vectorose.io ============ .. py:module:: vectorose.io .. autoapi-nested-parse:: Functions for import and export. This module provides the ability to load vector fields from file and save vector fields and vector rose histogram data. Attributes ---------- .. autoapisummary:: vectorose.io.DEFAULT_LOCATION_COLUMNS vectorose.io.DEFAULT_COMPONENT_COLUMNS Classes ------- .. autoapisummary:: vectorose.io.VectorFileType vectorose.io.ImageFileType vectorose.io.VideoFileType Functions --------- .. autoapisummary:: vectorose.io.__infer_filetype_from_filename vectorose.io.__infer_vector_filetype_from_filename vectorose.io.__infer_video_filetype_from_filename vectorose.io.import_vector_field vectorose.io.export_mpl_animation Module Contents --------------- .. py:data:: DEFAULT_LOCATION_COLUMNS :value: (0, 1, 2) Default column numbers for the location coordinates in the order ``(x, y, z)``. .. py:data:: DEFAULT_COMPONENT_COLUMNS Default column numbers for the vector components in the order ``(vx, vy, vz)``. .. py:class:: VectorFileType Bases: :py:obj:`enum.Enum` File types for numeric data. Numeric data may be imported and exported in a number of different formats. This enumerated type allows the user to specify which file type they would like to use to load or store numeric data, such as vector lists and binning arrays. The associated strings for each member are the file extension **without a dot**. :Members: * **CSV** -- Comma-separated value file, in which the columns will be separated by a tab "\t". File extension: ``*.csv``. * **NPY** -- NumPy array, which can easily be loaded into NumPy. File extension: ``*.npy``. * **EXCEL** -- Microsoft Excel spreadsheet (compatible with Excel 2007 or later). File extension: ``*.xlsx``. .. warning:: When constructing a filename using the members of this type, a dot ``(.)`` must be added. .. py:attribute:: CSV :value: 'csv' .. py:attribute:: NPY :value: 'npy' .. py:attribute:: EXCEL :value: 'xlsx' .. py:class:: ImageFileType Bases: :py:obj:`enum.Enum` Image File Types. File types for images. These include both raster formats (``*.png`` and ``*.tiff``) and vector formats (``*.svg`` and ``*.pdf``). The members of this enumerated type have as value the string extensions for the respective file types **without** the dot. :Members: * **PNG** -- Portable Network Graphics (png) image (raster). * **TIFF** -- Tagged Image File Format (tiff) image (raster). * **SVG** -- Scalable Vector Graphic (svg) image (vector). * **PDF** -- Portable Document Format (pdf) file (vector). .. warning:: When constructing a filename using the members of this type, a dot ``(.)`` must be added. .. py:attribute:: PNG :value: 'png' .. py:attribute:: TIFF :value: 'tiff' .. py:attribute:: SVG :value: 'svg' .. py:attribute:: PDF :value: 'pdf' .. py:class:: VideoFileType Bases: :py:obj:`enum.Enum` Video File Types. File types for videos and animations. The raw values for the members of this enumerated type correspond to the respective file extensions **without** a period. :Members: * **MP4** -- Moving Picture Experts Group (MPEG) 4 video format. * **GIF** -- Graphics Interchange Format animated image (regardless of whether you pronounce if G-IF or J-IF). .. warning:: When constructing a filename using the members of this type, a dot ``(.)`` must be added. .. py:attribute:: MP4 :value: 'mp4' .. py:attribute:: GIF :value: 'gif' .. py:function:: __infer_filetype_from_filename(filename: str, file_type_enum: Type[enum.Enum]) -> Optional[enum.Enum] Infer a file type from a filename. This function tries to infer a file type, of the provided enumerated type ``file_type_enum`` from a provided filename by checking the extension. If no valid extension is found, ``None`` is returned. Otherwise, the determined file type is returned. :param filename: String containing the filename. :param file_type_enum: Enumerated type representing the desired file type. This enumerated type should have string values representing various file extensions. These values **should not** contain a dot. :returns: :class:`file_type_enum` or :obj:`None` -- Member of ``file_type_enum`` if a valid file type is found. Otherwise, ``None``. .. seealso:: :obj:`ImageFileType` Sample enumerated types to pass in for image files. :obj:`VectorFileType` Sample enumerated types for vector data files. .. py:function:: __infer_vector_filetype_from_filename(filename: str) -> Optional[VectorFileType] Infer a vector field file type from a filename. This function tries to infer a :class:`VectorFileType` from a provided filename by checking the extension. If no valid extension is found, :class:`None` is returned. Otherwise, the determined vector type is returned. :param filename: String containing the filename. :returns: :class:`VectorFileType` or :obj:`None` -- Vector file type corresponding to the filename if a valid filetype is found. Otherwise, :class:`None`. .. py:function:: __infer_video_filetype_from_filename(filename: str) -> Optional[VideoFileType] Infer a video file type from a filename. This function tries to infer a :class:`VideoFileType` from a provided filename by checking the extension. If no valid extension is found, :class:`None` is returned. Otherwise, the determined vector type is returned. :param filename: String containing the filename. :returns: :class:`VideoFileType` or :obj:`None` -- Video file type corresponding to the filename if a valid filetype is found. Otherwise, :class:`None`. .. py:function:: import_vector_field(filepath: str, default_file_type: VectorFileType = VectorFileType.NPY, contains_headers: bool = False, sheet: Optional[Union[str, int]] = None, location_columns: Optional[Sequence[int]] = DEFAULT_LOCATION_COLUMNS, component_columns: Sequence[int] = DEFAULT_COMPONENT_COLUMNS, component_axis: int = -1, separator: str = '\t') -> Optional[numpy.ndarray] Import a vector field. Load a vector field from a file into a NumPy array. For available file formats, see :class:`VectorFileType`. The file type is inferred from the filename. If it cannot be inferred, the ``default_file_type`` is tried. If the vector field is not valid, then :class:`None` is returned. :param filepath: File path to the vector field file. :param default_file_type: File type to attempt if the type cannot be inferred from the filename. :param contains_headers: Indicate whether the file contains headers. This option is only considered if the vectors are in a CSV or Excel file. :param sheet: Name or index of the sheet to consider if the vectors are in an Excel file. :param location_columns: Column indices for the vector *spatial coordinates* in the order ``(x, y, z)``. If this is set to :class:`None`, the vectors are assumed to be located at the origin. By default, the first three columns are assumed to refer to ``(x, y, z)``, respectively. :param component_columns: Column indices referring to the vector *components* in the order ``(vx, vy, vz)``. By default, the last three columns ``(-3, -2, -1)`` are assumed to be the ``(vx, vy, vz)``. :param component_axis: Axis along which the components are defined, in the case of a NumPy array which has more than 2 dimensions. :param separator: Column separator to use if the vector field is a CSV file. :returns: :class:`numpy.ndarray` or :obj:`None` -- NumPy array containing the vectors. The array has shape ``(n, 3)`` or ``(n, 6)``, depending on whether the locations are included. The columns correspond to ``(x,y,z)`` coordinates of the location (if available), followed by ``(vx, vy, vz)`` components. If the filetype cannot be properly inferred, a value of ``None`` is returned instead. :raises OSError: The requested file does not exist. :raises ValueError: The requested file cannot be parsed. .. rubric:: Notes If the vector field file passed contains an array with a dimension > 2, then the components are assumed to be along the axis passed in the argument `component_axis` and the array will be flattened to 2D. .. py:function:: export_mpl_animation(animation: matplotlib.animation.Animation, filename: str, file_type: VideoFileType = VideoFileType.MP4, dpi: Optional[int] = 150, fps: Optional[int] = None, **export_kwargs: Dict[str, Any]) Export a Matplotlib animation. Export a provided Matplotlib animation as a video. :param animation: The :class:`matplotlib.animation.Animation` animation to export. :param filename: The destination for the video export. This filename will be used to infer the export file type. :param file_type: The default filetype to consider if unable to resolve the file type from the file name. :param dpi: Resolution of the exported video in dots-per-inch (DPI). :param fps: Desired frame rate in the exported video. :param export_kwargs: Additional keyword arguments to :meth:`matplotlib.animation.Animation.save`. .. seealso:: :obj:`matplotlib.animation.Animation.save` The function called to perform the actual export.