r2r_ctd.state ============= .. py:module:: r2r_ctd.state .. autoapi-nested-parse:: Functions for manipulating the state netCDF files and getting paths for derived files. Anything that modifies the state must go though functions contained here. This module also contains a bunch of functions that calculate where output files should go. Attributes ---------- .. autoapisummary:: r2r_ctd.state.R2R_QC_VARNAME r2r_ctd.state.logger Classes ------- .. autoapisummary:: r2r_ctd.state.NamedBytes r2r_ctd.state.CheckFunc Functions --------- .. autoapisummary:: r2r_ctd.state.write_ds_r2r r2r_ctd.state.get_state_path r2r_ctd.state.get_qa_dir r2r_ctd.state.get_xml_qa_path r2r_ctd.state.get_geoCSV_path r2r_ctd.state.get_config_path r2r_ctd.state.get_product_path r2r_ctd.state.get_filename r2r_ctd.state.initialize_or_get_state r2r_ctd.state.get_or_write_derived_file r2r_ctd.state.get_or_write_check Module Contents --------------- .. py:data:: R2R_QC_VARNAME :value: 'r2r_qc' Variable name used within the state netCDF files a an attribute key-value container. This is done to keep all the qa result contained instead of e.g. prefixing attribute names and having everything as a global attribute. .. py:data:: logger .. py:class:: NamedBytes Bases: :py:obj:`bytes` bytes object that has a name string property This is for passing around files with their names internally. The instance objects are "fragile" in that the name property will get dropped on any operation that returns a new bytes object (which is most of them). >>> b = NamedBytes(b'hello world', name="example.txt") >>> b b'hello world' >>> b.name 'example.txt' .. py:attribute:: name :type: str .. py:class:: CheckFunc Bases: :py:obj:`Protocol` Base class for protocol classes. Protocol classes are defined as:: class Proto(Protocol): def meth(self) -> int: ... Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing). For example:: class C: def meth(self) -> int: return 0 def func(x: Proto) -> int: return x.meth() func(C()) # Passes static type check See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:: class GenProto[T](Protocol): def meth(self) -> T: ... .. py:method:: __call__(ds: xarray.Dataset, *args: Any, **kwargs: Any) -> bool .. py:function:: write_ds_r2r(ds: xarray.Dataset) -> None Given a Dataset, serialize it to the path contained on the ```__path``` global attribute. The ``__path`` attribute is not serialized, but rather added by the :py:func:`initialize_or_get_state` on read in. .. py:function:: get_state_path(breakout: r2r_ctd.breakout.Breakout, hex_path: pathlib.Path) -> pathlib.Path Given a breakout and hex_path in that breakout, calculate what the state path would be .. py:function:: get_qa_dir(breakout: r2r_ctd.breakout.Breakout) -> pathlib.Path Determine the directory path used for QA output files, creating it if necessary. .. py:function:: get_xml_qa_path(breakout: r2r_ctd.breakout.Breakout) -> pathlib.Path Get the path of where to write the QA XML report. This is the same name as the template, but with xml instead of xmlt .. py:function:: get_geoCSV_path(breakout: r2r_ctd.breakout.Breakout) -> pathlib.Path Get the path of where to write the geoCSV file. This is the same name as the XML template, but with _ctd_metdata.geoCSV ``_ctd_metdata.geoCSV`` suffix rather than ``_qa.2.0.xmlt``. .. py:function:: get_config_path(breakout: r2r_ctd.breakout.Breakout) -> pathlib.Path Get the directory for writing the seabird configuration report files, creating it if necessary .. py:function:: get_product_path(breakout: r2r_ctd.breakout.Breakout) -> pathlib.Path Get the directory to write the cnv product files to, creating it if necessary. .. py:function:: get_filename(da: xarray.DataArray) -> str Gets the ``filename`` attribute of a DataArray object that represents a file. This is mostly use as sugar for type casting to a string .. py:function:: initialize_or_get_state(breakout: r2r_ctd.breakout.Breakout, hex_path: pathlib.Path) -> xarray.Dataset Given a hex_path, get the state as an xarray Dataset This will either find the existing netCDF file and open it (not load) or make a new state Dataset by calling :py:func:`odf.sbe.read_hex` on that path. This adds an attribute to the dataset ``__path`` that is used to keep track of where this file is actually written. This attribute is stripped by :py:func:`write_ds_r2r` when the Dataset is serialized. .. py:function:: get_or_write_derived_file(ds: xarray.Dataset, key: str, func: collections.abc.Callable, **kwargs) Get a derived file either from the state, or from the result of the callable func. This function is used to store create and store the instrument configuration reports and cnv files. The callable ``func`` will be passed the dataset ``ds`` as the first argument and any extra ``kwargs``. The ``ds`` will be checked for ``key`` before ``func`` is called and if present, those contents will be returned and ``func`` will not be called. If ``func`` returns a dictionary mapping of keys to DataArrays, then ``key`` must be one of the keys in that dict. All keys in the mapping will be stored on ds. This function also checks if the callable raises an :py:class:`InvalidSBEFileError` and also skips calling ``func`` returning None instead. .. py:function:: get_or_write_check(ds: xarray.Dataset, key: str, func: CheckFunc, **kwargs) -> bool Get or determine and write the boolean result of `func` The callable ``func`` will be passed the dataset ``ds`` as the first argument and any extra ``kwargs``. ``func`` must return a boolean value which will then be stored on ``ds`` in the attributes a special variable :py:obj:`R2R_QC_VARNAME`. This object simply serves as a container for these results. .. note:: netCDF doesn't have a boolean data type, so these checks are stored as literal 1 or 0 inside the state file.