r2r_ctd.state¶

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¶

`R2R_QC_VARNAME`	Variable name used within the state netCDF files a an attribute key-value container.
`logger`

Classes¶

`NamedBytes`	bytes object that has a name string property
`CheckFunc`	Base class for protocol classes.

Functions¶

`write_ds_r2r`(→ None)	Given a Dataset, serialize it to the path contained on the `__path` global attribute.
`get_state_path`(→ pathlib.Path)	Given a breakout and hex_path in that breakout, calculate what the state path would be
`get_qa_dir`(→ pathlib.Path)	Determine the directory path used for QA output files, creating it if necessary.
`get_xml_qa_path`(→ pathlib.Path)	Get the path of where to write the QA XML report.
`get_geoCSV_path`(→ pathlib.Path)	Get the path of where to write the geoCSV file.
`get_config_path`(→ pathlib.Path)	Get the directory for writing the seabird configuration report files, creating it if necessary
`get_product_path`(→ pathlib.Path)	Get the directory to write the cnv product files to, creating it if necessary.
`get_filename`(→ str)	Gets the `filename` attribute of a DataArray object that represents a file.
`initialize_or_get_state`(→ xarray.Dataset)	Given a hex_path, get the state as an xarray Dataset
`get_or_write_derived_file`(ds, key, func, **kwargs)	Get a derived file either from the state, or from the result of the callable func.
`get_or_write_check`(→ bool)	Get or determine and write the boolean result of func

Module Contents¶

r2r_ctd.state.R2R_QC_VARNAME = '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.

r2r_ctd.state.logger¶

class r2r_ctd.state.NamedBytes¶

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

name: str¶

class r2r_ctd.state.CheckFunc¶

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

__call__(ds: xarray.Dataset, *args: Any, **kwargs: Any) → bool¶

r2r_ctd.state.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 initialize_or_get_state() on read in.

r2r_ctd.state.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

r2r_ctd.state.get_qa_dir(breakout: r2r_ctd.breakout.Breakout) → pathlib.Path¶: Determine the directory path used for QA output files, creating it if necessary.

r2r_ctd.state.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

r2r_ctd.state.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.

r2r_ctd.state.get_config_path(breakout: r2r_ctd.breakout.Breakout) → pathlib.Path¶: Get the directory for writing the seabird configuration report files, creating it if necessary

r2r_ctd.state.get_product_path(breakout: r2r_ctd.breakout.Breakout) → pathlib.Path¶: Get the directory to write the cnv product files to, creating it if necessary.

r2r_ctd.state.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

r2r_ctd.state.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 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 write_ds_r2r() when the Dataset is serialized.

r2r_ctd.state.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 InvalidSBEFileError and also skips calling func returning None instead.

r2r_ctd.state.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 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.