CdfAttributeManager

class sammi.cdf_attribute_manager.CdfAttributeManager(global_schema_layers: list[Path] | None = None, variable_schema_layers: list[Path] | None = None, use_defaults: bool | None = True)

Bases: object

Class for creating and managing CDF attributes based out of yaml files. The SAMMI default schema only includes attributes required for ISTP compliance. Additional mission-specific attributes or requirements should be added through additional global and variable schema layers.

There are two main components to the SAMMI CDF Attribut Manager, including both global and variable attribute information.

Global schema information is loaded from YAML (dict-like) files in the following format:

attribute_name:
    description: >
        Include a meaningful description of the attribute and context needed to understand
        its values.
    default: <string> # A default value for the attribute if needed/desired
    required: <bool> # Whether the attribute is required

Variable schema information is loaded from YAML (dict-like) files in the following format:

attribute_key:
    attribute_name:
        description: >
            Include a meaningful description of the attribute and context needed to understand
            its values.
        required: <bool> # Whether the attribute is required
        valid_values: <list> # A list of valid values that the attribute can take.
        alternate: <string> An additional attribute name that can be treated as an alternative of the given attribute.
data:
    - attribute_name
    - ...
support_data:
    - ...
metadata:
    - ...

Parameters:

• global_schema_layers (Optional[list[Path]]) – Absolute file paths to global attribute schema files. These schema files are layered on top of one another in a latest-priority ordering. That is, the latest file that modifies a common schema attribute will take precedence over earlier values for a given attribute.

• variable_schema_layers (Optional[list[Path]]) – Absolute file paths to variable attribute schema files. These schema files are layered on top of one another in a latest-priority ordering. That is, the latest file that modifies a common schema attribute will take precedence over earlier values for a given attribute.

• use_defaults (Optional[bool]) – Whether or not to load the default global and variable attribute schema files. These default schema files contain only the requirements for CDF ISTP validation.

Examples

To use, you can load one or many global and variable attribute files:

>>> import sammi
>>> cdf_attr_manager = sammi.cdf_attribute_manager.CdfAttributeManager(use_defaults=True)
>>> data_path = Path(sammi.__file__).parent.parent / "sammi" / "data"
>>> cdf_attr_manager.load_global_attributes(data_path / "default_global_cdf_attrs_schema.yaml")
>>> cdf_attr_manager.load_global_attributes(data_path / "default_variable_cdf_attrs_schema.yaml")
>>> cdf_attr_manager.load_variable_attributes(data_path / "variable_attrs.yaml") 

Later files will overwrite earlier files if the same attribute is defined.

You can then get the global and variable attributes:

If you provide an instrument_id, it will also add the attributes defined under instrument_id. If this is not included, then only the attributes defined in the top level of the file are used.

>>> # Instrument ID is optional for refining the attributes used from the file
>>> global_attrs = cdf_attr_manager.get_global_attributes("instrument_id")
>>> variable_attrs = cdf_attr_manager.get_variable_attributes("Epoch") 

The variable and global attributes are validated against the schemas upon calling get_global_attributes and get_variable_attributes.

Attributes Summary

global_attribute_schema	(dict) Schema for variable attributes of the file.
variable_attribute_schema	(dict) Schema for variable attributes of the file.

Methods Summary

add_global_attribute(attribute_name, ...)	Add a single global attribute to the global attributes.
add_variable_attribute(variable_name, ...)	Add a single variable attribute to the variable attributes.
get_global_attributes([instrument_id])	Generate a dictionary global attributes based off the loaded schema and attrs.
get_variable_attributes(variable_name[, ...])	Get the attributes for a given variable name.
global_attribute_info([attribute_name])	Function to generate a dict of information about each global metadata attribute.
global_attribute_template()	Function to generate a template of required global attributes that must be set for a valid data file.
load_global_attributes(file_path)	Update the global attributes property with the attributes from the file.
load_variable_attributes(file_path)	Update the variable attributes property with the attributes from the file.
variable_attribute_info([attribute_name])	Function to generate a dict of information about each variable metadata attribute.
variable_attribute_template()	Function to generate a template of required variable attributes that must be set for a valid data file.

Attributes Documentation

global_attribute_schema

(dict) Schema for variable attributes of the file.

variable_attribute_schema

(dict) Schema for variable attributes of the file.

Methods Documentation

add_global_attribute(attribute_name: str, attribute_value: str) → None

Add a single global attribute to the global attributes.

This is intended only for dynamic global attributes which change per-file, such as Data_version. It is not intended to be used for static attributes, which should all be included in the YAML files.

This will overwrite any existing value in attribute_name if it exists. The attribute must be in the global schema, or it will not be included as output.

Parameters:

• attribute_name (str) – The name of the attribute to add.

• attribute_value (str) – The value of the attribute to add.

add_variable_attribute(variable_name: str, attribute_name: str, attribute_value: str) → None

Add a single variable attribute to the variable attributes.

This is intended only for dynamic variable attributes which change per-file. It is not intended to be used for static attributes, which should all be included in the YAML files.

This will overwrite any existing value in attribute_name if it exists. The attribute must be in the variable schema, or it will not be included as output.

Parameters:

• attribute_name (str) – The name of the attribute to add.

• attribute_value (str) – The value of the attribute to add.

get_global_attributes(instrument_id: str | None = None) → dict

Generate a dictionary global attributes based off the loaded schema and attrs.

Validates against the global schema to ensure all required variables are present. It can also include instrument specific global attributes if instrumet_id is set.

If an instrument_id is provided, the level and instrument specific attributes that were previously loaded using add_instrument_global_attrs will be included.

Parameters:

instrument_id (str) – The id of the CDF file, used to retrieve instrument and level specific global attributes. Suggested value is the logical_source_id.

Returns:

output (dict) – The global attribute values created from the input global attribute files and schemas.

get_variable_attributes(variable_name: str, check_schema: bool = True) → dict

Get the attributes for a given variable name.

It retrieves the variable from previously loaded variable definition files and validates against the defined variable schemas.

Parameters:

• variable_name (str) – The name of the variable to retrieve attributes for.

• check_schema (bool) – Flag to bypass schema validation.

Returns:

dict – Information containing specific variable attributes associated with “variable_name”.

global_attribute_info(attribute_name: str | None = None) → dict

Function to generate a dict of information about each global metadata attribute. The dict contains all information in the global attribute schema including:

• description: (str) A brief description of the attribute

• default: (str) The default value used if none is provided

• required: (bool) Whether the attribute is required

Parameters:

attribute_name (str, optional, default None) – The name of the attribute to get specific information for.

Returns:

info (dict) – information about global metadata

Raises:

KeyError – If attribute_name is not a recognized global attribute.:

global_attribute_template() → dict

Function to generate a template of required global attributes that must be set for a valid data file.

Returns:

template (dict) – A template for required global attributes that must be provided.

load_global_attributes(file_path: Path) → None

Update the global attributes property with the attributes from the file.

Calling this method multiple times on different files will add all the attributes from the files, overwriting existing attributes if they are duplicated.

Parameters:

file_path (Path) – File path to load the global attributes from.

load_variable_attributes(file_path: Path) → None

Update the variable attributes property with the attributes from the file.

Calling this method multiple times on different files will add all the attributes from the files, overwriting existing attributes if they are duplicated.

Parameters:

file_path (Path) – File path to load the variable attributes from.

variable_attribute_info(attribute_name: str | None = None) → dict

Function to generate a dict of information about each variable metadata attribute. The dict contains all information in the SWxSOC variable attribute schema including:

• description: (str) A brief description of the attribute

• required: (bool) Whether the attribute is required by SWxSOC standards

• valid_values: (str) List of allowed values the attribute can take for SWxSOC products,

  if applicable

• alternate: (str) An additional attribute name that can be treated as an alternative

  of the given attribute. Not all attributes have an alternative and only one of a given attribute or its alternate are required.

• var_types: (str) A list of the variable types that require the given

  attribute to be present.

Parameters:

attribute_name (str, optional, default None) – The name of the attribute to get specific information for.

Returns:

info (dict) – information about variable metadata

Raises:

KeyError – If attribute_name is not a recognized variable attribute.:

variable_attribute_template() → dict

Function to generate a template of required variable attributes that must be set for a valid data file.

Returns:

template (dict) – A template for required variable attributes that must be provided.