Introduction

The goal of MT Metadata is to develop a standard format and tools for archiving magnetotelluric (MT) time series and transfer function data.

Metadata standards for MT have been historically relaxed to user dependent. The goal of this module is to formalize and provide tools for users of MT timeseries and metadata.

The metadata for time series follows the standards proposed by the IRIS-PASSCAL MT Software working group published at Peacock, J.R., Frassetto, A., Kelbert, A., Egbert, G., Smirnov, M., Schultz, A.C., Kappler, K.N., Ronan, T., and Trabant, C., 2021, Metadata Standards for Magnetotelluric Time Series Data: U.S. Geological Survey data release, ` <https://doi.org/10.5066/P9AXGKEV>`__.

The metadata for transfer functions follows those proposed by Anna Kelbert EMTF XML: New data interchange format and conversion tools for electromagnetic transfer functions.

Architecture

MT Metadata is built on Pydantic BaseModel objects, providing a robust and modern approach to metadata management. This architectural choice offers several key advantages:

Data Validation

Pydantic provides automatic validation of metadata attributes, ensuring data integrity and type safety. Invalid data is caught immediately with clear error messages, preventing downstream issues.

Performance

Pydantic’s Rust-based core (v2+) delivers exceptional performance for serialization, deserialization, and validation operations, making metadata handling efficient even for large datasets.

Maintainability

The declarative syntax and type hints make the codebase more readable and maintainable. IDE support provides better autocomplete and inline documentation, reducing development errors.

Serialization

Built-in support for JSON, dictionary, and other formats simplifies data interchange. Metadata can be easily exported, shared, and stored in various formats.

Extensibility

Custom validators and field types allow for domain-specific validation rules while maintaining a consistent API across all metadata classes.

This modern foundation ensures MT Metadata remains robust, performant, and easy to extend as standards evolve.

MetadataBase

All metadata classes in MT Metadata inherit from MetadataBase, a specialized Pydantic BaseModel that provides a consistent interface for defining and managing MT metadata attributes.

Field Definition

Fields in MetadataBase are defined using Pydantic’s Field descriptor, which encapsulates both the data type and metadata about each attribute:

from pydantic import Field

class Station(MetadataBase):
    id: str = Field(
        default="",
        description="Station identification name",
        json_schema_extra={"style": "name", "required": True}
    )
    latitude: float = Field(
        default=0.0,
        description="Latitude in decimal degrees WGS84",
        json_schema_extra={"units": "degrees", "style": "number"}
    )
Field Attributes

Each field can specify:

  • default: The default value if not provided

  • description: Human-readable documentation

  • json_schema_extra: Additional metadata including units, style, options, and validation rules

  • type annotations: Python type hints for automatic validation

Benefits

This approach provides:

  • Self-documenting code: Field descriptions and types serve as inline documentation

  • Automatic validation: Type checking and custom validators ensure data integrity

  • JSON Schema generation: Automatic schema creation for API documentation and validation

  • Consistent API: All metadata objects share the same interface for getting/setting attributes

The MetadataBase class also provides methods for serialization (to_dict, to_json), comparison, and updating attributes, ensuring a uniform experience across all metadata types.

Note

This version is stable, but if you encounter any issues or have suggestions, feel free to comment by raising an issue on GitHub in the repository mt_metadata