casys.elements

Common base elements classes.

Classes

DataContainerType(value[, names, module, ...])

Different types of data.

LimitsType(value[, names, module, qualname, ...])

Different type of color limits presets.

CyclePassFmt(value[, names, module, ...])

CyclePassFormatter(orf, fmt)

Callable class allowing to format ticks.

DataResolution(min, max, step[, computed, ftype])

Data slices resolution.

DataResolutionAuto([min, max, step, ...])

Data slices resolution.

FeatureType(value[, names, module, ...])

Different of features in a plot.

Field(name[, source, source_aux, subfields, ...])

Field object representing parameters/variables in data sources.

FieldBase(name[, source, source_aux, ...])

Field object representing parameters/variables in data sources.

FieldsList(fields)

FieldType(value[, names, module, qualname, ...])

Existing type of fields.

FreqType(value[, names, module, qualname, ...])

Frequencies allowed by time statistics.

FrequencyHandler([value, meta, number])

Utility class allowing to create grid and periods objects respecting frequency criteria.

InterpolationOptions([mode, noise_level, ...])

Interpolation options.

TextElementType(value[, names, module, ...])

Different category of textual elements.

DataType(value[, names, module, qualname, ...])

Different kind of data handled by this module.

DiagnosticMeta(properties[, internal, names])

Class allowing to manage diagnostic properties in a storable way.

DiagnosticType(value[, names, module, ...])

Different kind of data handled by this module.

SelectionType(value[, names, module, ...])

Different kind of selection allowed in computation.

SpectralType(value[, names, module, ...])

Different kind of spectral curves allowed in computation.

StatType(value[, names, module, qualname, ...])

Different kind of statistics allowed in computation.

StorageMode(value[, names, module, ...])

Storage modes.

Exceptions

AltiDataError

Exception raised when a problem related to data or fields occurs.

CasysError

Exception raised when a problem related Casys occurs.

CasysPlotError

Exception raised when a problem related to plotting occurs.

CasysStorageError

Exception raised when a problem related to data or fields occurs.

ColorMapError

Exception raised when a problem related to color maps occurs.

exception casys.elements.AltiDataError

Bases: CasysError

Exception raised when a problem related to data or fields occurs.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception casys.elements.CasysError

Bases: Exception

Exception raised when a problem related Casys occurs.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception casys.elements.CasysPlotError

Bases: CasysError

Exception raised when a problem related to plotting occurs.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception casys.elements.CasysStorageError

Bases: CasysError

Exception raised when a problem related to data or fields occurs.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception casys.elements.ColorMapError

Bases: CasysPlotError

Exception raised when a problem related to color maps occurs.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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

Bases: Enum

C = 1
CP = 3
P = 2
label()

Label representation of the formatter.

Return type:

str

string_format()
Return type:

str

class casys.elements.CyclePassFormatter(orf, fmt)

Bases: object

Callable class allowing to format ticks.

Parameters:
fmt: CyclePassFmt
orf: PassIndexer
class casys.elements.DataContainerType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different types of data.

NADIR = 1
SWATH = 2
class casys.elements.DataResolution(min, max, step, computed=True, ftype=FIELD)

Bases: object

Data slices resolution.

Parameters:
compute(values)

Compute resolution information for provided values.

Parameters:

values (ndarray) – Values for which to compute the resolution.

computed: bool = True
classmethod default()
Return type:

DataResolution

ftype: FieldType = 11
group_str()
Return type:

str

html_elem()
Return type:

str

max: float
min: float
static normalize(resolution, allow_auto=False, ftype=FIELD)

Normalize provided input to a DataResolution object.

Parameters:
Return type:

DataResolution

Returns:

Normalized data resolution.

step: float
class casys.elements.DataResolutionAuto(min=None, max=None, step=None, computed=False, ftype=FIELD)

Bases: DataResolution

Data slices resolution.

Parameters:
compute(values)

Compute resolution information for provided values.

Parameters:

values (ndarray) – Values for which to compute the resolution.

computed: bool = False
classmethod default()
Return type:

DataResolution

ftype: FieldType = 11
group_str()
Return type:

str

html_elem()
Return type:

str

max: float | None = None
min: float | None = None
static normalize(resolution, allow_auto=False, ftype=FIELD)

Normalize provided input to a DataResolution object.

Parameters:
Return type:

DataResolution

Returns:

Normalized data resolution.

step: float | None = None
class casys.elements.DataType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different kind of data handled by this module.

CROSSOVER = 17
EDITING = 19
EDITING_RAW = 20
MISSING_POINTS = 18
RATIO = 16
RAW_COMPARISON = 4
RAW_COMPARISON_3D_SCATTER = 6
RAW_COMPARISON_3D_SURFACE = 5
RAW_DATA = 1
RAW_DATA_3D_SCATTER = 2
RAW_DATA_3D_SURFACE = 3
SECTION_ANALYSES = 21
SPECTRAL_ANALYSIS_INDIVIDUAL_PSD = 24
SPECTRAL_ANALYSIS_PSD = 23
SPECTRAL_ANALYSIS_SEGMENT = 22
STAT_BINNED = 11
STAT_BINNED_2D = 12
STAT_BINNED_2D_BOX3D = 15
STAT_BINNED_2D_CURVE = 13
STAT_BINNED_2D_SURFACE = 14
STAT_GEOBOX = 8
STAT_HISTO = 9
STAT_SCATTER = 10
STAT_TIME = 7
class casys.elements.DiagnosticMeta(properties, internal=False, names=<factory>)

Bases: ABC

Class allowing to manage diagnostic properties in a storable way.

Parameters:
DTYPE: ClassVar[DiagnosticType]
field_name(diag)

Diagnostic field’s name.

Parameters:

diag (str)

Return type:

str

fields_name()

List name of fields used in this diagnostic.

Return type:

list[str]

classmethod from_conf(names, conf, internal, instantiate)
Parameters:
Return type:

DiagnosticMeta

classmethod from_store_group(group, instantiate=True)

Generate a DiagnosticMeta from the provided group’s configuration.

Parameters:
  • group (DiagnosticGroupStore) – Storage group from which to extract diagnostic properties.

  • instantiate (bool) – Whether we want to instantiate the diagnostic or not.

Return type:

DiagnosticMeta

Returns:

Instantiated DiagnosticMeta.

classmethod get_class(dtype)
Parameters:

dtype (DiagnosticType)

Return type:

type[DiagnosticMeta]

internal: bool = False
merge(other)

Merge provided diagnostic meta to this one.

Parameters:

other (DiagnosticMeta) – Diagnostic meta to merge.

names: dict[str, dict[str, Any]]
properties: dict[str, Any]
classmethod register()

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

to_conf()

Generate a serialized version of this diagnostic meta.

Return type:

dict[str, Any]

Returns:

Serialized diagnostic meta configuration.

to_method_caller(schema, date_start, date_end, store, group)

Convert this diagnostic metadata into callable methods configurations.

Parameters:
  • schema (BaseSchema) – Schema used to generate the MethodCaller instance.

  • date_start (datetime64) – Analyse starting date.

  • date_end (datetime64) – Analyse ending date.

  • store (DiagnosticStore) – DiagnosticStore containing this metadata.

  • group (str) – Storage group associated to the current diagnostic.

Return type:

list[MethodCaller]

Returns:

List of callable methods.

to_method_conf(diag_name)

Generate the method configuration associated to the given diagnostic name.

Parameters:

diag_name (str) – Name of the diagnostic.

Return type:

dict[str, Any]

Returns:

Diagnostic method configuration.

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

Bases: Enum

Different kind of data handled by this module.

BINNED = 9
BINNED_2D = 10
CROSSOVER = 12
CUSTOM = 17
EDITING = 14
GEOBOX = 6
HISTOGRAM = 7
MAP = 1
MISSING_POINTS = 13
PERIODOGRAM = 5
RATIO = 11
RAW = 1
RAW_COMPARISON = 2
RAW_COMPARISON_3D = 3
SCATTER = 8
SECTION_ANALYSES = 15
SPECTRAL_ANALYSIS = 16
TEMPORAL = 4
class casys.elements.FeatureType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different of features in a plot.

COASTLINE = 2
GSHHS = 1
LAND = 3
OCEAN = 4
cartopy_feature(scale, levels=None)
Parameters:

scale (str | Scaler)

Return type:

<module ‘cartopy.feature’ from ‘/home/tzilio/.conda/envs/py313/lib/python3.13/site-packages/cartopy/feature/__init__.py’>

class casys.elements.Field(name, source=None, source_aux=None, subfields=None, unit=None, description='', interpolation=None, attributes=<factory>, ftype=None, stats_usage=<factory>, external=False, display=False)

Bases: FieldBase

Field object representing parameters/variables in data sources.

Parameters:
  • name (str) – Name of the field.

  • source (str | None) –

    Name of the field in the data source (can be a clip). WARNING: Clip’s operator syntax might change depending on the source’s type.

    • Dataset sources might require vector operator: :==, :!=, :<, :<=, :>, :>=

    • CLS Table sources require scalar operators: ==, !=, <, <=, >, >=

  • source_aux (str | None) – Alternative name of the field in the data source (can be a clip). This attribute might be used for multi-missions crossovers.

  • subfields (list[Field] | None) – List of subfields used in the source of this field. This might be useful when creating fields as clip from a MultiReader. Each subfield have to belong to single reader and will be computed before any reader post-processing (such as interpolation).

  • unit (Unit | str | None) – Unit of the field.

  • description (str) – Description of the field.

  • interpolation (str | dict[str, Any] | InterpolationOptions | None) –

    Interpolation options. Can be provided using an InterpolationOptions object or a dictionary containing ‘mode’ and ‘noise_level’ keys: {‘mode’: ‘smoothing_spline’, noise_level: 0.1} or a string containing only the ‘mode’.

    mode

    Interpolation mode to use when interpolating along a reference track. Accepted values are linear, nearest or smoothing_spline.

    noise_level

    Only required for the smoothing_spline mode. Estimated noise level in the signal. Oscillations lower that this value will be removed by the smoothing spline.

  • attributes (dict[str, Any]) – Additional information.

  • ftype (FieldType | str | None) – FieldType of the field.

  • stats_usage (set[str]) – Set of statistics using this field.

  • external (bool) – Whether this field comes from an external source or not.

  • display (bool) – Whether this field is only a display field or not (a display field might contain spaces)

add_usage(stat)

Add a statistic using this field.

Parameters:

stat (str) – Name of the statistic using this field.

classmethod attribute_names()
Return type:

list[str]

attributes: dict[str, Any]
static check_duplicates(fields)

Check that all provided fields have different names.

Parameters:

fields (list[Field]) – Fields to check.

Raises:

AltiDataError – If two fields share the same name.

property clip: Clip
description: str = ''
display: bool = False
external: bool = False
ftype: FieldType | str | None = None
html_elem()
Return type:

str

interpolation: str | dict[str, Any] | InterpolationOptions | None = None
is_clip()

Test whether this field is a clip or not.

Return type:

bool

Returns:

True if a clip, False otherwise.

is_similar(field)

Test whether both fields are equivalent or not.

Similar fields have identical properties with an exception

Parameters:

field (Field)

Return type:

bool

name: str
static name_marker(name, markers)

Return the marker of the provided name.

Parameters:
  • name (str) – Name to check.

  • markers (list[str]) – Markers on which to split.

Return type:

str | None

Returns:

Marker of the name.

classmethod normalize(field)
Parameters:

field (str | Field | None)

Return type:

Field | None

required_fields()
Return type:

list[str]

source: str | None = None
source_aux: str | None = None
static source_origin(name, markers)

Return the original source’s marker and name of the provided name.

Parameters:
  • name (str) – Name from which to get the original source.

  • markers (list[str]) – Markers on which to split.

Return type:

tuple[str | None, str]

Returns:

Marker and original source’s name.

property sources: set

List of the sources of this field.

static split_fields(fields, markers)

Split provided fields according to their marker.

Parameters:
  • fields (dict[str, Field]) – Fields to split.

  • markers (list[str]) – Markers on which to split.

Return type:

dict[str, dict[str, Field]]

Returns:

Split fields.

split_origins(markers)

Create a dictionary matching fields used in the source of this field to their marker.

Parameters:

markers (list[str]) – Markers on which to split.

Return type:

dict[str, dict[str, Field]]

Returns:

Dictionary matching fields to their marker.

stats_usage: set[str]
storage_field()

Storage (DiagnosticField) representation of this field.

Return type:

DiagnosticField

subfields: list[Field] | None = None
unit: Unit | str | None = None
update_usage(stats)

Update the set of statistics using this field.

Parameters:

stats (set[str]) – Set of kept statistics.

Return type:

set[str]

Returns:

Updated set of statistics using this field.

class casys.elements.FieldBase(name, source=None, source_aux=None, subfields=None, unit=None, description='', interpolation=None, attributes=<factory>)

Bases: object

Field object representing parameters/variables in data sources.

Parameters:
  • name (str) – Name of the field.

  • source (str | None) –

    Name of the field in the data source (can be a clip). WARNING: Clip’s operator syntax might change depending on the source’s type.

    • Dataset sources might require vector operator: :==, :!=, :<, :<=, :>, :>=

    • CLS Table sources require scalar operators: ==, !=, <, <=, >, >=

  • source_aux (str | None) – Alternative name of the field in the data source (can be a clip). This attribute might be used for multi-missions crossovers.

  • subfields (list[FieldBase] | None) – List of subfields used in the source of this field. This might be useful when creating fields as clip from a MultiReader. Each subfield have to belong to single reader and will be computed before any reader post-processing (such as interpolation).

  • unit (Unit | str | None) – Unit of the field.

  • description (str) – Description of the field.

  • interpolation (str | dict[str, Any] | InterpolationOptions | None) –

    Interpolation options. Can be provided using an InterpolationOptions object or a dictionary containing ‘mode’ and ‘noise_level’ keys: {‘mode’: ‘smoothing_spline’, noise_level: 0.1} or a string containing only the ‘mode’.

    mode

    Interpolation mode to use when interpolating along a reference track. Accepted values are linear, nearest or smoothing_spline.

    noise_level

    Only required for the smoothing_spline mode. Estimated noise level in the signal. Oscillations lower that this value will be removed by the smoothing spline.

  • attributes (dict[str, Any]) – Additional information.

classmethod attribute_names()
Return type:

list[str]

attributes: dict[str, Any]
description: str = ''
interpolation: str | dict[str, Any] | InterpolationOptions | None = None
is_similar(field)

Test whether both fields are equivalent or not.

Similar fields have identical properties with an exception

Parameters:

field (Field)

Return type:

bool

name: str
classmethod normalize(field)
Parameters:

field (str | Field | None)

Return type:

Field | None

source: str | None = None
source_aux: str | None = None
storage_field()

Storage (DiagnosticField) representation of this field.

Return type:

DiagnosticField

subfields: list[FieldBase] | None = None
unit: Unit | str | None = None
class casys.elements.FieldType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Existing type of fields.

CROSS_TRACK_DISTANCE = 8
CYCLE_NUMBER = 6
FIELD = 11
LATITUDE = 3
LATITUDE_NADIR = 5
LONGITUDE = 2
LONGITUDE_NADIR = 4
PASS_NUMBER = 7
SWATH_LINES = 9
SWATH_PIXELS = 10
TIME = 1
class casys.elements.FieldsList(fields)

Bases: object

Parameters:

fields (list[Field])

fields: list[Field]
class casys.elements.FreqType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Frequencies allowed by time statistics.

CUSTOM = 5
CYCLE = 1
DAY = 3
NONE = 6
PASS = 2
RAW = 4
extended_dates(indexer, start, end)

Extend provided dates according to the orbit (cycle or pass) they belong to.

Parameters:
Return type:

tuple[datetime64, datetime64]

Returns:

Extended dates.

storage_model()

Diagnostic storage model matching this frequency.

Return type:

type[DiagnosticModel]

to_cutting_type()

Convert to a corresponding ong_periods.CuttingType.

Return type:

CuttingType

Returns:

Corresponding ong_periods.CuttingType.

class casys.elements.FrequencyHandler(value=NONE, meta=<factory>, number=None)

Bases: object

Utility class allowing to create grid and periods objects respecting frequency criteria.

Parameters:
  • value (str | FrequencyHandler | FreqType) – Frequency value (cycle, pass, day or any pandas’ frequency).

  • meta (dict[str, Any]) – Additional parameters used for pandas frequency.

  • number (int | None) – Maximum number of period to generate.

add_indexer_constraint(indexer)

Add an indexer constraint. A constraint might require more periods than the indexer used to determine periods.

Parameters:

indexer (PassIndexer) – Constraining indexer.

freq: FreqType
grid(start, end, indexer=None)

Create a time grid matching frequency properties.

Parameters:
  • start (datetime64) – Starting date of the grid.

  • end (datetime64) – Ending date of the grid.

  • indexer (PassIndexer | None) – Orf indexer to use to build cycle/pass grids.

Return type:

Grid1D

Returns:

The grid.

group_str()

String identifier.

include_end: bool
indexer_constraints: list[PassIndexer]
is_compatible(handler)

Check whether the provided frequency is an exact subdivision of this one. An exact subdivision means the provided handler does not generate periods overlapping the ones of this handler.

  • cycle is compatible with pass and cycle

  • pass is only compatible with pass

  • 6 days are compatible with 2 days, 30 seconds, …

Parameters:

handler (FrequencyHandler | None) – Frequency handler to test.

Return type:

bool

Returns:

True if compatible, false otherwise.

meta: dict[str, Any]
static normalize_value(value)

Validate and normalize input frequency value.

Parameters:

value (str | FreqType) – Frequency to normalize.

Return type:

tuple[str, FreqType]

Returns:

Normalized frequency as a tuple (value, frequency type)

number: int | None = None
periods(start, end, indexer=None, reference=None)

Create a list of periods respecting the frequency criteria bounds and the given number.

Parameters:
  • start (datetime64) – Starting date.

  • end (datetime64) – Ending date.

  • indexer (PassIndexer | None) – Orf indexer to use to build cycle/pass grids.

  • reference (list[tuple[int, int]] | None) – List of reference’s orbits. Used for cycle/pass frequency in order to create periods representing the same cycle or pass as the reference ones.

Return type:

list[Period]

Returns:

List of periods (or None).

require_orf()

Check if this frequency requires an orf or not.

Return type:

bool

Returns:

True if it requires an ORF (cycle or pass), False otherwise.

property used_orbits: list[tuple[int, int]]

List of used and normalized (cycle, pass).

used_periods: list[Period]
value: str | FrequencyHandler | FreqType = 6
class casys.elements.InterpolationOptions(mode=InterpMode.LINEAR, noise_level=None, spline_length=None, median_filter_size=None, holes_threshold=None)

Bases: object

Interpolation options.

Parameters:
  • mode (str | InterpMode) – Interpolation mode to use when interpolating along a reference track. Accepted values are linear, nearest or smoothing_spline.

  • noise_level (int | float | None) – Required for the smoothing_spline mode. Estimated noise level in the signal. Oscillations lower that this value will be removed by the smoothing spline.

  • spline_length (float | None) – Spline length for “smoothing_spline” interpolation mode

  • median_filter_size (float | None) – Median filter_size for “smoothing_spline” interpolation mode

  • holes_threshold (float | None) – Threshold for interpolation by smoothing spline, this is carried out between small and big holes (same unit as points, seconds if dates). The points (and the associated values) between two consecutive big holes form a ‘section’. The interpolations are made section by section : a smoothing spline can never cross a big hole. Note that original sections may either disappear or be split in several ones according to the parameters ‘section_min_length’ and ‘section_max_length’. Default value is 32 times the median step.

holes_threshold: float | None = None
median_filter_size: float | None = None
mode: str | InterpMode = 2
noise_level: int | float | None = None
spline_length: float | None = None
class casys.elements.LimitsType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different type of color limits presets.

  • AUTO: [mean - 3*std, mean + 3*std]

AUTO = 1
PERCENTILE = 3
VALUE = 2
class casys.elements.SelectionType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different kind of selection allowed in computation.

ALL = 2
NONE = 1
RANGE = 3
class casys.elements.SpectralType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different kind of spectral curves allowed in computation.

PERIODOGRAM = 1
WELCH = 2
computer()
default_kwargs_setter()
class casys.elements.StatType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different kind of statistics allowed in computation.

COUNT = 1
MAD = 9
MAX = 4
MEAN = 5
MEDIAN = 6
MIN = 3
NBR = 2
NONE = 13
PROD = 11
STD = 7
SUM = 10
VALUE = 12
VAR = 8
property alternative: StatType

Alternative statistic (mostly used for histograms internal statistics).

classmethod check_stat_selection(selection)

Check if the selection’s stats exist.

Parameters:

selection (str | None) – Selection to check.

Return type:

Clip | None

Returns:

Statistics’ selection clip.

static clip_dictionary()

Dictionary containing renaming maps of statistics contained in clips. Statistics name might have a special meaning when used in clips. Renaming them avoid this kind of problem.

Return type:

dict[str, str]

Returns:

Dictionary of statistics name used in clips.

static clip_extract_names(clip)

Extract statistic’s names from a Clip.

Parameters:

clip (Clip) – Clip from which to extract names.

Return type:

set[str]

Returns:

List of statistics.

computer()

Computer associated to the statistic.

default_value()

Default value associated to the statistic.

Return type:

int | float

classmethod internals()

List of statistics used for internal statistics.

Return type:

list[StatType]

property lower_name: str

Statistic name in lower characters.

classmethod normalize_clip(selection)

Normalize the provided statistic based selection clip.

Parameters:

selection (str) – Clip to normalize.

Return type:

Clip

Returns:

Normalized clip.

classmethod stat_bar()

List of statistics used for the stat_bar display.

Return type:

list[StatType]

property store_dtype: DiagnosticType

Transform this statistic type to its matching storage diagnostic type.

suffix_field(field)

Return the field name suffixed with the current StatType name.

Parameters:

field (str)

Return type:

str

static to_string(stats)

Generate a list of formatted statistic names.

Parameters:

stats (Iterable[StatType]) – List of statistics as StatType.

Return type:

list[str]

Returns:

List of formatted statistics.

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

Bases: Enum

Storage modes.

MERGE = 2
OVERWRITE = 1
class casys.elements.TextElementType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different category of textual elements.

ALL = 1
AXES_LABELS = 3
AXES_TICKS = 4
BARS_LABELS = 5
BARS_TICKS = 6
LEGEND = 7
TITLE = 2