Instrument Catalog

Catalog of instruments of past and present missions, in configurations compared with their data products.

An entry’s validation states how far each configuration has been validated: not every entry is fully validated, and only validated configurations have passed every test of the standard (see tatc.catalog.standard, which also evaluates the records). The schemas of entries are in tatc.catalog.schemas, and of their records in tatc.catalog.records.

@author: Paul T. Grogan <paul.grogan@asu.edu>

The entries and their results are listed in Instrument Catalog.

Entries

tatc.catalog.get_entry(entry_id: str) → InstrumentEntry[source]

Gets a catalog entry by its identifier or one of its aliases (ignoring case).

Parameters:

entry_id (str) – The identifier or alias.

Returns:

A copy of the entry.

Return type:

InstrumentEntry

Raises:

KeyError – If there is no such entry.

tatc.catalog.get_entry_ids() → list[str][source]

Gets the identifiers of the catalog entries.

Returns:

The sorted identifiers.

Return type:

list[str]

tatc.catalog.list_entries(instrument_class: InstrumentClass | str | None = None, tier: Tier | str | None = None) → list[InstrumentEntry][source]

Lists catalog entries, optionally of one class or validation tier.

Parameters:
  • instrument_class (InstrumentClass | str | None) – The class, if any.

  • tier (Tier | str | None) – The validation tier, if any.

Returns:

Copies of the entries, sorted by identifier.

Return type:

list[InstrumentEntry]

tatc.catalog.build_payload(references: str | Sequence[str], *, orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements, grade: Grade | str | None = None, time_step: float | None = None, attitude: Annotated[Attitude | TargetAttitude | GlintAttitude | AttitudeSchedule, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | AttitudeSchedule | None = None, platform: str | None = None, start: datetime | None = None, end: datetime | None = None) → InstrumentPayload[source]

Builds the instruments of one or more catalog configurations for a satellite that carries them together, with the attitude they share, to be analyzed together. Each reference is the identifier of an entry (or of one of its aliases), optionally with a configuration after a colon (such as “atms:swath_noaa_20”, or “atms:swath” for the variant tested on the platform), whose configuration is otherwise selected by grade and platform (see InstrumentEntry.select_configuration). A configuration of alternatives gives only the instrument it analyzes by default. Analyze a satellite of the payload (InstrumentPayload.to_satellite) with its instrument_index.

Parameters:
  • references (str | Sequence[str]) – The references.

  • orbit (AllOrbits) – The orbit.

  • grade (Grade | str | None) – The grade of the use, if any, which every configuration must serve.

  • time_step (float | None) – The analysis time step (seconds), for configurations that tailor a field of view to it.

  • attitude (AllAttitudes | AttitudeSchedule | None) – An attitude to use instead of the validated one, in the velocity frame of every configuration.

  • platform (str | None) – The identifier of the platform modeled, if any.

  • start (datetime.datetime | None) – The start of the analysis, for configurations that schedule their tilt by day.

  • end (datetime.datetime | None) – The end of the analysis, for configurations that schedule their tilt by day.

Returns:

The instruments, with an instrument_index of 0 for one instrument and None (analyzed together) for several.

Return type:

InstrumentPayload

Raises:
  • KeyError – If an entry is unknown.

  • ValueError – If there are no references, a configuration is unknown or does not serve the grade, or the configurations have different attitudes.

pydantic model tatc.catalog.InstrumentEntry[source]

An instrument of a past or present mission, in configurations validated against its data products.

Show JSON schema
{
   "title": "InstrumentEntry",
   "description": "An instrument of a past or present mission, in configurations validated\nagainst its data products.",
   "type": "object",
   "properties": {
      "id": {
         "description": "Entry identifier.",
         "title": "Id",
         "type": "string"
      },
      "name": {
         "description": "Instrument name.",
         "title": "Name",
         "type": "string"
      },
      "aliases": {
         "default": [],
         "description": "Other names.",
         "items": {
            "type": "string"
         },
         "title": "Aliases",
         "type": "array"
      },
      "instrument_class": {
         "$ref": "#/$defs/InstrumentClass",
         "description": "Instrument class."
      },
      "selection": {
         "description": "Why the instrument is cataloged.",
         "title": "Selection",
         "type": "string"
      },
      "platforms": {
         "description": "The platforms that carry it.",
         "items": {
            "$ref": "#/$defs/Platform"
         },
         "minItems": 1,
         "title": "Platforms",
         "type": "array"
      },
      "data_products": {
         "description": "Its principal data products.",
         "items": {
            "$ref": "#/$defs/DataProduct"
         },
         "minItems": 1,
         "title": "Data Products",
         "type": "array"
      },
      "default_configuration": {
         "description": "The configuration used if none is specified.",
         "title": "Default Configuration",
         "type": "string"
      },
      "configurations": {
         "additionalProperties": {
            "$ref": "#/$defs/Configuration"
         },
         "description": "The ways of modeling it, by identifier.",
         "minProperties": 1,
         "title": "Configurations",
         "type": "object"
      },
      "limitations": {
         "default": [],
         "description": "What no configuration represents.",
         "items": {
            "type": "string"
         },
         "title": "Limitations",
         "type": "array"
      },
      "record": {
         "anyOf": [
            {
               "$ref": "#/$defs/ValidationRecord"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The results of its validation."
      }
   },
   "$defs": {
      "Configuration": {
         "additionalProperties": false,
         "description": "A way of modeling an instrument for a use, as it was validated: instruments\nwhose views are analyzed, or a sounding (of a limb sounder or radio\noccultation receiver), whose analysis it calls.",
         "properties": {
            "grade": {
               "$ref": "#/$defs/Grade",
               "description": "The use for which it is validated."
            },
            "description": {
               "description": "What the configuration represents.",
               "title": "Description",
               "type": "string"
            },
            "platforms": {
               "description": "The platforms on which it was tested.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Platforms",
               "type": "array"
            },
            "velocity_frame": {
               "$ref": "#/$defs/VelocityFrame",
               "description": "The velocity frame of the attitude of the space system."
            },
            "attitude": {
               "additionalProperties": true,
               "description": "Other fields of the attitude of the space system: that of its body, which every instrument it carries shares, so that configurations carried together (see `build_payload`) must have the same. Angles that orient one instrument on the body, such as the yaw of its scan line, are its instrument's parameters (`yaw_angle`, `roll_angle`, and `pitch_angle` of a pointed instrument).",
               "title": "Attitude",
               "type": "object"
            },
            "tilt_schedule": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/TiltSchedule"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A pitch of the body that changes by day, from which a schedule of attitudes is built for the period of an analysis."
            },
            "instruments": {
               "default": [],
               "description": "The instruments, unless a sounding is analyzed.",
               "items": {
                  "$ref": "#/$defs/InstrumentSpecification"
               },
               "title": "Instruments",
               "type": "array"
            },
            "sounding": {
               "anyOf": [
                  {
                     "discriminator": {
                        "mapping": {
                           "limb": "#/$defs/LimbScan",
                           "occultation": "#/$defs/Occultation"
                        },
                        "propertyName": "type"
                     },
                     "oneOf": [
                        {
                           "$ref": "#/$defs/LimbScan"
                        },
                        {
                           "$ref": "#/$defs/Occultation"
                        }
                     ]
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The sounding of a limb sounder or radio occultation receiver, whose analysis is called instead of analyzing views of instruments.",
               "title": "Sounding"
            },
            "instrument_index": {
               "default": 0,
               "description": "The index of the instrument to analyze by default, of `alternatives`.",
               "minimum": 0,
               "title": "Instrument Index",
               "type": "integer"
            },
            "grouping": {
               "anyOf": [
                  {
                     "enum": [
                        "union",
                        "alternatives"
                     ],
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "How multiple instruments relate: `union`, parts of one view that are analyzed together; or `alternatives`, separately valid views that are analyzed one at a time. Only for multiple instruments.",
               "title": "Grouping"
            },
            "limitations": {
               "default": [],
               "description": "What this configuration does not represent.",
               "items": {
                  "type": "string"
               },
               "title": "Limitations",
               "type": "array"
            }
         },
         "required": [
            "grade",
            "description",
            "platforms",
            "velocity_frame"
         ],
         "title": "Configuration",
         "type": "object"
      },
      "ConfigurationRecord": {
         "additionalProperties": false,
         "description": "The results of validating a configuration, written by a validation script.",
         "properties": {
            "digest": {
               "description": "The `Configuration.digest` tested.",
               "title": "Digest",
               "type": "string"
            },
            "standard_version": {
               "description": "The `STANDARD_VERSION` of the test.",
               "title": "Standard Version",
               "type": "integer"
            },
            "tatc_version": {
               "description": "The version of TAT-C tested.",
               "title": "Tatc Version",
               "type": "string"
            },
            "source": {
               "description": "The script of the results.",
               "title": "Source",
               "type": "string"
            },
            "reference": {
               "description": "The reference data.",
               "title": "Reference",
               "type": "string"
            },
            "period": {
               "description": "The period of the reference data.",
               "title": "Period",
               "type": "string"
            },
            "platforms": {
               "description": "The platforms of the reference data.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Platforms",
               "type": "array"
            },
            "metrics": {
               "description": "The results.",
               "items": {
                  "$ref": "#/$defs/Metric"
               },
               "title": "Metrics",
               "type": "array"
            },
            "transfers": {
               "additionalProperties": {
                  "$ref": "#/$defs/Transfer"
               },
               "description": "Results on platforms on which the configuration was not tested, by platform.",
               "title": "Transfers",
               "type": "object"
            },
            "fixture_metrics": {
               "additionalProperties": {
                  "type": "number"
               },
               "description": "Results from the reduced test fixture, which detect regressions but do not themselves establish agreement with the reference data.",
               "title": "Fixture Metrics",
               "type": "object"
            }
         },
         "required": [
            "digest",
            "standard_version",
            "tatc_version",
            "source",
            "reference",
            "period",
            "platforms",
            "metrics"
         ],
         "title": "ConfigurationRecord",
         "type": "object"
      },
      "DataProduct": {
         "additionalProperties": false,
         "description": "A data product of an instrument.",
         "properties": {
            "name": {
               "description": "Product name.",
               "title": "Name",
               "type": "string"
            },
            "provider": {
               "description": "The organization that distributes it.",
               "title": "Provider",
               "type": "string"
            },
            "url": {
               "description": "Where to find it.",
               "title": "Url",
               "type": "string"
            },
            "access": {
               "description": "`open`, or free with `registration`.",
               "enum": [
                  "open",
                  "registration"
               ],
               "title": "Access",
               "type": "string"
            }
         },
         "required": [
            "name",
            "provider",
            "url",
            "access"
         ],
         "title": "DataProduct",
         "type": "object"
      },
      "Grade": {
         "description": "Enumeration of the uses for which a configuration is validated.",
         "enum": [
            "coverage",
            "timing",
            "sample_size"
         ],
         "title": "Grade",
         "type": "string"
      },
      "InstrumentClass": {
         "description": "Enumeration of instrument classes, which select the applicable gates.",
         "enum": [
            "cross_track",
            "pushbroom",
            "conical",
            "sar",
            "geostationary",
            "geostationary_regional",
            "lidar",
            "altimeter",
            "scatterometer",
            "profiler",
            "limb",
            "occultation"
         ],
         "title": "InstrumentClass",
         "type": "string"
      },
      "InstrumentSpecification": {
         "additionalProperties": false,
         "description": "The class and parameters of an instrument, from which objects are constructed.\nThe provenance of an along-track field of view tailored to the time step and\nof `is_swept` may be omitted, as it is the same in every configuration.",
         "properties": {
            "type": {
               "description": "The instrument class: `instrument`, `pointed`, or `conical` (the `type` of its schema).",
               "title": "Type",
               "type": "string"
            },
            "parameters": {
               "additionalProperties": true,
               "description": "The instrument's fields.",
               "title": "Parameters",
               "type": "object"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each parameter, except for its name.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "type",
            "parameters"
         ],
         "title": "InstrumentSpecification",
         "type": "object"
      },
      "LimbScan": {
         "additionalProperties": false,
         "description": "The vertical scans of a limb sounder, with which `collect_limb_observations`\nis called: scans of the same elevations, in a cycle of scans (one or more,\nsuch as alternating upward and downward scans) that repeats from the start of\nan analysis. The phase of the cycle, which depends on the instrument's clock,\nis not modeled.",
         "properties": {
            "type": {
               "const": "limb",
               "default": "limb",
               "description": "The kind of sounding.",
               "title": "Type",
               "type": "string"
            },
            "scan_azimuth": {
               "description": "The viewing azimuth (degrees) from the inertial velocity, in the local horizontal plane (0 forward, 90 to the left, toward the orbit normal).",
               "exclusiveMaximum": 360,
               "minimum": 0,
               "title": "Scan Azimuth",
               "type": "number"
            },
            "scan_elevations": {
               "description": "The tangent point elevations (meters) of the samples of a scan.",
               "items": {
                  "type": "number"
               },
               "minItems": 2,
               "title": "Scan Elevations",
               "type": "array"
            },
            "scan_duration": {
               "description": "The time (seconds) to sweep the elevations.",
               "exclusiveMinimum": 0,
               "title": "Scan Duration",
               "type": "number"
            },
            "scans": {
               "description": "The starts of the scans of a cycle.",
               "items": {
                  "$ref": "#/$defs/ScanStart"
               },
               "minItems": 1,
               "title": "Scans",
               "type": "array"
            },
            "cycle_period": {
               "description": "The time (seconds) between starts of the cycle.",
               "exclusiveMinimum": 0,
               "title": "Cycle Period",
               "type": "number"
            },
            "sample_elevation": {
               "description": "The tangent point elevation (meters) of the representative position and time of each scan.",
               "title": "Sample Elevation",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "scan_azimuth",
            "scan_elevations",
            "scan_duration",
            "scans",
            "cycle_period",
            "sample_elevation",
            "provenance"
         ],
         "title": "LimbScan",
         "type": "object"
      },
      "Metric": {
         "additionalProperties": false,
         "description": "A value of a metric from a comparison with reference data.",
         "properties": {
            "name": {
               "description": "The metric (see `get_gates`).",
               "title": "Name",
               "type": "string"
            },
            "value": {
               "description": "The value.",
               "title": "Value",
               "type": "number"
            },
            "scope": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The part or condition of the test it applies to (such as an instrument or a time step), if not all of it. A gate takes the worst value of its metric over scopes.",
               "title": "Scope"
            }
         },
         "required": [
            "name",
            "value"
         ],
         "title": "Metric",
         "type": "object"
      },
      "Occultation": {
         "additionalProperties": false,
         "description": "The radio occultations of a receiver of signals of navigation satellites, with\nwhich `collect_ro_observations` is called.",
         "properties": {
            "type": {
               "const": "occultation",
               "default": "occultation",
               "description": "The kind of sounding.",
               "title": "Type",
               "type": "string"
            },
            "constellations": {
               "description": "The constellations of transmitters tracked (such as `gps`, `glonass`, `galileo`, or `beidou`), whose satellites are the transmitters of an analysis.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Constellations",
               "type": "array"
            },
            "max_yaw": {
               "description": "The maximum yaw (degrees) of a transmitter from the receiver's velocity or anti-velocity, for a valid occultation.",
               "exclusiveMaximum": 90,
               "exclusiveMinimum": 0,
               "title": "Max Yaw",
               "type": "number"
            },
            "range_elevation": {
               "description": "The lower and upper tangent point elevations (meters) of a valid occultation.",
               "maxItems": 2,
               "minItems": 2,
               "prefixItems": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "number"
                  }
               ],
               "title": "Range Elevation",
               "type": "array"
            },
            "sample_elevation": {
               "description": "The tangent point elevation (meters, of the straight line, without refraction) of the representative position and time.",
               "title": "Sample Elevation",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "constellations",
            "max_yaw",
            "range_elevation",
            "sample_elevation",
            "provenance"
         ],
         "title": "Occultation",
         "type": "object"
      },
      "Platform": {
         "additionalProperties": false,
         "description": "A platform that carries an instrument, with its status on a date.",
         "properties": {
            "id": {
               "description": "Platform identifier.",
               "title": "Id",
               "type": "string"
            },
            "name": {
               "description": "Platform name.",
               "title": "Name",
               "type": "string"
            },
            "norad_id": {
               "description": "NORAD catalog number, from which to obtain current orbital elements, which are not cataloged because they age.",
               "exclusiveMinimum": 0,
               "title": "Norad Id",
               "type": "integer"
            },
            "status": {
               "description": "The status on the date `as_of`.",
               "enum": [
                  "operational",
                  "extended",
                  "retired"
               ],
               "title": "Status",
               "type": "string"
            },
            "as_of": {
               "description": "The date of the status.",
               "format": "date",
               "title": "As Of",
               "type": "string"
            }
         },
         "required": [
            "id",
            "name",
            "norad_id",
            "status",
            "as_of"
         ],
         "title": "Platform",
         "type": "object"
      },
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      },
      "ScanDirection": {
         "description": "Enumeration of the two broad classes of limb sounder vertical scan:\nsweeping from the lowest to the highest requested tangent point\nelevation (`UPWARD`), or the reverse (`DOWNWARD`).",
         "enum": [
            "upward",
            "downward"
         ],
         "title": "ScanDirection",
         "type": "string"
      },
      "ScanStart": {
         "additionalProperties": false,
         "description": "The start of a vertical scan in a limb sounder's cycle of scans.",
         "properties": {
            "offset": {
               "description": "The time (seconds) from the start of the cycle.",
               "minimum": 0,
               "title": "Offset",
               "type": "number"
            },
            "direction": {
               "$ref": "#/$defs/ScanDirection",
               "description": "Whether the scan sweeps `upward` or `downward`."
            }
         },
         "required": [
            "offset",
            "direction"
         ],
         "title": "ScanStart",
         "type": "object"
      },
      "TiltSchedule": {
         "additionalProperties": false,
         "description": "A pitch of the body that changes between aft and fore twice an orbit, on a\nschedule that depends on the day, as OCI's tilt does to avoid sun glint. After\nthe ascending node, the pitch changes from aft to fore where the satellite's\ngeodetic latitude reaches the subsolar latitude at noon (UTC) of the day plus an\noffset that alternates with the parity of the day of the year (UTC); it changes\nback at a fixed argument of latitude. Each change is linear over an arc of the\norbit, within an interval in which the instruments do not observe.",
         "properties": {
            "fore_pitch_angle": {
               "description": "The pitch angle (degrees) of the fore tilt.",
               "maximum": 90,
               "minimum": -90,
               "title": "Fore Pitch Angle",
               "type": "number"
            },
            "aft_pitch_angle": {
               "description": "The pitch angle (degrees) of the aft tilt.",
               "maximum": 90,
               "minimum": -90,
               "title": "Aft Pitch Angle",
               "type": "number"
            },
            "odd_day_offset": {
               "description": "On days of odd day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
               "maximum": 45,
               "minimum": -45,
               "title": "Odd Day Offset",
               "type": "number"
            },
            "even_day_offset": {
               "description": "On days of even day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
               "maximum": 45,
               "minimum": -45,
               "title": "Even Day Offset",
               "type": "number"
            },
            "transition": {
               "description": "The arc of argument of latitude (degrees) over which each change is linear.",
               "exclusiveMaximum": 90,
               "exclusiveMinimum": 0,
               "title": "Transition",
               "type": "number"
            },
            "return_argument_of_latitude": {
               "description": "The argument of latitude (degrees) of the middle of the change back to aft.",
               "maximum": 270,
               "minimum": 90,
               "title": "Return Argument Of Latitude",
               "type": "number"
            },
            "blind_before": {
               "description": "The time (seconds) before the middle of each change from which the instruments do not observe.",
               "maximum": 600,
               "minimum": 0,
               "title": "Blind Before",
               "type": "number"
            },
            "blind_after": {
               "description": "The time (seconds) after the middle of each change at which the instruments observe again.",
               "maximum": 600,
               "minimum": 0,
               "title": "Blind After",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "fore_pitch_angle",
            "aft_pitch_angle",
            "odd_day_offset",
            "even_day_offset",
            "transition",
            "return_argument_of_latitude",
            "blind_before",
            "blind_after",
            "provenance"
         ],
         "title": "TiltSchedule",
         "type": "object"
      },
      "Transfer": {
         "additionalProperties": false,
         "description": "The results of a configuration on a platform on which it was not tested,\nwhich do not count toward its validation.",
         "properties": {
            "period": {
               "description": "The period of the reference data.",
               "title": "Period",
               "type": "string"
            },
            "metrics": {
               "description": "The results.",
               "items": {
                  "$ref": "#/$defs/Metric"
               },
               "minItems": 1,
               "title": "Metrics",
               "type": "array"
            }
         },
         "required": [
            "period",
            "metrics"
         ],
         "title": "Transfer",
         "type": "object"
      },
      "ValidationRecord": {
         "additionalProperties": false,
         "description": "The results of validating the configurations of an entry.",
         "properties": {
            "entry_id": {
               "description": "The identifier of the entry.",
               "title": "Entry Id",
               "type": "string"
            },
            "configurations": {
               "additionalProperties": {
                  "$ref": "#/$defs/ConfigurationRecord"
               },
               "description": "The results of each configuration.",
               "title": "Configurations",
               "type": "object"
            }
         },
         "required": [
            "entry_id",
            "configurations"
         ],
         "title": "ValidationRecord",
         "type": "object"
      },
      "VelocityFrame": {
         "description": "Enumeration of reference frames for the velocity vector that defines an\ninstrument's along-track direction (and hence its cross-track direction,\northogonal to velocity and nadir).",
         "enum": [
            "earth_fixed",
            "inertial"
         ],
         "title": "VelocityFrame",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "required": [
      "id",
      "name",
      "instrument_class",
      "selection",
      "platforms",
      "data_products",
      "default_configuration",
      "configurations"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
  • aliases (tuple[str, ...])

  • configurations (dict[str, tatc.catalog.schemas.Configuration])

  • data_products (tuple[tatc.catalog.schemas.DataProduct, ...])

  • default_configuration (str)

  • id (str)

  • instrument_class (tatc.catalog.standard.InstrumentClass)

  • limitations (tuple[str, ...])

  • name (str)

  • platforms (tuple[tatc.catalog.schemas.Platform, ...])

  • record (tatc.catalog.records.ValidationRecord | None)

  • selection (str)

Validators:
  • _check_references » all fields

field aliases: tuple[str, ...] = ()

Other names.

Validated by:
  • _check_references

field configurations: dict[str, Configuration] [Required]

The ways of modeling it, by identifier.

Constraints:
  • min_length = 1

Validated by:
  • _check_references

field data_products: tuple[DataProduct, ...] [Required]

Its principal data products.

Constraints:
  • min_length = 1

Validated by:
  • _check_references

field default_configuration: str [Required]

The configuration used if none is specified.

Validated by:
  • _check_references

field id: str [Required]

Entry identifier.

Validated by:
  • _check_references

field instrument_class: InstrumentClass [Required]

Instrument class.

Validated by:
  • _check_references

field limitations: tuple[str, ...] = ()

What no configuration represents.

Validated by:
  • _check_references

field name: str [Required]

Instrument name.

Validated by:
  • _check_references

field platforms: tuple[Platform, ...] [Required]

The platforms that carry it.

Constraints:
  • min_length = 1

Validated by:
  • _check_references

field record: ValidationRecord | None = None

The results of its validation.

Validated by:
  • _check_references

field selection: str [Required]

Why the instrument is cataloged.

Validated by:
  • _check_references

build(*, configuration: str | None = None, grade: Grade | str | None = None, orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements | None = None, time_step: float | None = None, attitude: Annotated[Attitude | TargetAttitude | GlintAttitude | AttitudeSchedule, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | AttitudeSchedule | None = None, platform: str | None = None, start: datetime | None = None, end: datetime | None = None) → InstrumentPayload[source]

Builds the instruments of a configuration with the attitude they were validated with. Each call builds new objects.

Parameters:
  • configuration (str | None) – The identifier of the configuration, or a name of its variants (such as swath for swath_noaa_20), or None to select one by grade and platform (see select_configuration), by default the default configuration.

  • grade (Grade | str | None) – The grade of the use, if any.

  • orbit (AllOrbits | None) – The orbit, if the configuration tailors a field of view to a time step or schedules its tilt.

  • time_step (float | None) – The analysis time step (seconds), if the configuration tailors a field of view to it.

  • attitude (AllAttitudes | AttitudeSchedule | None) – An attitude to use instead of the validated one (for example, a schedule of yaw flips), in the same velocity frame.

  • platform (str | None) – The identifier of the platform modeled, if any, which selects the configuration tested on it. Using a configuration on a platform on which it was not tested gives a warning.

  • start (datetime.datetime | None) – The start of the analysis (timezone-aware), if the configuration schedules its tilt by day.

  • end (datetime.datetime | None) – The end of the analysis (timezone-aware), if the configuration schedules its tilt by day.

Returns:

The instruments, attitude, and analysis settings.

Return type:

InstrumentPayload

Raises:

ValueError – If the configuration is unknown or does not serve the grade, tailoring lacks an orbit or time step, a schedule lacks an orbit or the period of the analysis, or an attitude has another velocity frame.

get_variants(name: str) → list[str][source]

Gets the configurations that a name refers to: the configuration of that identifier, or else those whose identifier is the name followed by their platform (such as swath_noaa_20 and swath_noaa_21 for swath), in an entry with configurations tested on different platforms.

Parameters:

name (str) – The name.

Returns:

The identifiers of the configurations, empty if none.

Return type:

list[str]

select_configuration(configuration: str | None = None, *, grade: Grade | str | None = None, platform: str | None = None) → str[source]

Selects a configuration: one that serves a use (see Configuration.serves) and was tested on a platform, preferring the default configuration and then those at the grade of the default. A name selects among the configurations it refers to (see get_variants), so that swath selects swath_noaa_21 for the platform noaa-21, and otherwise prefers the platforms of the default configuration. Without a configuration tested on the platform, it selects among the others (a transfer, on which build warns).

Parameters:
  • configuration (str | None) – The identifier of the configuration, or a name of its variants (see get_variants), or None to select any configuration.

  • grade (Grade | str | None) – The grade of the use, if any.

  • platform (str | None) – The identifier of the platform modeled, if any.

Returns:

The identifier of the configuration.

Return type:

str

Raises:

ValueError – If the configuration is unknown, or none serves the use.

to_satellite(orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements, *, configuration: str | None = None, grade: Grade | str | None = None, time_step: float | None = None, attitude: Annotated[Attitude | TargetAttitude | GlintAttitude | AttitudeSchedule, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | AttitudeSchedule | None = None, platform: str | None = None, name: str | None = None, start: datetime | None = None, end: datetime | None = None) → Satellite[source]

Builds a satellite that carries the instruments of a configuration (see build), which is analyzed with an instrument_index of 0, as the analysis functions do by default. A configuration analyzed otherwise (the parts of one view, or alternatives that analyze another instrument by default) needs build(…).to_satellite(orbit, name=name) and the payload’s instrument_index.

Parameters:
  • orbit (AllOrbits) – The orbit.

  • configuration (str | None) – The identifier of the configuration, or a name of its variants, or None to select one by grade and platform (see select_configuration).

  • grade (Grade | str | None) – The grade of the use, if any.

  • time_step (float | None) – The analysis time step (seconds), if the configuration tailors a field of view to it.

  • attitude (AllAttitudes | AttitudeSchedule | None) – An attitude to use instead of the validated one.

  • platform (str | None) – The identifier of the platform modeled.

  • name (str | None) – The satellite’s name, or None for the instrument’s.

  • start (datetime.datetime | None) – The start of the analysis, if the configuration schedules its tilt by day.

  • end (datetime.datetime | None) – The end of the analysis, if the configuration schedules its tilt by day.

Returns:

The satellite.

Return type:

Satellite

Raises:

ValueError – If the configuration is not analyzed with an instrument_index of 0.

property validation: EntryValidation

The validation status of this entry, computed from its records and the standard rather than declared (see tatc.catalog.standard.evaluate_entry).

class tatc.catalog.InstrumentPayload(instruments: list[Instrument], attitude: Annotated[Attitude | TargetAttitude | GlintAttitude | AttitudeSchedule, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | AttitudeSchedule | None, instrument_index: int | None, references: tuple[str, ...], transferred: bool, limitations: tuple[str, ...], sounding: LimbScan | Occultation | None = None)[source]

Instruments with the attitude that they were validated with, which must be used together. Analyze them with the instrument_index: of the instrument to analyze, or None to analyze the instruments together (as the parts of one view).

references: tuple[str, ...]

configuration`.

Type:

The configurations, as `entry

sounding: LimbScan | Occultation | None = None

The sounding whose analysis is called (with collect_observations), instead of analyzing views of instruments, if any.

to_satellite(orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements, *, name: str) → Satellite[source]

Builds a satellite that carries the instruments with their attitude. Analyze it with the instrument_index of this payload, or, for a sounding, with the sounding’s collect_observations, for which the satellite carries TAT-C’s default instrument.

Parameters:
  • orbit (AllOrbits) – The orbit.

  • name (str) – The satellite’s name.

Returns:

The satellite.

Return type:

Satellite

transferred: bool

Whether a configuration was not tested on the platform modeled.

Validation Status

See Validation Standard.

class tatc.catalog.EntryValidation(tier: Tier, configurations: dict[str, ConfigurationValidation], missing_grades: tuple[Grade, ...])[source]

The validation status of an entry, computed from its records and the standard: of each configuration, and the grades of its class that no configuration serves (missing_grades).

property gaps: tuple[str, ...]

of missing grades, then of each configuration, after its identifier (such as “swath: epoch_p95: not tested”).

Type:

Every gap

to_frame() → DataFrame[source]

Tabulates the gates of every configuration.

Returns:

A row for each gate of each configuration, with its configuration, grade, tier, metric label, value (NaN if not tested), formatted limit, and whether it passed (None if not tested).

Return type:

pandas.DataFrame

class tatc.catalog.ConfigurationValidation(tier: Tier, grade: Grade, gates: tuple[GateResult, ...], evidence_gaps: tuple[str, ...], record: ConfigurationRecord | None, holdout_gap_days: int | None = None)[source]

The validation status of a configuration: the results of its gates, and its evidence_gaps, of its test rather than of a gate (such as a configuration that changed after it was tested). Its holdout_gap_days are the days between the data to which its values were fitted and the data of its test, or None if it has no fitted values or no test.

property gaps: tuple[str, ...]

of failed gates, then of untested gates, then of evidence.

Type:

Every gap

class tatc.catalog.GateResult(gate: Gate, value: float | None)[source]

The outcome of a gate: None if the metric was not tested.

property gap: str | None

The gap, if the gate failed or was not tested.

property passed: bool | None

Whether the gate is met, or None if it was not tested.

class tatc.catalog.Tier(value)[source]

Enumeration of validation tiers, from weakest to strongest.

NOMINAL = 'nominal'

Published values, without results compared with reference data.

PARTIAL = 'partial'

Some gates are unmet or untested, or the evidence is incomplete.

VALIDATED = 'validated'

All applicable gates pass, with results of the configuration as cataloged.

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

property rank: int

The strength of the tier, from 0 (nominal) to 2 (validated).

class tatc.catalog.Grade(value)[source]

Enumeration of the uses for which a configuration is validated.

COVERAGE = 'coverage'

Which points and regions are observed, with epochs to a few seconds.

SAMPLE_SIZE = 'sample_size'

The size, spacing, and position of samples on the ground.

TIMING = 'timing'

As for coverage, with epochs to about a second.

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class tatc.catalog.InstrumentClass(value)[source]

Enumeration of instrument classes, which select the applicable gates.

__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

Schemas

The schemas of the files of entries.

pydantic model tatc.catalog.schemas.Configuration[source]

A way of modeling an instrument for a use, as it was validated: instruments whose views are analyzed, or a sounding (of a limb sounder or radio occultation receiver), whose analysis it calls.

Show JSON schema
{
   "title": "Configuration",
   "description": "A way of modeling an instrument for a use, as it was validated: instruments\nwhose views are analyzed, or a sounding (of a limb sounder or radio\noccultation receiver), whose analysis it calls.",
   "type": "object",
   "properties": {
      "grade": {
         "$ref": "#/$defs/Grade",
         "description": "The use for which it is validated."
      },
      "description": {
         "description": "What the configuration represents.",
         "title": "Description",
         "type": "string"
      },
      "platforms": {
         "description": "The platforms on which it was tested.",
         "items": {
            "type": "string"
         },
         "minItems": 1,
         "title": "Platforms",
         "type": "array"
      },
      "velocity_frame": {
         "$ref": "#/$defs/VelocityFrame",
         "description": "The velocity frame of the attitude of the space system."
      },
      "attitude": {
         "additionalProperties": true,
         "description": "Other fields of the attitude of the space system: that of its body, which every instrument it carries shares, so that configurations carried together (see `build_payload`) must have the same. Angles that orient one instrument on the body, such as the yaw of its scan line, are its instrument's parameters (`yaw_angle`, `roll_angle`, and `pitch_angle` of a pointed instrument).",
         "title": "Attitude",
         "type": "object"
      },
      "tilt_schedule": {
         "anyOf": [
            {
               "$ref": "#/$defs/TiltSchedule"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A pitch of the body that changes by day, from which a schedule of attitudes is built for the period of an analysis."
      },
      "instruments": {
         "default": [],
         "description": "The instruments, unless a sounding is analyzed.",
         "items": {
            "$ref": "#/$defs/InstrumentSpecification"
         },
         "title": "Instruments",
         "type": "array"
      },
      "sounding": {
         "anyOf": [
            {
               "discriminator": {
                  "mapping": {
                     "limb": "#/$defs/LimbScan",
                     "occultation": "#/$defs/Occultation"
                  },
                  "propertyName": "type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/LimbScan"
                  },
                  {
                     "$ref": "#/$defs/Occultation"
                  }
               ]
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The sounding of a limb sounder or radio occultation receiver, whose analysis is called instead of analyzing views of instruments.",
         "title": "Sounding"
      },
      "instrument_index": {
         "default": 0,
         "description": "The index of the instrument to analyze by default, of `alternatives`.",
         "minimum": 0,
         "title": "Instrument Index",
         "type": "integer"
      },
      "grouping": {
         "anyOf": [
            {
               "enum": [
                  "union",
                  "alternatives"
               ],
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "How multiple instruments relate: `union`, parts of one view that are analyzed together; or `alternatives`, separately valid views that are analyzed one at a time. Only for multiple instruments.",
         "title": "Grouping"
      },
      "limitations": {
         "default": [],
         "description": "What this configuration does not represent.",
         "items": {
            "type": "string"
         },
         "title": "Limitations",
         "type": "array"
      }
   },
   "$defs": {
      "Grade": {
         "description": "Enumeration of the uses for which a configuration is validated.",
         "enum": [
            "coverage",
            "timing",
            "sample_size"
         ],
         "title": "Grade",
         "type": "string"
      },
      "InstrumentSpecification": {
         "additionalProperties": false,
         "description": "The class and parameters of an instrument, from which objects are constructed.\nThe provenance of an along-track field of view tailored to the time step and\nof `is_swept` may be omitted, as it is the same in every configuration.",
         "properties": {
            "type": {
               "description": "The instrument class: `instrument`, `pointed`, or `conical` (the `type` of its schema).",
               "title": "Type",
               "type": "string"
            },
            "parameters": {
               "additionalProperties": true,
               "description": "The instrument's fields.",
               "title": "Parameters",
               "type": "object"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each parameter, except for its name.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "type",
            "parameters"
         ],
         "title": "InstrumentSpecification",
         "type": "object"
      },
      "LimbScan": {
         "additionalProperties": false,
         "description": "The vertical scans of a limb sounder, with which `collect_limb_observations`\nis called: scans of the same elevations, in a cycle of scans (one or more,\nsuch as alternating upward and downward scans) that repeats from the start of\nan analysis. The phase of the cycle, which depends on the instrument's clock,\nis not modeled.",
         "properties": {
            "type": {
               "const": "limb",
               "default": "limb",
               "description": "The kind of sounding.",
               "title": "Type",
               "type": "string"
            },
            "scan_azimuth": {
               "description": "The viewing azimuth (degrees) from the inertial velocity, in the local horizontal plane (0 forward, 90 to the left, toward the orbit normal).",
               "exclusiveMaximum": 360,
               "minimum": 0,
               "title": "Scan Azimuth",
               "type": "number"
            },
            "scan_elevations": {
               "description": "The tangent point elevations (meters) of the samples of a scan.",
               "items": {
                  "type": "number"
               },
               "minItems": 2,
               "title": "Scan Elevations",
               "type": "array"
            },
            "scan_duration": {
               "description": "The time (seconds) to sweep the elevations.",
               "exclusiveMinimum": 0,
               "title": "Scan Duration",
               "type": "number"
            },
            "scans": {
               "description": "The starts of the scans of a cycle.",
               "items": {
                  "$ref": "#/$defs/ScanStart"
               },
               "minItems": 1,
               "title": "Scans",
               "type": "array"
            },
            "cycle_period": {
               "description": "The time (seconds) between starts of the cycle.",
               "exclusiveMinimum": 0,
               "title": "Cycle Period",
               "type": "number"
            },
            "sample_elevation": {
               "description": "The tangent point elevation (meters) of the representative position and time of each scan.",
               "title": "Sample Elevation",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "scan_azimuth",
            "scan_elevations",
            "scan_duration",
            "scans",
            "cycle_period",
            "sample_elevation",
            "provenance"
         ],
         "title": "LimbScan",
         "type": "object"
      },
      "Occultation": {
         "additionalProperties": false,
         "description": "The radio occultations of a receiver of signals of navigation satellites, with\nwhich `collect_ro_observations` is called.",
         "properties": {
            "type": {
               "const": "occultation",
               "default": "occultation",
               "description": "The kind of sounding.",
               "title": "Type",
               "type": "string"
            },
            "constellations": {
               "description": "The constellations of transmitters tracked (such as `gps`, `glonass`, `galileo`, or `beidou`), whose satellites are the transmitters of an analysis.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Constellations",
               "type": "array"
            },
            "max_yaw": {
               "description": "The maximum yaw (degrees) of a transmitter from the receiver's velocity or anti-velocity, for a valid occultation.",
               "exclusiveMaximum": 90,
               "exclusiveMinimum": 0,
               "title": "Max Yaw",
               "type": "number"
            },
            "range_elevation": {
               "description": "The lower and upper tangent point elevations (meters) of a valid occultation.",
               "maxItems": 2,
               "minItems": 2,
               "prefixItems": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "number"
                  }
               ],
               "title": "Range Elevation",
               "type": "array"
            },
            "sample_elevation": {
               "description": "The tangent point elevation (meters, of the straight line, without refraction) of the representative position and time.",
               "title": "Sample Elevation",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "constellations",
            "max_yaw",
            "range_elevation",
            "sample_elevation",
            "provenance"
         ],
         "title": "Occultation",
         "type": "object"
      },
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      },
      "ScanDirection": {
         "description": "Enumeration of the two broad classes of limb sounder vertical scan:\nsweeping from the lowest to the highest requested tangent point\nelevation (`UPWARD`), or the reverse (`DOWNWARD`).",
         "enum": [
            "upward",
            "downward"
         ],
         "title": "ScanDirection",
         "type": "string"
      },
      "ScanStart": {
         "additionalProperties": false,
         "description": "The start of a vertical scan in a limb sounder's cycle of scans.",
         "properties": {
            "offset": {
               "description": "The time (seconds) from the start of the cycle.",
               "minimum": 0,
               "title": "Offset",
               "type": "number"
            },
            "direction": {
               "$ref": "#/$defs/ScanDirection",
               "description": "Whether the scan sweeps `upward` or `downward`."
            }
         },
         "required": [
            "offset",
            "direction"
         ],
         "title": "ScanStart",
         "type": "object"
      },
      "TiltSchedule": {
         "additionalProperties": false,
         "description": "A pitch of the body that changes between aft and fore twice an orbit, on a\nschedule that depends on the day, as OCI's tilt does to avoid sun glint. After\nthe ascending node, the pitch changes from aft to fore where the satellite's\ngeodetic latitude reaches the subsolar latitude at noon (UTC) of the day plus an\noffset that alternates with the parity of the day of the year (UTC); it changes\nback at a fixed argument of latitude. Each change is linear over an arc of the\norbit, within an interval in which the instruments do not observe.",
         "properties": {
            "fore_pitch_angle": {
               "description": "The pitch angle (degrees) of the fore tilt.",
               "maximum": 90,
               "minimum": -90,
               "title": "Fore Pitch Angle",
               "type": "number"
            },
            "aft_pitch_angle": {
               "description": "The pitch angle (degrees) of the aft tilt.",
               "maximum": 90,
               "minimum": -90,
               "title": "Aft Pitch Angle",
               "type": "number"
            },
            "odd_day_offset": {
               "description": "On days of odd day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
               "maximum": 45,
               "minimum": -45,
               "title": "Odd Day Offset",
               "type": "number"
            },
            "even_day_offset": {
               "description": "On days of even day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
               "maximum": 45,
               "minimum": -45,
               "title": "Even Day Offset",
               "type": "number"
            },
            "transition": {
               "description": "The arc of argument of latitude (degrees) over which each change is linear.",
               "exclusiveMaximum": 90,
               "exclusiveMinimum": 0,
               "title": "Transition",
               "type": "number"
            },
            "return_argument_of_latitude": {
               "description": "The argument of latitude (degrees) of the middle of the change back to aft.",
               "maximum": 270,
               "minimum": 90,
               "title": "Return Argument Of Latitude",
               "type": "number"
            },
            "blind_before": {
               "description": "The time (seconds) before the middle of each change from which the instruments do not observe.",
               "maximum": 600,
               "minimum": 0,
               "title": "Blind Before",
               "type": "number"
            },
            "blind_after": {
               "description": "The time (seconds) after the middle of each change at which the instruments observe again.",
               "maximum": 600,
               "minimum": 0,
               "title": "Blind After",
               "type": "number"
            },
            "provenance": {
               "additionalProperties": {
                  "$ref": "#/$defs/Provenance"
               },
               "description": "The origin of each value.",
               "title": "Provenance",
               "type": "object"
            }
         },
         "required": [
            "fore_pitch_angle",
            "aft_pitch_angle",
            "odd_day_offset",
            "even_day_offset",
            "transition",
            "return_argument_of_latitude",
            "blind_before",
            "blind_after",
            "provenance"
         ],
         "title": "TiltSchedule",
         "type": "object"
      },
      "VelocityFrame": {
         "description": "Enumeration of reference frames for the velocity vector that defines an\ninstrument's along-track direction (and hence its cross-track direction,\northogonal to velocity and nadir).",
         "enum": [
            "earth_fixed",
            "inertial"
         ],
         "title": "VelocityFrame",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "required": [
      "grade",
      "description",
      "platforms",
      "velocity_frame"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _check_instruments » all fields

field attitude: dict[str, Any] [Optional]

Other fields of the attitude of the space system: that of its body, which every instrument it carries shares, so that configurations carried together (see build_payload) must have the same. Angles that orient one instrument on the body, such as the yaw of its scan line, are its instrument’s parameters (yaw_angle, roll_angle, and pitch_angle of a pointed instrument).

Validated by:
  • _check_instruments

field description: str [Required]

What the configuration represents.

Validated by:
  • _check_instruments

field grade: Grade [Required]

The use for which it is validated.

Validated by:
  • _check_instruments

field grouping: Literal['union', 'alternatives'] | None = None

How multiple instruments relate: union, parts of one view that are analyzed together; or alternatives, separately valid views that are analyzed one at a time. Only for multiple instruments.

Validated by:
  • _check_instruments

field instrument_index: int = 0

The index of the instrument to analyze by default, of alternatives.

Constraints:
  • ge = 0

Validated by:
  • _check_instruments

field instruments: tuple[InstrumentSpecification, ...] = ()

The instruments, unless a sounding is analyzed.

Validated by:
  • _check_instruments

field limitations: tuple[str, ...] = ()

What this configuration does not represent.

Validated by:
  • _check_instruments

field platforms: tuple[str, ...] [Required]

The platforms on which it was tested.

Constraints:
  • min_length = 1

Validated by:
  • _check_instruments

field sounding: AllSoundings | None = None

The sounding of a limb sounder or radio occultation receiver, whose analysis is called instead of analyzing views of instruments.

Validated by:
  • _check_instruments

field tilt_schedule: TiltSchedule | None = None

A pitch of the body that changes by day, from which a schedule of attitudes is built for the period of an analysis.

Validated by:
  • _check_instruments

field velocity_frame: VelocityFrame [Required]

The velocity frame of the attitude of the space system.

Validated by:
  • _check_instruments

get_holdout_gap(period: str) → int | None[source]

Gets the days between the data to which values were fitted and the data of a test: between the nearest days of the periods.

Parameters:

period (str) – The period of the data of the test (see Period).

Returns:

The days, or None if no value was fitted.

Return type:

int | None

make_attitude() → Attitude | GlintAttitude | TargetAttitude[source]

Makes the attitude of the configuration: of the type its type names (attitude by default, glint, or target), in its velocity frame.

Returns:

The attitude.

Return type:

Attitude | GlintAttitude | TargetAttitude

serves(grade: Grade | str) → bool[source]

Checks whether this configuration serves a use (see tatc.catalog.standard.serves).

Parameters:

grade (Grade | str) – The grade of the use.

Returns:

True, if it serves the use.

Return type:

bool

property digest: str

A digest of the values that affect analysis results, with which a validation record identifies the configuration it tested.

pydantic model tatc.catalog.schemas.InstrumentSpecification[source]

The class and parameters of an instrument, from which objects are constructed. The provenance of an along-track field of view tailored to the time step and of is_swept may be omitted, as it is the same in every configuration.

Show JSON schema
{
   "title": "InstrumentSpecification",
   "description": "The class and parameters of an instrument, from which objects are constructed.\nThe provenance of an along-track field of view tailored to the time step and\nof `is_swept` may be omitted, as it is the same in every configuration.",
   "type": "object",
   "properties": {
      "type": {
         "description": "The instrument class: `instrument`, `pointed`, or `conical` (the `type` of its schema).",
         "title": "Type",
         "type": "string"
      },
      "parameters": {
         "additionalProperties": true,
         "description": "The instrument's fields.",
         "title": "Parameters",
         "type": "object"
      },
      "provenance": {
         "additionalProperties": {
            "$ref": "#/$defs/Provenance"
         },
         "description": "The origin of each parameter, except for its name.",
         "title": "Provenance",
         "type": "object"
      }
   },
   "$defs": {
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "type",
      "parameters"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _add_default_provenance » all fields

  • _check_parameters » all fields

field parameters: dict[str, Any] [Required]

The instrument’s fields.

Validated by:
  • _add_default_provenance

  • _check_parameters

field provenance: dict[str, Provenance] [Optional]

The origin of each parameter, except for its name.

Validated by:
  • _add_default_provenance

  • _check_parameters

field type: str [Required]

The instrument class: instrument, pointed, or conical (the type of its schema).

Validated by:
  • _add_default_provenance

  • _check_parameters

construct_instrument(tailored_field_of_view: float | None) → Instrument[source]

Constructs a new instrument that shares no state with this specification.

Parameters:

tailored_field_of_view (float | None) – The along-track field of view (degrees), if this specification tailors it to a time step.

Returns:

The instrument.

Return type:

Instrument

property is_tailored: bool

Whether the along-track field of view is tailored to a time step.

pydantic model tatc.catalog.schemas.Provenance[source]

The origin of a parameter value.

Show JSON schema
{
   "title": "Provenance",
   "description": "The origin of a parameter value.",
   "type": "object",
   "properties": {
      "kind": {
         "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
         "enum": [
            "nominal",
            "measured",
            "derived",
            "placeholder"
         ],
         "title": "Kind",
         "type": "string"
      },
      "source": {
         "description": "Where the value comes from.",
         "title": "Source",
         "type": "string"
      },
      "platforms": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The platforms to whose data a measured value was fitted.",
         "title": "Platforms"
      },
      "period": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
         "title": "Period"
      }
   },
   "additionalProperties": false,
   "required": [
      "kind",
      "source"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _check_measured » all fields

field kind: Literal['nominal', 'measured', 'derived', 'placeholder'] [Required]

Origin of the value: nominal, a published specification; measured, fitted to reference data; derived, computed from other values; or placeholder, without physical meaning.

Validated by:
  • _check_measured

field period: Period | None = None

The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.

Validated by:
  • _check_measured

field platforms: tuple[str, ...] | None = None

The platforms to whose data a measured value was fitted.

Constraints:
  • min_length = 1

Validated by:
  • _check_measured

field source: str [Required]

Where the value comes from.

Validated by:
  • _check_measured

pydantic model tatc.catalog.schemas.TiltSchedule[source]

A pitch of the body that changes between aft and fore twice an orbit, on a schedule that depends on the day, as OCI’s tilt does to avoid sun glint. After the ascending node, the pitch changes from aft to fore where the satellite’s geodetic latitude reaches the subsolar latitude at noon (UTC) of the day plus an offset that alternates with the parity of the day of the year (UTC); it changes back at a fixed argument of latitude. Each change is linear over an arc of the orbit, within an interval in which the instruments do not observe.

Show JSON schema
{
   "title": "TiltSchedule",
   "description": "A pitch of the body that changes between aft and fore twice an orbit, on a\nschedule that depends on the day, as OCI's tilt does to avoid sun glint. After\nthe ascending node, the pitch changes from aft to fore where the satellite's\ngeodetic latitude reaches the subsolar latitude at noon (UTC) of the day plus an\noffset that alternates with the parity of the day of the year (UTC); it changes\nback at a fixed argument of latitude. Each change is linear over an arc of the\norbit, within an interval in which the instruments do not observe.",
   "type": "object",
   "properties": {
      "fore_pitch_angle": {
         "description": "The pitch angle (degrees) of the fore tilt.",
         "maximum": 90,
         "minimum": -90,
         "title": "Fore Pitch Angle",
         "type": "number"
      },
      "aft_pitch_angle": {
         "description": "The pitch angle (degrees) of the aft tilt.",
         "maximum": 90,
         "minimum": -90,
         "title": "Aft Pitch Angle",
         "type": "number"
      },
      "odd_day_offset": {
         "description": "On days of odd day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
         "maximum": 45,
         "minimum": -45,
         "title": "Odd Day Offset",
         "type": "number"
      },
      "even_day_offset": {
         "description": "On days of even day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.",
         "maximum": 45,
         "minimum": -45,
         "title": "Even Day Offset",
         "type": "number"
      },
      "transition": {
         "description": "The arc of argument of latitude (degrees) over which each change is linear.",
         "exclusiveMaximum": 90,
         "exclusiveMinimum": 0,
         "title": "Transition",
         "type": "number"
      },
      "return_argument_of_latitude": {
         "description": "The argument of latitude (degrees) of the middle of the change back to aft.",
         "maximum": 270,
         "minimum": 90,
         "title": "Return Argument Of Latitude",
         "type": "number"
      },
      "blind_before": {
         "description": "The time (seconds) before the middle of each change from which the instruments do not observe.",
         "maximum": 600,
         "minimum": 0,
         "title": "Blind Before",
         "type": "number"
      },
      "blind_after": {
         "description": "The time (seconds) after the middle of each change at which the instruments observe again.",
         "maximum": 600,
         "minimum": 0,
         "title": "Blind After",
         "type": "number"
      },
      "provenance": {
         "additionalProperties": {
            "$ref": "#/$defs/Provenance"
         },
         "description": "The origin of each value.",
         "title": "Provenance",
         "type": "object"
      }
   },
   "$defs": {
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "fore_pitch_angle",
      "aft_pitch_angle",
      "odd_day_offset",
      "even_day_offset",
      "transition",
      "return_argument_of_latitude",
      "blind_before",
      "blind_after",
      "provenance"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _check_provenance » all fields

field aft_pitch_angle: float [Required]

The pitch angle (degrees) of the aft tilt.

Constraints:
  • ge = -90

  • le = 90

Validated by:
  • _check_provenance

field blind_after: float [Required]

The time (seconds) after the middle of each change at which the instruments observe again.

Constraints:
  • ge = 0

  • le = 600

Validated by:
  • _check_provenance

field blind_before: float [Required]

The time (seconds) before the middle of each change from which the instruments do not observe.

Constraints:
  • ge = 0

  • le = 600

Validated by:
  • _check_provenance

field even_day_offset: float [Required]

On days of even day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.

Constraints:
  • ge = -45

  • le = 45

Validated by:
  • _check_provenance

field fore_pitch_angle: float [Required]

The pitch angle (degrees) of the fore tilt.

Constraints:
  • ge = -90

  • le = 90

Validated by:
  • _check_provenance

field odd_day_offset: float [Required]

On days of odd day of the year, the latitude (degrees) of the change to fore, from the subsolar latitude.

Constraints:
  • ge = -45

  • le = 45

Validated by:
  • _check_provenance

field provenance: dict[str, Provenance] [Required]

The origin of each value.

Validated by:
  • _check_provenance

field return_argument_of_latitude: float [Required]

The argument of latitude (degrees) of the middle of the change back to aft.

Constraints:
  • ge = 90

  • le = 270

Validated by:
  • _check_provenance

field transition: float [Required]

The arc of argument of latitude (degrees) over which each change is linear.

Constraints:
  • gt = 0

  • lt = 90

Validated by:
  • _check_provenance

build_schedule(orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements, start: datetime, end: datetime, velocity_frame: VelocityFrame, attitude: dict[str, Any]) → AttitudeSchedule[source]

Builds a schedule of attitudes, one for each day (UTC) from the start to the end of an analysis.

Parameters:
  • orbit (AllOrbits) – The orbit.

  • start (datetime.datetime) – The start of the analysis (timezone-aware).

  • end (datetime.datetime) – The end of the analysis (timezone-aware).

  • velocity_frame (VelocityFrame) – The velocity frame of the attitude.

  • attitude (dict[str, Any]) – Other fields of the attitude.

Returns:

The schedule.

Return type:

AttitudeSchedule

get_blind_intervals(day: date, orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements) → list[tuple[float, float]] | None[source]

Gets the intervals of argument of latitude (degrees) of a day in which the instruments do not observe, around each change, at the orbit’s mean rate.

Parameters:
  • day (datetime.date) – The day (UTC).

  • orbit (AllOrbits) – The orbit.

Returns:

The (start, end) pairs, or None if

the instruments always observe.

Return type:

list[tuple[float, float]] | None

get_pitch_angle_profile(day: date, orbit: CircularOrbit | GeneralPerturbationsOrbit | GeosynchronousOrbit | KeplerianOrbit | MolniyaOrbit | SunSynchronousOrbit | TundraOrbit | TwoLineElements) → list[tuple[float, float]][source]

Gets the pitch angle profile of a day, as (argument of latitude, pitch angle) pairs.

Parameters:
  • day (datetime.date) – The day (UTC).

  • orbit (AllOrbits) – The orbit.

Returns:

The profile.

Return type:

list[tuple[float, float]]

get_switch_latitude(day: date) → float[source]

Gets the geodetic latitude (degrees) at which the pitch changes from aft to fore on a day.

Parameters:

day (datetime.date) – The day (UTC).

Returns:

The latitude (degrees).

Return type:

float

pydantic model tatc.catalog.schemas.LimbScan[source]

The vertical scans of a limb sounder, with which collect_limb_observations is called: scans of the same elevations, in a cycle of scans (one or more, such as alternating upward and downward scans) that repeats from the start of an analysis. The phase of the cycle, which depends on the instrument’s clock, is not modeled.

Show JSON schema
{
   "title": "LimbScan",
   "description": "The vertical scans of a limb sounder, with which `collect_limb_observations`\nis called: scans of the same elevations, in a cycle of scans (one or more,\nsuch as alternating upward and downward scans) that repeats from the start of\nan analysis. The phase of the cycle, which depends on the instrument's clock,\nis not modeled.",
   "type": "object",
   "properties": {
      "type": {
         "const": "limb",
         "default": "limb",
         "description": "The kind of sounding.",
         "title": "Type",
         "type": "string"
      },
      "scan_azimuth": {
         "description": "The viewing azimuth (degrees) from the inertial velocity, in the local horizontal plane (0 forward, 90 to the left, toward the orbit normal).",
         "exclusiveMaximum": 360,
         "minimum": 0,
         "title": "Scan Azimuth",
         "type": "number"
      },
      "scan_elevations": {
         "description": "The tangent point elevations (meters) of the samples of a scan.",
         "items": {
            "type": "number"
         },
         "minItems": 2,
         "title": "Scan Elevations",
         "type": "array"
      },
      "scan_duration": {
         "description": "The time (seconds) to sweep the elevations.",
         "exclusiveMinimum": 0,
         "title": "Scan Duration",
         "type": "number"
      },
      "scans": {
         "description": "The starts of the scans of a cycle.",
         "items": {
            "$ref": "#/$defs/ScanStart"
         },
         "minItems": 1,
         "title": "Scans",
         "type": "array"
      },
      "cycle_period": {
         "description": "The time (seconds) between starts of the cycle.",
         "exclusiveMinimum": 0,
         "title": "Cycle Period",
         "type": "number"
      },
      "sample_elevation": {
         "description": "The tangent point elevation (meters) of the representative position and time of each scan.",
         "title": "Sample Elevation",
         "type": "number"
      },
      "provenance": {
         "additionalProperties": {
            "$ref": "#/$defs/Provenance"
         },
         "description": "The origin of each value.",
         "title": "Provenance",
         "type": "object"
      }
   },
   "$defs": {
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      },
      "ScanDirection": {
         "description": "Enumeration of the two broad classes of limb sounder vertical scan:\nsweeping from the lowest to the highest requested tangent point\nelevation (`UPWARD`), or the reverse (`DOWNWARD`).",
         "enum": [
            "upward",
            "downward"
         ],
         "title": "ScanDirection",
         "type": "string"
      },
      "ScanStart": {
         "additionalProperties": false,
         "description": "The start of a vertical scan in a limb sounder's cycle of scans.",
         "properties": {
            "offset": {
               "description": "The time (seconds) from the start of the cycle.",
               "minimum": 0,
               "title": "Offset",
               "type": "number"
            },
            "direction": {
               "$ref": "#/$defs/ScanDirection",
               "description": "Whether the scan sweeps `upward` or `downward`."
            }
         },
         "required": [
            "offset",
            "direction"
         ],
         "title": "ScanStart",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "scan_azimuth",
      "scan_elevations",
      "scan_duration",
      "scans",
      "cycle_period",
      "sample_elevation",
      "provenance"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _check_scans » all fields

field cycle_period: float [Required]

The time (seconds) between starts of the cycle.

Constraints:
  • gt = 0

Validated by:
  • _check_scans

field provenance: dict[str, Provenance] [Required]

The origin of each value.

Validated by:
  • _check_scans

field sample_elevation: float [Required]

The tangent point elevation (meters) of the representative position and time of each scan.

Validated by:
  • _check_scans

field scan_azimuth: float [Required]

The viewing azimuth (degrees) from the inertial velocity, in the local horizontal plane (0 forward, 90 to the left, toward the orbit normal).

Constraints:
  • ge = 0

  • lt = 360

Validated by:
  • _check_scans

field scan_duration: float [Required]

The time (seconds) to sweep the elevations.

Constraints:
  • gt = 0

Validated by:
  • _check_scans

field scan_elevations: tuple[float, ...] [Required]

The tangent point elevations (meters) of the samples of a scan.

Constraints:
  • min_length = 2

Validated by:
  • _check_scans

field scans: tuple[ScanStart, ...] [Required]

The starts of the scans of a cycle.

Constraints:
  • min_length = 1

Validated by:
  • _check_scans

field type: Literal['limb'] = 'limb'

The kind of sounding.

Validated by:
  • _check_scans

collect_observations(satellites: Satellite | list[Satellite], start: datetime, end: datetime) → GeoDataFrame[source]

Collects the limb sounding observations of scans that repeat from the start of an analysis (see tatc.analysis.collect_limb_observations).

Parameters:
Returns:

The observations of the scans, by time.

Return type:

geopandas.GeoDataFrame

get_scan_times(start: datetime, end: datetime) → dict[ScanDirection, list[datetime]][source]

Gets the start times of the scans of each direction, in cycles that repeat from the start of an analysis until its end.

Parameters:
Returns:

The start times, by direction.

Return type:

dict[ScanDirection, list[datetime.datetime]]

pydantic model tatc.catalog.schemas.ScanStart[source]

The start of a vertical scan in a limb sounder’s cycle of scans.

Show JSON schema
{
   "title": "ScanStart",
   "description": "The start of a vertical scan in a limb sounder's cycle of scans.",
   "type": "object",
   "properties": {
      "offset": {
         "description": "The time (seconds) from the start of the cycle.",
         "minimum": 0,
         "title": "Offset",
         "type": "number"
      },
      "direction": {
         "$ref": "#/$defs/ScanDirection",
         "description": "Whether the scan sweeps `upward` or `downward`."
      }
   },
   "$defs": {
      "ScanDirection": {
         "description": "Enumeration of the two broad classes of limb sounder vertical scan:\nsweeping from the lowest to the highest requested tangent point\nelevation (`UPWARD`), or the reverse (`DOWNWARD`).",
         "enum": [
            "upward",
            "downward"
         ],
         "title": "ScanDirection",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "required": [
      "offset",
      "direction"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
field direction: ScanDirection [Required]

Whether the scan sweeps upward or downward.

field offset: float [Required]

The time (seconds) from the start of the cycle.

Constraints:
  • ge = 0

pydantic model tatc.catalog.schemas.Occultation[source]

The radio occultations of a receiver of signals of navigation satellites, with which collect_ro_observations is called.

Show JSON schema
{
   "title": "Occultation",
   "description": "The radio occultations of a receiver of signals of navigation satellites, with\nwhich `collect_ro_observations` is called.",
   "type": "object",
   "properties": {
      "type": {
         "const": "occultation",
         "default": "occultation",
         "description": "The kind of sounding.",
         "title": "Type",
         "type": "string"
      },
      "constellations": {
         "description": "The constellations of transmitters tracked (such as `gps`, `glonass`, `galileo`, or `beidou`), whose satellites are the transmitters of an analysis.",
         "items": {
            "type": "string"
         },
         "minItems": 1,
         "title": "Constellations",
         "type": "array"
      },
      "max_yaw": {
         "description": "The maximum yaw (degrees) of a transmitter from the receiver's velocity or anti-velocity, for a valid occultation.",
         "exclusiveMaximum": 90,
         "exclusiveMinimum": 0,
         "title": "Max Yaw",
         "type": "number"
      },
      "range_elevation": {
         "description": "The lower and upper tangent point elevations (meters) of a valid occultation.",
         "maxItems": 2,
         "minItems": 2,
         "prefixItems": [
            {
               "type": "number"
            },
            {
               "type": "number"
            }
         ],
         "title": "Range Elevation",
         "type": "array"
      },
      "sample_elevation": {
         "description": "The tangent point elevation (meters, of the straight line, without refraction) of the representative position and time.",
         "title": "Sample Elevation",
         "type": "number"
      },
      "provenance": {
         "additionalProperties": {
            "$ref": "#/$defs/Provenance"
         },
         "description": "The origin of each value.",
         "title": "Provenance",
         "type": "object"
      }
   },
   "$defs": {
      "Provenance": {
         "additionalProperties": false,
         "description": "The origin of a parameter value.",
         "properties": {
            "kind": {
               "description": "Origin of the value: `nominal`, a published specification; `measured`, fitted to reference data; `derived`, computed from other values; or `placeholder`, without physical meaning.",
               "enum": [
                  "nominal",
                  "measured",
                  "derived",
                  "placeholder"
               ],
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Where the value comes from.",
               "title": "Source",
               "type": "string"
            },
            "platforms": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "minItems": 1,
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The platforms to whose data a measured value was fitted.",
               "title": "Platforms"
            },
            "period": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The period of the data to which a measured value was fitted, from which the gap to the data of its tests is computed.",
               "title": "Period"
            }
         },
         "required": [
            "kind",
            "source"
         ],
         "title": "Provenance",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "constellations",
      "max_yaw",
      "range_elevation",
      "sample_elevation",
      "provenance"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
Validators:
  • _check_values » all fields

field constellations: tuple[str, ...] [Required]

The constellations of transmitters tracked (such as gps, glonass, galileo, or beidou), whose satellites are the transmitters of an analysis.

Constraints:
  • min_length = 1

Validated by:
  • _check_values

field max_yaw: float [Required]

The maximum yaw (degrees) of a transmitter from the receiver’s velocity or anti-velocity, for a valid occultation.

Constraints:
  • gt = 0

  • lt = 90

Validated by:
  • _check_values

field provenance: dict[str, Provenance] [Required]

The origin of each value.

Validated by:
  • _check_values

field range_elevation: tuple[float, float] [Required]

The lower and upper tangent point elevations (meters) of a valid occultation.

Validated by:
  • _check_values

field sample_elevation: float [Required]

The tangent point elevation (meters, of the straight line, without refraction) of the representative position and time.

Validated by:
  • _check_values

field type: Literal['occultation'] = 'occultation'

The kind of sounding.

Validated by:
  • _check_values

collect_observations(receivers: Satellite | list[Satellite], transmitters: Satellite | list[Satellite], start: datetime, end: datetime, time_step: timedelta = datetime.timedelta(seconds=10)) → GeoDataFrame[source]

Collects the radio occultation observations of receivers (see tatc.analysis.collect_ro_observations).

Parameters:
Returns:

The occultations.

Return type:

geopandas.GeoDataFrame

Records

The schemas of the validation records of entries.

pydantic model tatc.catalog.records.ConfigurationRecord[source]

The results of validating a configuration, written by a validation script.

Show JSON schema
{
   "title": "ConfigurationRecord",
   "description": "The results of validating a configuration, written by a validation script.",
   "type": "object",
   "properties": {
      "digest": {
         "description": "The `Configuration.digest` tested.",
         "title": "Digest",
         "type": "string"
      },
      "standard_version": {
         "description": "The `STANDARD_VERSION` of the test.",
         "title": "Standard Version",
         "type": "integer"
      },
      "tatc_version": {
         "description": "The version of TAT-C tested.",
         "title": "Tatc Version",
         "type": "string"
      },
      "source": {
         "description": "The script of the results.",
         "title": "Source",
         "type": "string"
      },
      "reference": {
         "description": "The reference data.",
         "title": "Reference",
         "type": "string"
      },
      "period": {
         "description": "The period of the reference data.",
         "title": "Period",
         "type": "string"
      },
      "platforms": {
         "description": "The platforms of the reference data.",
         "items": {
            "type": "string"
         },
         "minItems": 1,
         "title": "Platforms",
         "type": "array"
      },
      "metrics": {
         "description": "The results.",
         "items": {
            "$ref": "#/$defs/Metric"
         },
         "title": "Metrics",
         "type": "array"
      },
      "transfers": {
         "additionalProperties": {
            "$ref": "#/$defs/Transfer"
         },
         "description": "Results on platforms on which the configuration was not tested, by platform.",
         "title": "Transfers",
         "type": "object"
      },
      "fixture_metrics": {
         "additionalProperties": {
            "type": "number"
         },
         "description": "Results from the reduced test fixture, which detect regressions but do not themselves establish agreement with the reference data.",
         "title": "Fixture Metrics",
         "type": "object"
      }
   },
   "$defs": {
      "Metric": {
         "additionalProperties": false,
         "description": "A value of a metric from a comparison with reference data.",
         "properties": {
            "name": {
               "description": "The metric (see `get_gates`).",
               "title": "Name",
               "type": "string"
            },
            "value": {
               "description": "The value.",
               "title": "Value",
               "type": "number"
            },
            "scope": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The part or condition of the test it applies to (such as an instrument or a time step), if not all of it. A gate takes the worst value of its metric over scopes.",
               "title": "Scope"
            }
         },
         "required": [
            "name",
            "value"
         ],
         "title": "Metric",
         "type": "object"
      },
      "Transfer": {
         "additionalProperties": false,
         "description": "The results of a configuration on a platform on which it was not tested,\nwhich do not count toward its validation.",
         "properties": {
            "period": {
               "description": "The period of the reference data.",
               "title": "Period",
               "type": "string"
            },
            "metrics": {
               "description": "The results.",
               "items": {
                  "$ref": "#/$defs/Metric"
               },
               "minItems": 1,
               "title": "Metrics",
               "type": "array"
            }
         },
         "required": [
            "period",
            "metrics"
         ],
         "title": "Transfer",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "digest",
      "standard_version",
      "tatc_version",
      "source",
      "reference",
      "period",
      "platforms",
      "metrics"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
field digest: str [Required]

The Configuration.digest tested.

field fixture_metrics: dict[str, float] [Optional]

Results from the reduced test fixture, which detect regressions but do not themselves establish agreement with the reference data.

field metrics: tuple[Metric, ...] [Required]

The results.

field period: Period [Required]

The period of the reference data.

Constraints:
  • func = <function _check_period at 0x77a2b8ad5b40>

field platforms: tuple[str, ...] [Required]

The platforms of the reference data.

Constraints:
  • min_length = 1

field reference: str [Required]

The reference data.

field source: str [Required]

The script of the results.

field standard_version: int [Required]

The STANDARD_VERSION of the test.

field tatc_version: str [Required]

The version of TAT-C tested.

field transfers: dict[str, Transfer] [Optional]

Results on platforms on which the configuration was not tested, by platform.

pydantic model tatc.catalog.records.Transfer[source]

The results of a configuration on a platform on which it was not tested, which do not count toward its validation.

Show JSON schema
{
   "title": "Transfer",
   "description": "The results of a configuration on a platform on which it was not tested,\nwhich do not count toward its validation.",
   "type": "object",
   "properties": {
      "period": {
         "description": "The period of the reference data.",
         "title": "Period",
         "type": "string"
      },
      "metrics": {
         "description": "The results.",
         "items": {
            "$ref": "#/$defs/Metric"
         },
         "minItems": 1,
         "title": "Metrics",
         "type": "array"
      }
   },
   "$defs": {
      "Metric": {
         "additionalProperties": false,
         "description": "A value of a metric from a comparison with reference data.",
         "properties": {
            "name": {
               "description": "The metric (see `get_gates`).",
               "title": "Name",
               "type": "string"
            },
            "value": {
               "description": "The value.",
               "title": "Value",
               "type": "number"
            },
            "scope": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The part or condition of the test it applies to (such as an instrument or a time step), if not all of it. A gate takes the worst value of its metric over scopes.",
               "title": "Scope"
            }
         },
         "required": [
            "name",
            "value"
         ],
         "title": "Metric",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "period",
      "metrics"
   ]
}

Config:
  • extra: str = forbid

  • frozen: bool = True

Fields:
field metrics: tuple[Metric, ...] [Required]

The results.

Constraints:
  • min_length = 1

field period: Period [Required]

The period of the reference data.

Constraints:
  • func = <function _check_period at 0x77a2b8ad5b40>

tatc.catalog.records.get_period_days(period: str) → tuple[tuple[date, date], ...][source]

Gets the days of a period: one or more items separated by commas, each a date or a time with a zone in ISO 8601 (such as 2026-10-02 or 2026-10-03T12:00Z), or a range of dates (2026-08-15 to 2026-10-08).

Parameters:

period (str) – The period.

Returns:

The first and last day (UTC) of each item.

Return type:

tuple[tuple[datetime.date, datetime.date], …]

Raises:

ValueError – If the period is not of this form.

Standard

The standard against which catalog entries are validated, and its evaluation of their records (evaluate_entry).

The acceptance thresholds are frozen so that they test new instruments rather than following their results: changing one requires a new STANDARD_VERSION. See docs/validation/standard.rst for their back-test against earlier results.

@author: Paul T. Grogan <paul.grogan@asu.edu>

tatc.catalog.standard.COMPATIBLE_VERSIONS = (1, 2, 3, 4, 5, 6, 7)

Versions whose results still apply, as no threshold changed after the first: later versions only added classes (see is_compatible).

class tatc.catalog.standard.Gate(metric: str, limit: float, at_most: bool, unit: str, label: str = '')[source]

An acceptance threshold on a metric, with the metric’s label for display (by default, its name).

format_limit() → str[source]

Formats the threshold, such as “≤ 5 km”.

Returns:

The threshold, with its unit.

Return type:

str

format_value(value: float) → str[source]

Formats a value of the metric, with enough decimals that its rounded value meets this gate exactly when the value does.

Parameters:

value (float) – The value.

Returns:

The value, with its unit.

Return type:

str

is_met(value: float) → bool[source]

Checks whether a value of the metric meets this gate.

Parameters:

value (float) – The value.

Returns:

True, if the value meets the threshold.

Return type:

bool

tatc.catalog.standard.MIN_HOLDOUT_GAP_DAYS = 30

Minimum days between the fitting data of measured values and their test data.

tatc.catalog.standard.STANDARD_VERSION = 7

The version of the thresholds in get_gates.

tatc.catalog.standard.evaluate_entry(entry: InstrumentEntry) → EntryValidation[source]

Applies the standard to an entry’s records. An entry is only as strong as its weakest configuration, needs configurations that serve the grades of its class (see get_required_grades), and is partial rather than nominal if any configuration was compared with reference data.

Parameters:

entry (InstrumentEntry) – The entry.

Returns:

Its validation status.

Return type:

EntryValidation

tatc.catalog.standard.get_gates(instrument_class: InstrumentClass, grade: Grade) → tuple[Gate, ...][source]

Gets the gates of a configuration.

Parameters:
  • instrument_class (InstrumentClass) – The class of the instrument.

  • grade (Grade) – The grade of the configuration.

Returns:

The applicable gates.

Return type:

tuple[Gate, …]

Raises:

ValueError – If the class is not validated at the grade.

tatc.catalog.standard.get_required_grades(instrument_class: InstrumentClass) → tuple[Grade, ...][source]

Gets the grades that an entry needs to be validated: the coverage grade, and the sample size grade if its class has one. A configuration at the timing grade also meets the coverage grade, as timing also tests coverage.

Parameters:

instrument_class (InstrumentClass) – The class of the instrument.

Returns:

The required grades.

Return type:

tuple[Grade, …]

tatc.catalog.standard.is_compatible(instrument_class: InstrumentClass, version: int) → bool[source]

Checks whether results tested under a version of the standard apply to a class: the version is compatible and has the class’s gates. Version 2 added the lidar class, 3 the altimeter class, 4 the scatterometer class, 5 the regional geostationary class, 6 the profiler class, and 7 the limb and occultation classes.

Parameters:
  • instrument_class (InstrumentClass) – The class of the instrument.

  • version (int) – The version of the standard.

Returns:

True, if the results apply.

Return type:

bool

tatc.catalog.standard.serves(configuration_grade: Grade | str, grade: Grade | str) → bool[source]

Checks whether a configuration at a grade serves a use: its own grade, or the coverage grade for a configuration at the timing grade, which also tests coverage.

Parameters:
  • configuration_grade (Grade | str) – The grade of the configuration.

  • grade (Grade | str) – The grade of the use.

Returns:

True, if it serves the use.

Return type:

bool

Metrics

Metrics that compare analysis results with reference data.

These depend only on numpy, so they can run in unit tests as well as in validation notebooks.

@author: Paul T. Grogan <paul.grogan@asu.edu>

tatc.catalog.metrics.compute_mask_iou(first: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], second: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], weights: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None) → float[source]

Computes the intersection over union of two masks on the same grid.

Parameters:
  • first (npt.ArrayLike) – The first boolean mask.

  • second (npt.ArrayLike) – The second boolean mask.

  • weights (npt.ArrayLike | None) – The weight of each cell (for example, its area), or None for equal weights.

Returns:

The intersection over union.

Return type:

float

Raises:

ValueError – If the union of the masks is empty.

tatc.catalog.metrics.compute_pass_scores(matched: int, observed: int, predicted: int) → dict[str, float][source]

Computes the agreement between observed and predicted passes.

Parameters:
  • matched (int) – The number of observed passes that were predicted.

  • observed (int) – The number of observed passes.

  • predicted (int) – The number of predicted passes.

Returns:

The percentages pass_recall, of observed passes that were predicted, and pass_precision, of predicted passes that were observed.

Return type:

dict[str, float]

Raises:

ValueError – If there are no passes, or more matches than passes.

tatc.catalog.metrics.compute_product_limit_error(zenith: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], observed: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], bound: float) → float[source]

Computes how far the boundary of predicted observations lies from a product’s declared bound of local zenith angle.

Parameters:
  • zenith (npt.ArrayLike) – The local zenith angle (degrees) of each pixel.

  • observed (npt.ArrayLike) – Whether each pixel is predicted to be observed.

  • bound (float) – The declared bound (degrees).

Returns:

The largest distance (degrees) from the bound of the greatest angle observed and the smallest angle not observed.

Return type:

float

Raises:

ValueError – If the pixels are not on both sides of the boundary.

tatc.catalog.metrics.summarize(values: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → dict[str, float][source]

Summarizes a sample of residuals, ignoring values that are not finite.

Parameters:

values (npt.ArrayLike) – The residuals.

Returns:

The number of values n, median, and the 95th percentile p95 and maximum max of their absolute values.

Return type:

dict[str, float]

Raises:

ValueError – If there are no finite values.