casys.utilities

Utility functions.

Functions

`nc_content`(paths[, show_vars, show_dims, ...])	List the content of netCDF files including its subgroups.
`open_grdataset`(paths[, group, sub_groups, ...])	Alternative function to xarray.open_mfdataset allowing to open a group with its dimensions even if included in a parent group.
`call_methods`(methods, item)	Call a list of methods on the provided item.
`check_class_equality`(reference, other, ...)	Check whether the provided classes have the same value for the given parameters.
`copy_doc`(copy_func)	Decorator allowing to copy the docstring of a function.
`dataset_align`(data, data_ref, index[, ...])	Align provided dataset's indexes with the reference dataset's ones.
`dataset_select_field`(data, field, limits)	Reduce a dataset by only keeping indexes respecting provided field limits.
`fix_limits`(values[, as_none])	Fix provided limits values by normalizing it.
`dates_to_int_days`(*, date_1, date_2)	Convert provided dates into an integer representing the date rounded to the day.
`dates_to_string_days`(*, date_1, date_2)	Convert provided dates into a string representing the time interval rounded to the day.
`get_from_context_dict`(context, key, name[, ...])	Get the requested element from the given context key.
`interval_step_to_number`(vmin, vmax, step)	Transform a splitting interval expressed as min, max, step to an interval expressed as min, max, number.
`kwargs_checker`(kwargs[, allowed_args, exception])	Check whether provided kwargs are allowed.
`method_caller`(method, cls_type)	Method caller factory.
`normalize_image_size`(values)	Normalize provided image size values.
`normalize_longitude`(longitudes)	Normalize the provided longitude to a [-180, 180[ range.
`normalize_path`(path)	Expand and normalize the provided path.
`periods_for_track`(indexer, start, end, exception)	Generate a period iterator fitting the requirements of the provided track.
`periods_from_indexer`(indexer, start, end, ...)	Generate a period iterator over the provided indexer.
`pixels_selection_to_string`(*, pixels)	Convert the pixels list to the correct string for a storage group name.
`set_signature`(cls)	Call the 'set_signature' method on the provided class.

Classes

`DataCleaner`([policy])	Data cleaning utility.
`DataCleaningPolicy`(value[, names, module, ...])	Different kind of data cleaning policies.
`MethodCaller`(**kwargs)	Generic method caller abstraction class.
`UniqueNames`()	Class allowing to generate unique names.

class casys.utilities.DataCleaner(policy=DataCleaningPolicy.NONE)

Bases: object

Data cleaning utility.

Parameters:: policy (DataCleaningPolicy) – Data cleaning policy.

clean(data, index)

Clean provided dataset according to the cleaning policy.

Parameters:

data (Dataset) – Dataset to clean.
index (str) – Name of the index.

Return type:

Dataset

Returns:

Cleaned dataset.

policy: DataCleaningPolicy = 1

class casys.utilities.DataCleaningPolicy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different kind of data cleaning policies.

INDEX_SORT: Sort indexes.
INDEX_REMOVE_DUPLICATES: Remove consecutive duplicated indexes.
INDEX_SORT_REMOVE_DUPLICATES: Sort and remove duplicated indexes.
INDEX_ENFORCE_INCREASING: Remove block of indexes breaking the monotony.
NONE: Do nothing.

INDEX_ENFORCE_INCREASING = 5

INDEX_REMOVE_DUPLICATES = 3

INDEX_SORT = 2

INDEX_SORT_AND_REMOVE_DUPLICATES = 4

NONE = 1

class casys.utilities.MethodCaller(**kwargs)

Bases: Generic[T], ABC

Generic method caller abstraction class.

Define the method to call on objects and the parameters of this method.

call_method(item)

Parameters:: item (TypeVar(T))

property parameters

class casys.utilities.UniqueNames

Bases: object

Class allowing to generate unique names.

classmethod get_name(name)

Generate a unique name using the provided one. If the provided name is already used, suffix it by an integer.

Parameters:: name (str) – Requested name.
Return type:: str
Returns:: Unique name.

names: dict[str, int] = {}

classmethod reset(): Reset known names.

casys.utilities.call_methods(methods, item)

Call a list of methods on the provided item.

Parameters:

methods (list[TypeVar(MethodCallerType, bound= MethodCaller)]) – List of methods.
item – Item on which to call methods.

casys.utilities.check_class_equality(reference, other, parameters, ctype=None)

Check whether the provided classes have the same value for the given parameters.

Parameters:

reference (TypeVar(T)) – Reference object.
other (TypeVar(T)) – Object to compare.
parameters (list[str]) – List of parameters to compare.
ctype (type[TypeVar(T)] | None) – Expected class.

Returns:

Comparison results.

casys.utilities.copy_doc(copy_func)

Decorator allowing to copy the docstring of a function.

Parameters:: copy_func (Callable) – Function from which to copy the docstring.
Return type:: Callable
Returns:: Function decorator.

casys.utilities.dataset_align(data, data_ref, index, tolerance=None, interp=False, method=None, **kwargs)

Align provided dataset’s indexes with the reference dataset’s ones.

Parameters:

data (Dataset) – Data to align.
data_ref (Dataset) – Reference’s data.
index (str) – Index’s name
tolerance (int | float | timedelta64 | None) – Tolerance used with the “nearest” method.
interp (bool) – Whether to interpolate data on the reference’s index or not.
method (str | None) – xarray interpolation or re-indexation method.
kwargs – Additional parameters passed to the underlying xarray function.

Return type:

Dataset

Returns:

Aligned dataset.

casys.utilities.dataset_select_field(data, field, limits)

Reduce a dataset by only keeping indexes respecting provided field limits.

Parameters:

data (Dataset) – Input data.
field (str) – Field on which to apply the selection.
limits (tuple[Any, Any]) – Field’s min and max limits.

Return type:

Dataset

Returns:

Reduced dataset.

casys.utilities.dates_to_int_days(*, date_1, date_2)

Convert provided dates into an integer representing the date rounded to the day.

Parameters:

date_1 (datetime64) – First date.
date_2 (datetime64) – Second date.

Return type:

tuple[int, int]

Returns:

Tuple of integers representing the date rounded to the day.

casys.utilities.dates_to_string_days(*, date_1, date_2)

Convert provided dates into a string representing the time interval rounded to the day.

Parameters:

date_1 (datetime64) – First date.
date_2 (datetime64) – Second date.

Return type:

str

Returns:

Time interval as a string.

casys.utilities.fix_limits(values, as_none=True)

Fix provided limits values by normalizing it.

Parameters:

values (tuple[Any, Any] | None) – Values to normalize.
as_none (bool) – Whether to return None or (None, None)

Return type:

tuple[Any, Any] | None

Returns:

Normalized values.

casys.utilities.get_from_context_dict(context, key, name, error=True)

Get the requested element from the given context key.

Parameters:

context (dict[str, Any]) – Dictionary context in which to find the key.
key (str) – Key in which to look for the element.
name (str) – Name of the element to get.
error (bool) – Whether to raise an error or return the name if not found.

Return type:

Any

Returns:

Requested element.

casys.utilities.interval_step_to_number(vmin, vmax, step)

Transform a splitting interval expressed as min, max, step to an interval expressed as min, max, number. A warning is logged if the provided min, max range cannot be exactly split with the step. A computed maximum is used.

Parameters:

vmin (int | float) – Minimum value of the interval.
vmax (int | float) – Maximum value of the interval.
step (int | float) – Step of the intervals.

Return type:

tuple[int | float, int | float, int | float]

Returns:

(min, max, nbr)

casys.utilities.kwargs_checker(kwargs, allowed_args=list[str], exception=<class 'ValueError'>)

Check whether provided kwargs are allowed.

Parameters:

kwargs (dict[str, Any]) – kwargs to test.
allowed_args – List of allowed kwargs.
exception (type[Exception]) – Exception to raise.

Raises:

Exception – Raise the provided exception if some kwargs are not allowed.

casys.utilities.method_caller(method, cls_type)

Method caller factory.

Parameters:

method (str) – Name of the method to call.
cls_type (type) – Class on which the method will be called.

Return type:

type[TypeVar(MethodCallerType, bound= MethodCaller)]

Returns:

A MethodCaller class for the provided method.

casys.utilities.nc_content(paths, show_vars=True, show_dims=True, show_attrs=True)

List the content of netCDF files including its subgroups.

Parameters:

paths (str | list[str]) – NetCDF file to explore (use the first file if a pattern is provided).
show_vars (bool) – Whether to list variables or not.
show_dims (bool) – Whether to list dimensions or not.
show_attrs (bool) – Whether to list attributes or not.

Returns:

List of groups and subgroups associated with their content.

casys.utilities.normalize_image_size(values)

Normalize provided image size values.

Parameters:: values (tuple[Any, Any] | int | None) – Values to normalize.
Return type:: tuple[Any, Any] | int | None
Returns:: Normalized values.

casys.utilities.normalize_longitude(longitudes)

Normalize the provided longitude to a [-180, 180[ range.

Parameters:: longitudes (DataArray | ndarray) – Longitudes to normalize.
Return type:: DataArray | ndarray
Returns:: Normalized longitude.

casys.utilities.normalize_path(path)

Expand and normalize the provided path.

Parameters:: path (str) – Path to normalize.
Returns:: Normalized path.

casys.utilities.open_grdataset(paths, group=None, sub_groups=True, separator='.', pre_kwargs=None, mf_kwargs=None)

Alternative function to xarray.open_mfdataset allowing to open a group with its dimensions even if included in a parent group.

Subgroups might be included with their variables renamed by prefixing them with their group path.

Parameters:

paths (str | list[str]) – NetCDF file(s) to read.
group (str) – Name/path of the group to open.
sub_groups (bool) – Whether to include subgroups or not.
separator (str) – Separator to use when renaming group fields (default to “.”).
pre_kwargs (dict[str, Any]) – Additional xarray.open_dataset parameters used during the preprocessing.
mf_kwargs (dict[str, Any]) – Additional xarray.open_mfdataset parameters.

Return type:

Dataset

Returns:

xarray.Dataset.

casys.utilities.periods_for_track(indexer, start, end, exception)

Generate a period iterator fitting the requirements of the provided track.

Parameters:

indexer (PassIndexer) – Pass indexer used to match dates to pass’ number.
start (datetime64) – Starting date of the period of interest.
end (datetime64) – Ending date of the period of interest.
exception (type[Exception]) – Exception raised if provided dates do not match existing passes.

Return type:

PeriodGenerator

Returns:

Period iterator.

casys.utilities.periods_from_indexer(indexer, start, end, frequency, delta=None, exception=<class 'Exception'>)

Generate a period iterator over the provided indexer.

Parameters:

indexer (PassIndexer) – Pass indexer used to match dates to pass’ number.
start (datetime64) – Starting date of the period of interest.
end (datetime64) – Ending date of the period of interest.
frequency (CuttingType) – Period’s frequency.
delta (timedelta64 | None) – Time gap used to increase ending dates of periods.
exception (type[Exception]) – Exception raised if something goes wrong.

Return type:

PeriodGenerator

Returns:

Period iterator.

casys.utilities.pixels_selection_to_string(*, pixels)

Convert the pixels list to the correct string for a storage group name.

Parameters:: pixels (list[int | tuple[int, int]]) – List of the pixels.
Return type:: str
Returns:: Converted string of the pixels.

casys.utilities.set_signature(cls)

Call the ‘set_signature’ method on the provided class.

Parameters:: cls (TypeVar(T))
Return type:: TypeVar(T)