Skip to content

variable_attributes

Classes:

Name Description
VariableAttributes

Attributes that will be recorded in the output dataset.

Classes#

VariableAttributes #

Bases: AttributeModel

Attributes that will be recorded in the output dataset.

These metadata are to record information about the data properties and related fields (e.g., units, ancillary_variables, etc), user-facing metadata (e.g., long_name, comment), as well as attributes related to quality checks and controls (e.g., valid_, fail_, and warn_* properties).

Methods:

Name Description
validate_unit
validate_units_are_commented

Attributes:

Name Type Description
accuracy Optional[float]
calibration_date Optional[str]
cf_role Optional[str]
comment Optional[StrictStr]
coverage_content_type Optional[str]
fail_delta Optional[float]
fail_range Optional[List[float]]
fill_value Optional[Any]
instrument Optional[str]
long_name Optional[StrictStr]
make_model Optional[str]
precision Optional[float]
resolution Optional[float]
standard_name Optional[StrictStr]
units Optional[str]
valid_delta Optional[float]
valid_range Optional[List[float]]
warn_delta Optional[float]
warn_range Optional[List[float]]

Attributes#

accuracy class-attribute instance-attribute #
accuracy: Optional[float] = Field(
    default=None,
    description="The sensor accuracy is the closeness of the measurements to the variable's true value. It should be given in the same units as the measured variable. If the instrument has been calibrated multiple times with different results, the most recent accuracy should be provided here (see instrument_variable:calibration_date).",
)
calibration_date class-attribute instance-attribute #
calibration_date: Optional[str] = Field(
    default=None,
    description="The date the instrument was last calibrated. Value should be specified using ISO-8601 compatible strings.",
)
cf_role class-attribute instance-attribute #
cf_role: Optional[str] = Field(
    title="CF Role",
    default=None,
    description="Allowed values are defined in Chapter 9.5 CF guidelines and consist of: timeseries_id, profile_id, and trajectory_id, depending on the featureType represented in the dataset, as specified by the featureType global attribute.",
)
comment class-attribute instance-attribute #
comment: Optional[StrictStr] = Field(
    default=None,
    description="A user-friendly description of what the variable represents, how it was measured or derived, or any other relevant information that increases the ability of users to understand and use this data. This field plays a considerable role in creating self-documenting data, so we highly recommend including this field, especially for any variables which are particularly important for your dataset. Additionally, if the units for an attribute are unknown, then this field must include the phrase: 'Unknown units.' so that users know there is some uncertainty around this property. Variables that are unitless (e.g., categorical data or ratios), should set the 'units' to '1'.",
)
coverage_content_type class-attribute instance-attribute #
coverage_content_type: Optional[str] = Field(
    default=None,
    description="An ISO 19115-1 code to indicate the source of the data (image, thematicClassification, physicalMeasurement, auxiliaryInformation, qualityInformation, referenceInformation, modelResult, or coordinate).",
)
fail_delta class-attribute instance-attribute #
fail_delta: Optional[float] = Field(
    default=None,
    description="The largest difference between consecutive values in the data outside of which the data should be teated with heavy skepticism as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having a 'Bad' assessment.",
)
fail_range class-attribute instance-attribute #
fail_range: Optional[List[float]] = Field(
    default=None,
    min_items=2,
    max_items=2,
    description="A two-element list of [min, max] values outside of which the data should be teated with heavy skepticism as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having a 'Bad' assessment.",
)
fill_value class-attribute instance-attribute #
fill_value: Optional[Any] = Field(
    default=None,
    alias="_FillValue",
    description="A value used to initialize the variable's data and indicate that the data is missing. Defaults to -9999 for numerical data. If choosing a different value, it is important to use a value that could not reasonably be mistaken for a physical value or data point.",
)
instrument class-attribute instance-attribute #
instrument: Optional[str] = Field(
    default=None,
    description="Variable attribute to be specified on each geophysical variable to identify the instrument that collected the data. The value of the attribute should be set to another variable which contains the details of the instrument. There can be multiple instruments involved depending on if all the instances of the featureType in the collection come from the same instrument or not. If multiple instruments are involved, a variable should be defined for each instrument and referenced from the geophysical variable in a comma separated string.",
)
long_name class-attribute instance-attribute #
long_name: Optional[StrictStr] = Field(
    default=None,
    description="A brief label for the name of the measured property. The xarray python library automatically searches for this attribute to use as an axes label in plots, so the value should be suitable for display.",
)
make_model class-attribute instance-attribute #
make_model: Optional[str] = Field(
    title="Make and Model",
    default=None,
    description="The make and model of the instrument.",
)
precision class-attribute instance-attribute #
precision: Optional[float] = Field(
    default=None,
    description="The sensor precision is the closeness of the measurements to each other. It should be given in the same units as the measured variable. If the instrument has been calibrated multiple times with different results, the most recent precision should be provided here (see instrument_variable:calibration_date).",
)
resolution class-attribute instance-attribute #
resolution: Optional[float] = Field(
    default=None,
    description="The sensor resolution is the smallest change it can represent in the quantity that it is measuring. It should be given in the same units as the measured variable.",
)
standard_name class-attribute instance-attribute #
standard_name: Optional[StrictStr] = Field(
    default=None,
    description="A string exactly matching a value in the CF Standard Name table which is used to provide a standardized way of identifying variables and measurements across heterogeneous datasets and domains. If a suitable match does not exist, then this attribute should be omitted. The full list of CF Standard Names is at: https://cfconventions.org/Data/cf-standard-names.",
)
units class-attribute instance-attribute #
units: Optional[str] = Field(
    description="A string indicating the units the data are measured in. Tsdat uses pint to handle unit conversions, so this string must be compatible with the pint list of units, if provided. A complete list of compatible units can be found here: https://github.com/hgrecco/pint/blob/master/pint/default_en.txt. If the property is unitless, then the string '1' should be used. If the units of the property are not known, then the units attribute should be omitted and the comment attribute should include a note indicating that units are not known. Doing so provides helpful context for data users."
)
valid_delta class-attribute instance-attribute #
valid_delta: Optional[float] = Field(
    default=None,
    description="The largest difference between consecutive values in the data outside of which the data should be treated as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having a 'Bad' assessment and replace those values with the variable's _FillValue.",
)
valid_range class-attribute instance-attribute #
valid_range: Optional[List[float]] = Field(
    default=None,
    min_items=2,
    max_items=2,
    description="A two-element list of [min, max] values outside of which the data should be treated as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having a 'Bad' assessment and replace those values with the variable's _FillValue.",
)
warn_delta class-attribute instance-attribute #
warn_delta: Optional[float] = Field(
    default=None,
    description="The largest difference between consecutive values in the data outside of which the data should be teated with some skepticism as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having an 'Indeterminate' assessment.",
)
warn_range class-attribute instance-attribute #
warn_range: Optional[List[float]] = Field(
    default=None,
    min_items=2,
    max_items=2,
    description="A two-element list of [min, max] values outside of which the data should be teated with some skepticism as missing. If applying QC tests, then users should configure the quality managers to flag values outside of this range as having an 'Indeterminate' assessment.",
)

Functions#

validate_unit #
validate_unit(unit_str: str) -> str
Source code in tsdat/config/variables/variable_attributes.py
@validator("units")
def validate_unit(cls, unit_str: str) -> str:
    try:
        # Validate with pint unit registry
        unit_str = check_unit(unit_str, keep_exp=False)
    except PintError:
        logger.warning(
            f"'{unit_str}' is not a valid unit or combination of units. The string"
            " will be kept as-is."
        )
    return unit_str
validate_units_are_commented #
validate_units_are_commented(
    values: Dict[str, Any]
) -> Dict[str, Any]
Source code in tsdat/config/variables/variable_attributes.py
@root_validator
def validate_units_are_commented(cls, values: Dict[str, Any]) -> Dict[str, Any]:
    if not values["units"]:
        if not values["comment"] or "Unknown units." not in values["comment"]:
            raise ValueError(
                "The 'units' attr is required if known. If the units are not known,"
                " then the 'comment' attr should include the phrase 'Unknown"
                " units.' so that users are aware that the measurement's units are"
                " not known. Note that 'unitless' quantities (e.g., categorical"
                " data, ratios, etc) should set the 'units' attr to '1'."
            )
    return values

Functions#