axsdb¶

Submodules:

`interpolation`	Fast xarray interpolation.
`math`	Fast interpolation with Numba.
`units`	Unit handling components, based on the Pint library.

Database classes

`AbsorptionDatabase`(dir_path, index[, ...])	Common parent type for absorption coefficient databases.
`MonoAbsorptionDatabase`(dir_path, index[, ...])	Absorption coefficient database (monochromatic variant).
`CKDAbsorptionDatabase`(dir_path, index[, ...])	Absorption coefficient database (CKD variant).

Database factory

AbsorptionDatabaseFactory()

This factory instantiates AbsorptionDatabase subclasses given a name.

Error handling

`get_error_handling_config`()	Retrieve the current global default error handling configuration.
`set_error_handling_config`(value)	Set the global default error handling configuration.
`ErrorHandlingConfiguration`([x, p, t])	Error handling configuration.
`ErrorHandlingPolicy`(missing, scalar, bounds)	Error handling policy for a single coordinate.
`ErrorHandlingAction`(value)	Error handling action descriptors.
`BoundsPolicy`([action, mode, fill_value])	Policy for handling out-of-bounds values on one side (lower or upper).
`BoundsMode`(value)	Bounds policy mode descriptors.

Database classes¶

class axsdb.AbsorptionDatabase(dir_path, index: DataFrame, spectral_coverage: DataFrame = (_CountingAttr(counter=38, _default=NOTHING, repr=False, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}),), metadata: dict = NOTHING, lazy: bool = False, cache: LRUCache = NOTHING, error_handling_config=None)[source]¶

Bases: object

Common parent type for absorption coefficient databases.

This class implements most of the data indexing logic common to all absorption coefficient databases. A database is composed of a set of NetCDF files compliant with the absorption coefficient database format specification and placed in the same directory. A database instance is initialized by specifying the path to the directory where the files are stored.

If it exists, a metadata.json file is loaded into the metadata attribute.

Databases are usually not initialized using the constructor, but rather using the class method constructors from_directory() and from_dict().

Parameters:

dir_path (path-like) – Path to database root directory.
index (DataFrame) – File index, assumed sorted by ascending wavelengths.
spectral_coverage (DataFrame) – Dataframe that unrolls the spectral information contained in all data files in the database.
metadata (dict, optional) – Dictionary that contains the database metadata.
cache (cachetools.LRUCache, optional) – A mapping that implements an LRU caching policy.
error_handling_config (ErrorHandlingConfiguration or dict, optional) – Default error handling policy. If unset, a global default is used.

Notes

A file index, stored as the _index private attribute, associates to each file the spectral region it covers. The index is preferably loaded from a CSV file that contains all this information; if it is not found, the table is built upon database initialization and saved to the database directory. The indexing step requires to access all files and may take a while. The file index table is used during queries to select efficiently the file where data will be read. For convenience, information about bounds contained in the index is assembled into a spectral mesh suitable for query using numpy.digitize() and stored in the _chunks dictionary.

A spectral coverage table, stored as the _spectral_coverage private attribute, merges the spectral coordinates of all files into a consistent index. This table is used to provide spectral coverage information to higher-level components that drive the simulation. Table contents are preferably loaded from a CSV file; if it is not found, the table is build upon database initialization and saved to the database directory. This indexing step also requires to access all files and may take a while.

Database access and memory usage can be controlled through two parameters:

File queries are stored in an LRU cache. The initial size is set to a low value (8) and should be appropriate for most situations. If more cache control is needed, the cache_clear(), cache_close() and cache_reset() methods can be used.
Datasets can be open with an eager or lazy approach. This behaviour is controlled using the lazy constructor parameter. In eager mode, the entire file used for a query is loaded into memory. This can bring significant access overhead when using large files. If desired, datasets can instead be open lazily, triggering disk access only for the specific data that are used.

Methods:

`cache_clear`()	Clear the cache.
`cache_close`()	Close all cached datasets.
`cache_reset`(maxsize)	Reset the cache with the specified maximum size.
`convert`(value, mode)	Attempt conversion of a value to an absorption database.
`eval_sigma_a_ckd`(w, g, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant).
`eval_sigma_a_mono`(w, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant).
`from_dict`(value)	Construct from a dictionary.
`from_directory`(dir_path[, lazy, fix, ...])	Initialize a CKD database from a directory that contains one or several datasets.
`lookup_datasets`(**kwargs)	Perform a dataset lookup based on the requested spectral coordinate.
`lookup_filenames`(**kwargs)	Look up a filename in the index table from the coordinate values passed as keyword arguments.

Attributes:

`dir_path`	Database root path.
`error_handling_config`	Default error handling policy.
`lazy`	if `True`, load data lazily; else, load data eagerly.
`load_dataset`(args, *kwargs)
`metadata`	Database metadata.
`spectral_coverage`	Spectral coverage table.

cache_clear() → None[source]¶: Clear the cache.

cache_close() → None[source]¶: Close all cached datasets.

cache_reset(maxsize: int) → None[source]¶: Reset the cache with the specified maximum size.

static convert(value: Any, mode: Literal['mono', 'ckd']) → AbsorptionDatabase[source]¶

Attempt conversion of a value to an absorption database.

Parameters:

value – The value for which conversion is attempted.
mode ({"mono", "ckd"}) – Mode router to the desired database type.

Return type:

MonoAbsorptionDatabase or CKDAbsorptionDatabase

Notes

Conversion rules are as follows:

If value is a string or a path, try converting using the from_directory() constructor. The returned type is consistent with the active mode.
If value is a dict, try converting using the from_dict() constructor. The returned type is consistent with the active mode.
Otherwise, do not convert.

property dir_path: Path¶: Database root path.

property error_handling_config: ErrorHandlingConfiguration¶: Default error handling policy. If unset, the global default is used.

eval_sigma_a_ckd(w: Quantity, g: float, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray[source]¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
g (float) – The g-point for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

eval_sigma_a_mono(w: Quantity, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray[source]¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

classmethod from_dict(value: dict) → AbsorptionDatabase[source]¶

Construct from a dictionary. The dictionary has a required entry "construct" that specifies the constructor that will be used to instantiate the database. Additional entries are keyword arguments passed to the selected constructor.

Parameters:: value (dict) – Converted value.
Return type:: AbsorptionDatabase

classmethod from_directory(dir_path: PathLike, lazy: bool = False, fix: bool = True, error_handling_config: ErrorHandlingConfiguration | None = None) → AbsorptionDatabase[source]¶

Initialize a CKD database from a directory that contains one or several datasets.

Parameters:

dir_path (path-like) – Path where the CKD database is located.
lazy (bool, default: False) – Access mode switch: if True, load data lazily; else, load data eagerly.
fix (bool, default: True) – If True, attempt generating missing index files upon initialization. Otherwise, raise if they are missing.

Return type:

AbsorptionDatabase

Raises:

NotADirectoryError – If dir_path does not point to an existing directory.
FileNotFoundError – If an index file is missing and fix is False.

lazy: bool¶

if True, load data lazily; else, load data eagerly.

Type:: Access mode switch

load_dataset(*args, **kwargs) = <cachetools._cachedmethod._unlocked.<locals>.Descriptor.Wrapper object>[source]¶

lookup_datasets(**kwargs) → list[Dataset][source]¶: Perform a dataset lookup based on the requested spectral coordinate. See lookup_filenames() for the accepted arguments.

lookup_filenames(**kwargs) → list[str][source]¶

Look up a filename in the index table from the coordinate values passed as keyword arguments.

Parameters:

wl (quantity or array-like, optional) – Wavelength (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavelength chunk bounds.
wn (quantity or array-like, optional) – Wavenumber (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavenumber chunk bounds.

Returns:

filenames – Names of the successfully looked up files, relative to the database root directory.

Return type:

list of str

Raises:

ValueError – If the requested spectral coordinate is out of bounds.

Notes

Depending on the specified keyword argument (wl or wn), the lookup will be performed in wavelength or wavenumber mode. Both are equivalent.

property metadata: dict¶: Database metadata.

property spectral_coverage: DataFrame¶: Spectral coverage table.

class axsdb.MonoAbsorptionDatabase(dir_path, index: DataFrame, spectral_coverage: DataFrame = (_CountingAttr(counter=38, _default=NOTHING, repr=False, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}),), metadata: dict = NOTHING, lazy: bool = False, cache: LRUCache = NOTHING, error_handling_config=None)[source]¶

Bases: AbsorptionDatabase

Absorption coefficient database (monochromatic variant).

Methods:

`cache_clear`()	Clear the cache.
`cache_close`()	Close all cached datasets.
`cache_reset`(maxsize)	Reset the cache with the specified maximum size.
`convert`(value, mode)	Attempt conversion of a value to an absorption database.
`eval_sigma_a_ckd`(w, g, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant).
`eval_sigma_a_mono`(w, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant).
`from_dict`(value)	Construct from a dictionary.
`from_directory`(dir_path[, lazy, fix, ...])	Initialize a CKD database from a directory that contains one or several datasets.
`lookup_datasets`(**kwargs)	Perform a dataset lookup based on the requested spectral coordinate.
`lookup_filenames`(**kwargs)	Look up a filename in the index table from the coordinate values passed as keyword arguments.

Attributes:

`dir_path`	Database root path.
`error_handling_config`	Default error handling policy.
`lazy`	if `True`, load data lazily; else, load data eagerly.
`load_dataset`(args, *kwargs)
`metadata`	Database metadata.
`spectral_coverage`	Spectral coverage table.

cache_clear() → None¶: Clear the cache.

cache_close() → None¶: Close all cached datasets.

cache_reset(maxsize: int) → None¶: Reset the cache with the specified maximum size.

static convert(value: Any, mode: Literal['mono', 'ckd']) → AbsorptionDatabase¶

Attempt conversion of a value to an absorption database.

Parameters:

value – The value for which conversion is attempted.
mode ({"mono", "ckd"}) – Mode router to the desired database type.

Return type:

MonoAbsorptionDatabase or CKDAbsorptionDatabase

Notes

Conversion rules are as follows:

If value is a string or a path, try converting using the from_directory() constructor. The returned type is consistent with the active mode.
If value is a dict, try converting using the from_dict() constructor. The returned type is consistent with the active mode.
Otherwise, do not convert.

property dir_path: Path¶: Database root path.

property error_handling_config: ErrorHandlingConfiguration¶: Default error handling policy. If unset, the global default is used.

eval_sigma_a_ckd(w: Quantity, g: float, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
g (float) – The g-point for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

eval_sigma_a_mono(w: Quantity, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray[source]¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

classmethod from_dict(value: dict) → MonoAbsorptionDatabase[source]¶

Parameters:: value (dict) – Converted value.
Return type:: AbsorptionDatabase

classmethod from_directory(dir_path: PathLike, lazy: bool = False, fix: bool = True, error_handling_config: ErrorHandlingConfiguration | None = None) → AbsorptionDatabase¶

Initialize a CKD database from a directory that contains one or several datasets.

Parameters:

dir_path (path-like) – Path where the CKD database is located.
lazy (bool, default: False) – Access mode switch: if True, load data lazily; else, load data eagerly.
fix (bool, default: True) – If True, attempt generating missing index files upon initialization. Otherwise, raise if they are missing.

Return type:

AbsorptionDatabase

Raises:

NotADirectoryError – If dir_path does not point to an existing directory.
FileNotFoundError – If an index file is missing and fix is False.

lazy: bool¶

if True, load data lazily; else, load data eagerly.

Type:: Access mode switch

load_dataset(*args, **kwargs) = <cachetools._cachedmethod._unlocked.<locals>.Descriptor.Wrapper object>¶

lookup_datasets(**kwargs) → list[Dataset]¶: Perform a dataset lookup based on the requested spectral coordinate. See lookup_filenames() for the accepted arguments.

lookup_filenames(**kwargs) → list[str]¶

Look up a filename in the index table from the coordinate values passed as keyword arguments.

Parameters:

wl (quantity or array-like, optional) – Wavelength (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavelength chunk bounds.
wn (quantity or array-like, optional) – Wavenumber (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavenumber chunk bounds.

Returns:

filenames – Names of the successfully looked up files, relative to the database root directory.

Return type:

list of str

Raises:

ValueError – If the requested spectral coordinate is out of bounds.

Notes

Depending on the specified keyword argument (wl or wn), the lookup will be performed in wavelength or wavenumber mode. Both are equivalent.

property metadata: dict¶: Database metadata.

property spectral_coverage: DataFrame¶: Spectral coverage table.

class axsdb.CKDAbsorptionDatabase(dir_path, index: DataFrame, spectral_coverage: DataFrame = (_CountingAttr(counter=38, _default=NOTHING, repr=False, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}),), metadata: dict = NOTHING, lazy: bool = False, cache: LRUCache = NOTHING, error_handling_config=None)[source]¶

Bases: AbsorptionDatabase

Absorption coefficient database (CKD variant).

Methods:

`cache_clear`()	Clear the cache.
`cache_close`()	Close all cached datasets.
`cache_reset`(maxsize)	Reset the cache with the specified maximum size.
`convert`(value, mode)	Attempt conversion of a value to an absorption database.
`eval_sigma_a_ckd`(w, g, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant).
`eval_sigma_a_mono`(w, thermoprops[, ...])	Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant).
`from_dict`(value)	Construct from a dictionary.
`from_directory`(dir_path[, lazy, fix, ...])	Initialize a CKD database from a directory that contains one or several datasets.
`lookup_datasets`(**kwargs)	Perform a dataset lookup based on the requested spectral coordinate.
`lookup_filenames`(**kwargs)	Look up a filename in the index table from the coordinate values passed as keyword arguments.

Attributes:

`dir_path`	Database root path.
`error_handling_config`	Default error handling policy.
`lazy`	if `True`, load data lazily; else, load data eagerly.
`load_dataset`(args, *kwargs)
`metadata`	Database metadata.
`spectral_coverage`	Spectral coverage table.

cache_clear() → None¶: Clear the cache.

cache_close() → None¶: Close all cached datasets.

cache_reset(maxsize: int) → None¶: Reset the cache with the specified maximum size.

static convert(value: Any, mode: Literal['mono', 'ckd']) → AbsorptionDatabase¶

Attempt conversion of a value to an absorption database.

Parameters:

value – The value for which conversion is attempted.
mode ({"mono", "ckd"}) – Mode router to the desired database type.

Return type:

MonoAbsorptionDatabase or CKDAbsorptionDatabase

Notes

Conversion rules are as follows:

If value is a string or a path, try converting using the from_directory() constructor. The returned type is consistent with the active mode.
If value is a dict, try converting using the from_dict() constructor. The returned type is consistent with the active mode.
Otherwise, do not convert.

property dir_path: Path¶: Database root path.

property error_handling_config: ErrorHandlingConfiguration¶: Default error handling policy. If unset, the global default is used.

eval_sigma_a_ckd(w: Quantity, g: float, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray[source]¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (CKD variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
g (float) – The g-point for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

eval_sigma_a_mono(w: Quantity, thermoprops: Dataset, error_handling_config: ErrorHandlingConfiguration | None = None) → DataArray¶

Compute the absorption coefficient given spectral coordinates and a thermophysical profile (mono variant). The default implementation raises.

Parameters:

w (quantity) – The wavelength for which the absorption coefficient is evaluated.
thermoprops (Dataset) – The thermophysical profile for which the absorption coefficient is evaluated.
error_handling_config (ErrorHandlingConfiguration, optional) – The error handling policy applied if coordinates are missing, do not have the appropriate dimension or are out of the dataset’s bounds. If set, this overrides the configuration set in error_handling_config.

Returns:

A data array containing the evaluated absorption coefficient as a function of the spectral coordinate and altitude.

Return type:

DataArray

classmethod from_dict(value: dict) → CKDAbsorptionDatabase[source]¶

Parameters:: value (dict) – Converted value.
Return type:: AbsorptionDatabase

classmethod from_directory(dir_path: PathLike, lazy: bool = False, fix: bool = True, error_handling_config: ErrorHandlingConfiguration | None = None) → AbsorptionDatabase¶

Initialize a CKD database from a directory that contains one or several datasets.

Parameters:

dir_path (path-like) – Path where the CKD database is located.
lazy (bool, default: False) – Access mode switch: if True, load data lazily; else, load data eagerly.
fix (bool, default: True) – If True, attempt generating missing index files upon initialization. Otherwise, raise if they are missing.

Return type:

AbsorptionDatabase

Raises:

NotADirectoryError – If dir_path does not point to an existing directory.
FileNotFoundError – If an index file is missing and fix is False.

lazy: bool¶

if True, load data lazily; else, load data eagerly.

Type:: Access mode switch

load_dataset(*args, **kwargs) = <cachetools._cachedmethod._unlocked.<locals>.Descriptor.Wrapper object>¶

lookup_datasets(**kwargs) → list[Dataset]¶: Perform a dataset lookup based on the requested spectral coordinate. See lookup_filenames() for the accepted arguments.

lookup_filenames(**kwargs) → list[str]¶

Look up a filename in the index table from the coordinate values passed as keyword arguments.

Parameters:

wl (quantity or array-like, optional) – Wavelength (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavelength chunk bounds.
wn (quantity or array-like, optional) – Wavenumber (scalar or array, quantity or unitless). If passed as a unitless value, it is interpreted using the units of the wavenumber chunk bounds.

Returns:

filenames – Names of the successfully looked up files, relative to the database root directory.

Return type:

list of str

Raises:

ValueError – If the requested spectral coordinate is out of bounds.

Notes

Depending on the specified keyword argument (wl or wn), the lookup will be performed in wavelength or wavenumber mode. Both are equivalent.

property metadata: dict¶: Database metadata.

property spectral_coverage: DataFrame¶: Spectral coverage table.

Database factory

class axsdb.AbsorptionDatabaseFactory[source]¶

Bases: object

This factory instantiates AbsorptionDatabase subclasses given a name. Internally, a registry maps registered names to a matching database type, a path where its data is located, and default loading options.

Examples

Initialize a factory instance:

>>> factory = AbsorptionDatabaseFactory()

>>> factory.register(
...     name="nanockd", cls=CKDAbsorptionDatabase, path="~/Downloads/nanockd"
... )

Instantiate a database:

>>> factory.create("nanockd")  

Methods:

`create`(name, **kwargs)	Instantiate a database given its name using the `from_directory()` constructor.
`register`(name, cls, path[, kwargs])	Register a new database to the factory.

create(name: str, **kwargs) → AbsorptionDatabase[source]¶

Instantiate a database given its name using the from_directory() constructor.

Parameters:

name (str) – Name of a registered databased.
kwargs – Optional keyword arguments passed to the database constructor. These settings will override registered defaults.

Returns:

Created database instance.

Return type:

AbsorptionDatabase

register(name: str, cls: AbsorptionDatabaseT, path: Path | Callable, kwargs: dict[str, Any] | None = None) → None[source]¶

Parameters:

name (str) – A unique identifier for this entry.
cls (type) – The matching database type.
path (path-like or callable) – The path to the directory where database data are located. If the name is dynamic (e.g. resolved by Eradiate’s file resolver), a callable with signature f() -> Path | str can be passed.
kwargs (dict, optional) – Default loading options passed to the constructor when instantiating this database.

Examples

Simplest registration pattern:

>>> factory = AbsorptionDatabaseFactory()
>>> factory.register(
...     name="nanomono", cls=MonoAbsorptionDatabase, path="~/Data/nanomono"
... )

Get path dynamically from a callable:

>>> def path():
...     return "~/Data/nanomono"
>>> factory.register(
...     name="nanomono",
...     cls=MonoAbsorptionDatabase,
...     path=path,
... )

Add default keyword arguments:

>>> factory.register(
...     name="nanomono",
...     cls=MonoAbsorptionDatabase,
...     path="~/Data/nanomono",
...     kwargs={"lazy": True},
... )

Error handling¶

axsdb.get_error_handling_config() → ErrorHandlingConfiguration[source]¶

Retrieve the current global default error handling configuration.

Return type:: ErrorHandlingConfiguration

axsdb.set_error_handling_config(value: Mapping | ErrorHandlingConfiguration) → None[source]¶

Set the global default error handling configuration.

Parameters:: value (Mapping | ErrorHandlingConfiguration) – Error handling configuration.
Raises:: ValueError – If value cannot be converted to an ErrorHandlingConfiguration.

class axsdb.ErrorHandlingConfiguration(x=NOTHING, p=NOTHING, t=NOTHING)[source]¶

Bases: object

Error handling configuration.

Parameters:

x (ErrorHandlingPolicy, optional) – Error handling policy for species concentrations. If not provided, uses the global default.
p (ErrorHandlingPolicy, optional) – Error handling policy for pressure. If not provided, uses the global default.
t (ErrorHandlingPolicy, optional) – Error handling policy for temperature. If not provided, uses the global default.

Methods:

convert(value)

Convert a value to an ErrorHandlingConfiguration.

classmethod convert(value)[source]¶

Convert a value to an ErrorHandlingConfiguration.

Parameters:: value – Value to convert. Dictionaries values are passed as keyword arguments to the constructor.
Return type:: ErrorHandlingConfiguration

class axsdb.ErrorHandlingPolicy(missing: ErrorHandlingAction, scalar: ErrorHandlingAction, bounds)[source]¶

Bases: object

Error handling policy for a single coordinate.

Parameters:

missing (ErrorHandlingAction) – Action when coordinate is missing from dataset.
scalar (ErrorHandlingAction) – Action when coordinate dimension is scalar.
bounds (tuple[BoundsPolicy, BoundsPolicy]) – Policies for (lower_bound, upper_bound). Values are automatically converted by BoundsPolicy.convert(). A single value can be passed and will be interpreted as a symmetric case.

Methods:

convert(value)

Convert a value to an ErrorHandlingPolicy.

classmethod convert(value)[source]¶

Convert a value to an ErrorHandlingPolicy.

Parameters:

value –

Value to convert. Can be:

an ErrorHandlingPolicy instance (returned as-is).
a dict with keys missing, scalar, and bounds.

The bounds value is passed to _convert_bounds() and can be:
- a string/number/dict/BoundsPolicy (symmetric)
- a tuple of 2 BoundsPolicy instances
- a tuple of 2 numbers (fill values)
- a dict with lower and/or upper keys

Return type:

ErrorHandlingPolicy

Raises:

ValueError – If the value cannot be converted to an ErrorHandlingPolicy instance.

class axsdb.ErrorHandlingAction(value)[source]¶

Bases: Enum

Error handling action descriptors.

IGNORE = 'ignore'¶: Ignore the error.

RAISE = 'raise'¶: Raise the error.

WARN = 'warn'¶: Emit a warning.

class axsdb.BoundsPolicy(action: ErrorHandlingAction = ErrorHandlingAction.IGNORE, mode: BoundsMode = BoundsMode.FILL, fill_value: float | None = 0.0)[source]¶

Bases: object

Policy for handling out-of-bounds values on one side (lower or upper).

Parameters:

action (ErrorHandlingAction, default: IGNORE) – Whether to check/warn/raise on out-of-bounds values.
mode (BoundsPolicyMode, default: FILL) –
How to handle out-of-bounds values during interpolation.
- FILL: Use fill_value for out-of-bounds points.
- CLAMP: Clamp to nearest boundary value.
fill_value (float or None, default: 0.0) – Value to use when mode=FILL. None means NaN.

Methods:

convert(value)

Convert various inputs to BoundsPolicy.

classmethod convert(value)[source]¶

Convert various inputs to BoundsPolicy.

Parameters:

value –

Value to convert. Can be:

a BoundsPolicy instance (returned as-is).
a string "ignore", "warn", or "raise" (sets action).
a string "fill" or "clamp" (sets mode).
a numeric value (sets fill_value).
None (returns default policy).
a dict with keys: action, mode, fill_value.

Return type:

BoundsPolicy

Raises:

ValueError – If the value cannot be converted to a BoundsPolicy instance.

Examples

>>> BoundsPolicy.convert("ignore")
BoundsPolicy(action=<IGNORE>, mode=<FILL>, fill_value=0.0)
>>> BoundsPolicy.convert("clamp")
BoundsPolicy(action=<IGNORE>, mode=<CLAMP>, fill_value=0.0)
>>> BoundsPolicy.convert(0.5)
BoundsPolicy(action=<IGNORE>, mode=<FILL>, fill_value=0.5)
>>> BoundsPolicy.convert({"action": "warn", "fill_value": 1.0})
BoundsPolicy(action=<WARN>, mode=<FILL>, fill_value=1.0)
>>> BoundsPolicy.convert(None)
BoundsPolicy(action=<IGNORE>, mode=<FILL>, fill_value=0.0)

class axsdb.BoundsMode(value)[source]¶

Bases: Enum

Bounds policy mode descriptors.

CLAMP = 'clamp'¶: Clamp to nearest boundary value.

FILL = 'fill'¶: Use fill_value for out-of-bounds points.