Fields definition

The Field object is used when specifying diagnostics (raw data, statistics, …) to reference a field (sometimes called variable or parameter) included in the data source.

Field can be manually created (to dynamically combine multiple fields) or extracted from the source.

Using existing fields

The show_fields() method allows to visualize and search among all existing fields.

from casys import NadirData, DateHandler

start = DateHandler("2019-06-01 05:30:00")
end = DateHandler("2019-06-07 05:30:00")

ad = NadirData(
    date_start=start,
    date_end=end,
    source="TABLE_C_J3_B_GDRD",
    orf="C_J3_GDRD",
    time="time",
    longitude="LONGITUDE",
    latitude="LATITUDE",
)

# Display all fields included in the data source
ad.show_fields()

# Or a set of fields containing the provided string ("SIGMA0" here)
ad.show_fields(containing="SIGMA0")

Name	Description	Unit
ATMOSPHERIC_ATTENUATION_SIGMA0.ALTI	Atténuation atmosphérique du coefficient de rétrodiffusion en bande principale	dB
ATMOSPHERIC_ATTENUATION_SIGMA0.ALTI.B2	Atténuation atmosphérique du coefficient de rétrodiffusion en bande secondaire	dB
FLAG_QUAL.ALTI.NET_INSTR_CORR_SIGMA0	0: good, 1: bad.	1
FLAG_QUAL.ALTI.NET_INSTR_CORR_SIGMA0_B2	0: good, 1: bad.	1
SIGMA0.ALTI	All instrumental corrections included, excepted the system bias, i.e. AGC instrumental errors correction, internal calibration	dB
SIGMA0.ALTI.B2	All instrumental corrections included, excepted the system bias, i.e. AGC instrumental errors correction, internal calibration	dB
SIGMA0.ALTI.RTK_MLE3	Coefficient de rétrodiffusion en bande principale (rtk MLE3)	dB
SIGMA0_BIAS.ALTI	Biais du SIGMA0 par rapport à une valeur moyenne de référence	dB
SIGMA0_NET_INSTRUMENTAL_CORRECTION.ALTI	Sum of AGC instrumental errors correction, internal calibration correction and modeled instrumental errors correction - system	dB
SIGMA0_NET_INSTRUMENTAL_CORRECTION.ALTI.B2	Sum of AGC instrumental errors correction, internal calibration correction and modeled instrumental errors correction - system	dB
SIGMA0_NET_INSTRUMENTAL_CORRECTION.ALTI.RTK_MLE3	Somme des corrections instrumentales sur le sigma0 en bande principale (rtk MLE3)	dB
SIGMA0_NUMBER.ALTI	Nombre de mesures elementaires de sigma0 en bande principale	count
SIGMA0_NUMBER.ALTI.B2	Nombre de mesures elementaires de sigma0 en bande secondaire	count
SIGMA0_NUMBER.ALTI.RTK_MLE3	Nombre de mesures elementaires de sigma0 en bande principale (rtk MLE3)	count
SIGMA0_STD.ALTI	Compression of high rate elements is preceded by a detection of outliers. Only valid high-rate values are used to compute this	dB
SIGMA0_STD.ALTI.B2	Compression of high rate elements is preceded by a detection of outliers. Only valid high-rate values are used to compute this	dB
SIGMA0_STD.ALTI.RTK_MLE3	Ecart-type des mesures elementaires de sigma0 en bande principale (rtk MLE3)	dB

These fields can then be extracted through the fields property and directly used as is to define diagnostics.

sig0 = ad.fields["SIGMA0.ALTI"]

Manually creating fields

Field object might use a more complex definition based on combination of existing fields along with some conditions.

Warning

Clips use vector operator: :==, :!=, :<, :<=, :>, :>=

Field object representing parameters/variables in data sources.

Parameters
----------
name
    Name of the field.
source
    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
    Alternative name of the field in the data source (can be a clip).
    This attribute might be used for multi-missions crossovers.
subfields
    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 of the field.
description
    Description of the field.
interpolation
    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
    Additional information.
ftype
    FieldType of the field.

stats_usage
    Set of statistics using this field.
external
    Whether this field comes from an external source or not.
display
    Whether this field is only a display field or not (a display field might
    contain spaces)

Examples of fields using complex clips as source.

from casys import Field


sla = Field(
    name="SLA",
    source="ORBIT.ALTI - RANGE.ALTI - MEAN_SEA_SURFACE.MODEL.CNESCLS15",
    unit="m"
)

range_std_ku = Field(
    name="range_std_ku",
    source="IIF(FLAG_VAL.ALTI :== 0, RANGE_STD.ALTI, DV)",
    unit="m"
)

range_std_c = Field(
    name="range_std_c",
    source="IIF(FLAG_VAL.ALTI :== 0, RANGE_STD.ALTI.B2, DV)",
    unit="m"
)

swh = Field(
    name="swh",
    source="IIF(FLAG_VAL.ALTI :== 0, SWH.ALTI, DV)",
    unit="m"
)

wind = Field(
    name="wind",
    source="IIF(FLAG_VAL.ALTI :== 0, WIND_SPEED.ALTI, DV)",
    unit="m/s"
)

Using simple field definition

It is also possible to use directly the name in characters chain of a field in the source while defining a diagnostics:

ad = NadirData(
    date_start=start,
    date_end=end,
    source="TABLE_C_J3_B_GDRD",
    orf="C_J3_GDRD",
    time="time",
    longitude="LONGITUDE",
    latitude="LATITUDE",
)

ad.add_raw_data(name="raw_swh", field="SWH.ALTI")

Multi-readers and subfields

When working with MultiReaders interpolating on a reference track, some fields’ source might contain clips having to be executed before the interpolation (clips including conditions on a flag or any value that might change during the interpolation).

In order to specify such behavior, Field have a subfields parameter allowing to provide a list of fields which will be computed by readers before post-processing operations (such as interpolation on a reference track).

Fields defined in the subfields parameter can be used as input for the source parameter.

The following example illustrate this parameter usage.

We’re working with 2 readers (using S6_ and J3_ as markers)

These reader’s data are interpolated on a reference track

We want to build a Field representing a difference between the 2 readers

Defining everything using the source parameter will compute and interpolate each field contained in the source separately.

FLAG values will be changed and the result will not be what’s expected.

from casys import Field

swh_diff = Field(
    name="swh_diff",
    source="IIF(J3_FLAG_VAL.ALTI :== 0 && S6_FLAG_VAL.ALTI :== 0, S6_SWH.ALTI - J3_SWH.ALTI, DV)",
    interpolation={"mode": "smoothing_spline", "noise_level": 0.0},
)

Whereas using the source and subfields parameters allows subfields to be computed by their respective reader before the interpolation and the resulting field will contain the expected difference.

from casys import Field

swh_diff = Field(
    name="swh_diff",
    source="swh_s6 - swh_j3",
    subfields=[
        Field(
            name="swh_j3",
            source="IIF(J3_FLAG_VAL.ALTI :== 0, J3_SWH.ALTI, DV)",
            interpolation={"mode": "smoothing_spline", "noise_level": 0.0},
        ),
        Field(
            name="swh_s6",
            source="IIF(S6_FLAG_VAL.ALTI :== 0, S6_SWH.ALTI, DV)",
            interpolation={"mode": "smoothing_spline", "noise_level": 0.0},
        ),
    ],
)