.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/grp1_ArrSchema/plot_e00_making_schema.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_grp1_ArrSchema_plot_e00_making_schema.py: Defining ArraySchema and AnnotatedArray's ========================================= ArraySchema are dictionary objects that describe the requirements of an array structure. AnnotatedArray are xarray.DataArray's that are expected to conform to a given ArraySchema - subclasses of xarray.DataArray. .. GENERATED FROM PYTHON SOURCE LINES 10-14 .. code-block:: Python import rmellipse as rme .. GENERATED FROM PYTHON SOURCE LINES 15-20 Defining AnnotatedArrays ------------------------ There are 2 required fields in a schema. The first is a shape and the second is a dimension specification. .. GENERATED FROM PYTHON SOURCE LINES 20-29 .. code-block:: Python class Array2x2(rme.AnnotatedArray): schema = rme.ArraySchema( shape=(2, 2), dims=('row', 'column'), ) .. GENERATED FROM PYTHON SOURCE LINES 30-34 Dimension and shape specifiers can also be alphabetical letters (lower or upper case) that indicate arbitrary dimensionality. If two specifiers are the same letter, that indicates they are the same shape. For example, a stack of square matrices might be defined as .. GENERATED FROM PYTHON SOURCE LINES 34-43 .. code-block:: Python class ArrayMxNxN(rme.AnnotatedArray): schema = rme.ArraySchema( shape=('M', 'N', 'N'), dims=('page', 'row', 'column'), ) .. GENERATED FROM PYTHON SOURCE LINES 44-49 It's possible to define arbitary dimensionality or shape with ellipses. For example, the following schema is an array of arbitary leading dimensions ending in an NxN shape of rows and columns. If the shape is arbitary, then so are the dimension names in the same position. There can be only a single arbitrary specifier. So (...,'N') is okay but (...,'N',...) is not. .. GENERATED FROM PYTHON SOURCE LINES 49-58 .. code-block:: Python class ArrayLeadingNxN(rme.AnnotatedArray): schema = rme.ArraySchema( shape=(..., 'N', 'N'), dims=(..., 'row', 'column'), ) .. GENERATED FROM PYTHON SOURCE LINES 59-66 Data Types ---------- By default, an ArraySchema has no dtype specifier (None) but one can be provided to identity what kind of data is expected in the values of the DataArray. An array is considered valid to a schema it it can be casted into that schema's dtype using the numpy.can_cast() function. .. GENERATED FROM PYTHON SOURCE LINES 66-72 .. code-block:: Python class Array2x2Float(rme.AnnotatedArray): schema = rme.ArraySchema(shape=(2, 2), dims=('row', 'column'), dtype=float) .. GENERATED FROM PYTHON SOURCE LINES 73-78 Coordinates ----------- You can specify the expected coordinates of an AnnotatedArray by including a coords field with a CoordinateSchema. .. GENERATED FROM PYTHON SOURCE LINES 78-86 .. code-block:: Python class TimeDomainArray(rme.AnnotatedArray): schema = rme.ArraySchema( shape=('N',), dims=('time',), coords={'time': rme.CoordinateSchema(dtype=float)} ) .. GENERATED FROM PYTHON SOURCE LINES 87-89 If an array has a fixed dimension shape and coordinates, you can define the coordinate values by supplying values to the coordinate field. .. GENERATED FROM PYTHON SOURCE LINES 89-103 .. code-block:: Python class TimeDomainArray2x2(rme.AnnotatedArray): schema = rme.ArraySchema( shape=('N', 2, 2), dims=('time', 'row', 'col'), coords={ 'time': rme.CoordinateSchema(dtype=float), 'row': rme.CoordinateSchema(dtype=int, values=[0, 1]), 'col': rme.CoordinateSchema(dtype=int, values=[0, 1]), }, ) .. GENERATED FROM PYTHON SOURCE LINES 104-111 Units ----- By default the units field is None (which means no specified units, not unitless). If your array contains values of a physical unit, it can be supplied as a string in the units field. This can be provided to both the array values themselves, and to individual coordinates. .. GENERATED FROM PYTHON SOURCE LINES 111-122 .. code-block:: Python class TimeDomainVoltage(rme.AnnotatedArray): schema = rme.ArraySchema( shape=('N',), dims=('time',), units='V', coords={'time': rme.CoordinateSchema(dtype=float, units='s')}, ) .. GENERATED FROM PYTHON SOURCE LINES 123-133 Metadata -------- Metadata on xarray.DataArrays (and consequently AnnotatedArrays) are stored in the attrs attribute as a dictionary. If your data model is expecting specific structures of metadata, those can be defined using Pydantic datamodels. For example, you may be making a system that records DC measurments, and want to require that operator, temperature, and source current metadata fields are always present. It's strongly recommended that extra metadata fields be allowed as well. .. GENERATED FROM PYTHON SOURCE LINES 133-153 .. code-block:: Python from pydantic import BaseModel, ConfigDict class DCMeasurementMetadata(BaseModel): # Enable extra fields model_config = ConfigDict(extra='allow') operator: str temperature_celcius: float source_current_amps: float class TimeDomainVoltageWithMetadata(rme.AnnotatedArray): schema = rme.ArraySchema( shape=('N',), dims=('time',), units='V', coords={'time': rme.CoordinateSchema(dtype=float, units='s')}, attrs=DCMeasurementMetadata, ) .. _sphx_glr_download_auto_examples_grp1_ArrSchema_plot_e00_making_schema.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_e00_making_schema.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_e00_making_schema.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_e00_making_schema.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_