rmellipse.arrschema =================== .. py:module:: rmellipse.arrschema Exceptions ---------- .. autoapisummary:: rmellipse.arrschema.ValidationError Classes ------- .. autoapisummary:: rmellipse.arrschema.AnnotatedArray rmellipse.arrschema.ArraySchema rmellipse.arrschema.CoordinateSchema Package Contents ---------------- .. py:class:: AnnotatedArray(*args, **kwargs) Bases: :py:obj:`xarray.DataArray` Extension of xr.DataArray that is expected to conform to a specific schema. Schema is defined by an ArraySchema class. .. py:attribute:: schema :type: ArraySchema .. py:method:: validate() Validate array data against the schema of this type. .. py:method:: from_dataarray(array: xarray.DataArray) -> Self :classmethod: Cast an array into an annotated array. :param array: Array that can be cast into this format. :type array: xr.DataArray :returns: New array. :rtype: Self .. py:method:: zeros(attrs: Mapping | None = None, **coords: numpy.ndarray | xarray.DataArray) -> AnnotatedArray :classmethod: Generate an empty array of zeros based on the schema. If extra coordinates are supplied they will be inserted at the first arbitrary dimension specificier in the AnnotatedArray's schema ('...'). Coordinates with set values can be ignored, and will be automatically inserted. Zero array is initialized with numpy.zeros. :param attrs: Provided metadata to instantiate the AnnotatedArray with. The values in the supplied metadata are shallow copied onto the instantiated AnnotatedArrays's attrs. :type attrs: Mapping | None = None :param \*\*coords: KeyValue pairs of coordinates. Must include the required coordinates of the AnnotatedArray. :type \*\*coords: np.ndarray | xr.DataArray :returns: Array with supplied coordinates that conforms to the schema. :rtype: AnnotatedArray :raises KeyError: DESCRIPTION. .. py:method:: zeros_from(prototype: AnnotatedArray, drop_dims: list[str] | None = None, rename_dims: Mapping | None = None, use_coords: Mapping | None = None, reorder: bool = True, validate: bool = True, attrs: Mapping | None = None, **coords) -> AnnotatedArray :classmethod: Generate a new zeros array based on a prototype array. Dimensions that are mapped from the prototype array to the output array are cast into the correct type. Otherwise, dimensions are inserted in the expected place. :param prototype: Array to base the new array off of. :type prototype: AnnotatedArray :param drop_dims: Drop these dimensions. The default is None. :type drop_dims: list[str], optional :param rename_dims: Mapping of dimensions on the prototype array that should be converted to dimensions of this type of array. The default is None. :type rename_dims: Mapping | dict, optional :param use_coords: Additional dimensions required for the new type, key is the dimension name and value is the new coordinate to use for that dimension. :type use_coords: Mapping | dict, optional :param reorder: Automatically try to reorder dimensions to conform to the specification. :type reorder: bool, optional :param validate: If true, validate after creation. Default is False :type validate: bool, optional :param attrs: If provided, supply metadata to be used as attributes. :type attrs: Mapping | dict, optional :param \*\*coords: Keyword version of use_coords. Is merged with ontop of use_coords. :type \*\*coords: Mapping | None, optional :returns: **zeros** -- Zeros array in the new format. :rtype: AnnotatedArray .. py:class:: ArraySchema(shape: tuple[str | int | types.EllipsisType, Ellipsis], dims: tuple[str | types.EllipsisType, Ellipsis], dtype: type | None = None, units: str | None = None, coords: Mapping = {}, attrs: pydantic.BaseModel = None) Bases: :py:obj:`dict` Specialized dict subclass to describe the shape an array. Initialize an ArraySchema. :param shape: Shape of structure. Ellipses indicate arbitrary dimensions, letters indicate a required dimension of unknown length, and integers indicate a required dimension of a required length. :type shape: tuple[str | int | EllipsisType, ...] :param dims: Names assigned to dimensions specified by shape. Any required dimension must be names, and arbitrary dimensions must also be ellipses. :type dims: tuple[str | EllipsisType, ...] :param dtype: Type must be parseable by numpy's dtype (e.g. f8, c8, u8, etc). None means no datatype requriement, can be Any. :type dtype: type | None :param units: Mapping of units to the array structure. :type units: Mapping, optional :param coords: Mapping of required dimensions to a coordinate space. Must provide at least a dtype and a single unit as a string. Optionally, if the coordinates are fixed (i.e. the row and column indices of stacks of 2-d matrices) then you may specify those coordinates here. :type coords: Mapping, optional :param attrs_schema: JSON Schema for validating metadata attributes. :type attrs_schema: mapping, optional :returns: Dictionary conforming to an arrschema specification. :rtype: dict :raises Exception: If some logical inconsistency or is found, or the provided schema doesn't follow the specification for an array schema. .. py:method:: validate(arr: AnnotatedArray, attach_schema: bool = True) Test if array conforms to schema. :param arr: Array to check. :type arr: AnnotatedArray :param attach_schema: If True, the schema is dumped into a string and attatched to the attrs of the input data array. The default is True. :type attach_schema: bool, optional :raises ValidationError: If a discrepancy is found between the data and the schema. :rtype: None. .. py:class:: CoordinateSchema(values: list | None = None, dtype: type | None = None, units: str | None = None) Bases: :py:obj:`dict` dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2) Initialize self. See help(type(self)) for accurate signature. .. py:exception:: ValidationError(*args, **kwargs) Bases: :py:obj:`Exception` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature.