"""

====================
Observation Families
====================

In the CMC assimilation cycle, RDB files are generated during the cycles and are stored within the ``monitoring/banco/`` directory. **This RDB format is the exact type of file that Pikobs reads and processes** across all its modules.

.. tip::
   For more in-depth technical information regarding the structure and usage of RDB files at CMC, please refer to the official internal documentation: `CMC RDB-USAGE Wiki <https://wiki.cmc.ec.gc.ca/wiki/RDB-USAGE#Introduction>`_.

Assimilation Stages & Directories
---------------------------------

Data files are organized into three main subdirectories inside ``monitoring/banco/``, corresponding to the specific stage of the assimilation cycle. Each file follows the naming convention ``YYYYMMDDHH_<family>`` (e.g., ``2022053100_atms_allsky``).

evalalt (Evaluation)
    Typically contains background-checked observations **just before final thinning**.

    * **Near-surface data:** The file extension is ``sf_qc`` (even if the *derialt* extension was ``sf2``).
    * **LAM domains:** Observations in these files are already clipped to the Limited Area Model domain.
    * **Missing Types:** ``evalalt`` files are not produced for some observation types (e.g., currently, ozone, radar, satellite winds).
    * **Exceptions:** Exceptionally, ``ua`` (radiosonde) evalalts are produced in the derivate.

bgckalt (Background Check)
    Contains background-checked observations **after the application of final thinning**.

    * **Metrics:** Contains the **O-B** (Observation minus Background) value for each observation.
    * **Thinning Process:** Final (spatio-temporal) thinning is currently done by a MIDAS subroutine. Formerly, these were stand-alone programs generally referred to as "thinning1".
    * **IC4 GDPS Updates:** As of IC4, the GDPS uses ``sf2`` data (not ``sf``) and applies a final (temporal) thinning. At the same time, colocated observations are removed (both within networks and across networks).
    * **Near-surface data:** The file extension is ``sf`` (even if the *derialt* extension was ``sf2``).

postalt (Post-Analysis)
    Contains observations **after assimilation** is complete.

    * **Metrics:** Contains the **O-A** (Observation minus Analysis) value for each observation.
    * **Status Verification:** These files are used to check if an observation was successfully assimilated or rejected by the system.

Supported Observation Families
------------------------------

Pikobs supports comprehensive statistical monitoring for the following major observation types. When using the command-line interface, pass the exact shortcode (e.g., ``--family atms_allsky``) based on these categories:

Conventional Observations
~~~~~~~~~~~~~~~~~~~~~~~~

**ai (AIRCRAFT)**
    Aircraft-based meteorological observations (AIREP/AMDAR), providing vital wind and temperature profiles at flight levels. *(evalalt suffix: ai_qc)*

**gp (GROUND-BASED GPS)**
    Ground-based Global Positioning System meteorological data, primarily measuring Zenith Total Delay (ZTD) to estimate atmospheric water vapor. *(evalalt suffix: gp_qc)*

**sf (SURFACE)**
    Surface meteorological observations originating from land stations (SYNOP, METAR), ships, and moored or drifting ocean buoys. *(evalalt suffix: sf_qc)*

**ua (UPPER AIR / RAOBS)**
    Radiosonde observations (weather balloons) providing high-resolution vertical profiles of temperature, humidity, and wind from the surface to the stratosphere.

Radar Observations
~~~~~~~~~~~~~~~~~

**ra (RADAR / DOPPLER VELOCITY)**
    Weather radar observations, specifically measuring Doppler radial velocity. Crucial for high-resolution wind field analysis and severe weather monitoring. *(Not produced in evalalt)*

Satellite & Microwave Observations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**atms / atms_allsky (ATMS)**
    Advanced Technology Microwave Sounder observations, providing crucial temperature and moisture sounding capabilities under clear-sky and all-sky conditions.

**cris (CrIS)**
    Cross-track Infrared Sounder radiance data, offering high-spectral-resolution infrared observations for detailed atmospheric sounding. *(evalalt suffix: crisfsr1_qc / crisfsr2_qc)*

**csr (CSR)**
    Clear Sky Radiances or Compact Scatterometer Radar observations, used to retrieve surface wind vectors or monitor the atmospheric state.

**iasi (IASI)**
    Infrared Atmospheric Sounding Interferometer data, delivering hyperspectral infrared measurements for precise temperature and trace gas retrievals.

**mwhs2 (MWHS-2)**
    Microwave Humidity Sounder 2 observations, utilized primarily for tracking atmospheric water vapor globally.

**ro (GPS-RO)**
    GPS Radio Occultation measurements, providing highly accurate, calibration-free vertical profiles of atmospheric refractivity, temperature, and pressure.

**sc (SCATTEROMETER)**
    Scatterometer instrument data, specifically designed to measure wind speed and direction over the global oceans.

**ssmis (SSMIS)**
    Special Sensor Microwave Imager/Sounder data, offering combined microwave imaging and sounding capabilities for monitoring precipitation, sea ice, and atmospheric conditions.

**sw / sw_polaireDB (AMV / SATELLITE WINDS)**
    Atmospheric Motion Vectors derived from tracking clouds or water vapor features in consecutive satellite imagery (including Polar Direct Broadcast).

**to_amsua / to_amsub (ATOVS & MHS)**
    Advanced TIROS Operational Vertical Sounder data (AMSU-A and AMSU-B/MHS). A vital suite of microwave instruments for atmospheric temperature and humidity profiling, available in clear-sky, all-sky, and rapid RARS formats.

Quick Reference Table
---------------------

For quick CLI usage, here is the mapping of all valid ``--family`` arguments found in the directories:

.. list-table:: Exact CLI Arguments & Suffixes Reference
   :widths: 30 30 40
   :header-rows: 1
   :align: center

   * - Family CLI Argument
     - evalalt suffix
     - Instrument / Type
   * - ``ai``
     - ``ai_qc``
     - Aircraft (Conventional)
   * - ``atms`` / ``atms_allsky``
     - ``atms_qc`` / ``atms_allsky_qc``
     - ATMS Microwave Sounder
   * - ``cris``
     - ``crisfsr1_qc`` / ``crisfsr2_qc``
     - CrIS Infrared Sounder
   * - ``csr``
     - ``csr_qc``
     - Clear Sky Radiances
   * - ``gp``
     - ``gp_qc``
     - Ground-based GPS
   * - ``iasi``
     - ``iasi_qc``
     - IASI Hyperspectral
   * - ``mwhs2``
     - ``mwhs2_qc``
     - MWHS-2 Microwave
   * - ``ra``
     - *(Not in evalalt)*
     - Radar Doppler Velocity
   * - ``ro``
     - ``ro_qc``
     - GPS Radio Occultation
   * - ``sc``
     - ``sc_qc``
     - Scatterometer
   * - ``sf``
     - ``sf_qc``
     - Surface (Conventional)
   * - ``ssmis``
     - ``ssmis_qc``
     - SSMIS Microwave
   * - ``sw`` / ``sw_polaireDB``
     - *(Not in evalalt)*
     - Satellite Winds (AMV)
   * - ``to_amsua`` (incl. allsky/rars)
     - ``to_amsua_qc`` (+ variants)
     - AMSU-A Microwave
   * - ``to_amsub`` (incl. allsky/rars)
     - ``to_amsub_qc`` (+ variants)
     - AMSU-B/MHS Microwave
   * - ``ua``
     - *(Not in evalalt)*
     - Upper Air / Radiosondes


"""
