vectorose.io

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

DEFAULT_LOCATION_COLUMNS	Default column numbers for the location coordinates in the order
DEFAULT_COMPONENT_COLUMNS	Default column numbers for the vector components in the order

Classes

VectorFileType	File types for numeric data.
ImageFileType	Image File Types.
VideoFileType	Video File Types.

Functions

__infer_filetype_from_filename(→ Optional[enum.Enum])	Infer a file type from a filename.
__infer_vector_filetype_from_filename(...)	Infer a vector field file type from a filename.
__infer_video_filetype_from_filename(...)	Infer a video file type from a filename.
import_vector_field(→ Optional[numpy.ndarray])	Import a vector field.
export_mpl_animation(animation, filename[, file_type, ...])	Export a Matplotlib animation.

Module Contents

vectorose.io.DEFAULT_LOCATION_COLUMNS = (0, 1, 2)

Default column numbers for the location coordinates in the order (x, y, z).

vectorose.io.DEFAULT_COMPONENT_COLUMNS

Default column numbers for the vector components in the order (vx, vy, vz).

class vectorose.io.VectorFileType

Bases: 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.

CSV = 'csv'

NPY = 'npy'

EXCEL = 'xlsx'

class vectorose.io.ImageFileType

Bases: 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.

PNG = 'png'

TIFF = 'tiff'

SVG = 'svg'

PDF = 'pdf'

class vectorose.io.VideoFileType

Bases: 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.

MP4 = 'mp4'

GIF = 'gif'

vectorose.io.__infer_filetype_from_filename(filename: str, file_type_enum: Type[enum.Enum]) → enum.Enum | None

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.

Parameters:

• filename – String containing the filename.

• 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:

file_type_enum or None – Member of file_type_enum if a valid file type is found. Otherwise, None.

See also

ImageFileType

Sample enumerated types to pass in for image files.

VectorFileType

Sample enumerated types for vector data files.

vectorose.io.__infer_vector_filetype_from_filename(filename: str) → VectorFileType | None

Infer a vector field file type from a filename.

This function tries to infer a VectorFileType from a provided filename by checking the extension. If no valid extension is found, None is returned. Otherwise, the determined vector type is returned.

Parameters:

filename – String containing the filename.

Returns:

VectorFileType or None – Vector file type corresponding to the filename if a valid filetype is found. Otherwise, None.

vectorose.io.__infer_video_filetype_from_filename(filename: str) → VideoFileType | None

Infer a video file type from a filename.

This function tries to infer a VideoFileType from a provided filename by checking the extension. If no valid extension is found, None is returned. Otherwise, the determined vector type is returned.

Parameters:

filename – String containing the filename.

Returns:

VideoFileType or None – Video file type corresponding to the filename if a valid filetype is found. Otherwise, None.

vectorose.io.import_vector_field(filepath: str, default_file_type: VectorFileType = VectorFileType.NPY, contains_headers: bool = False, sheet: str | int | None = None, location_columns: Sequence[int] | None = DEFAULT_LOCATION_COLUMNS, component_columns: Sequence[int] = DEFAULT_COMPONENT_COLUMNS, component_axis: int = -1, separator: str = '\t') → numpy.ndarray | None

Import a vector field.

Load a vector field from a file into a NumPy array. For available file formats, see 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 None is returned.

Parameters:

• filepath – File path to the vector field file.

• default_file_type – File type to attempt if the type cannot be inferred from the filename.

• contains_headers – Indicate whether the file contains headers. This option is only considered if the vectors are in a CSV or Excel file.

• sheet – Name or index of the sheet to consider if the vectors are in an Excel file.

• location_columns – Column indices for the vector spatial coordinates in the order (x, y, z). If this is set to 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.

• 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).

• component_axis – Axis along which the components are defined, in the case of a NumPy array which has more than 2 dimensions.

• separator – Column separator to use if the vector field is a CSV file.

Returns:

numpy.ndarray or 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.

• ValueError – The requested file cannot be parsed.

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.

vectorose.io.export_mpl_animation(animation: matplotlib.animation.Animation, filename: str, file_type: VideoFileType = VideoFileType.MP4, dpi: int | None = 150, fps: int | None = None, **export_kwargs: Dict[str, Any])

Export a Matplotlib animation.

Export a provided Matplotlib animation as a video.

Parameters:

• animation – The matplotlib.animation.Animation animation to export.

• filename – The destination for the video export. This filename will be used to infer the export file type.

• file_type – The default filetype to consider if unable to resolve the file type from the file name.

• dpi – Resolution of the exported video in dots-per-inch (DPI).

• fps – Desired frame rate in the exported video.

• export_kwargs – Additional keyword arguments to matplotlib.animation.Animation.save().

See also

matplotlib.animation.Animation.save

The function called to perform the actual export.