.. _ctoh_database_ref: ==================== Base de données CTOH ==================== .. _db_structure_ref: Structure arborescente de données ################################# Le terme "base de données CTOH" est utilisé au sens large qui correspond en réalité à une **structure arboréssente de fichiers (SAF)** où les fichiers sont répartie de manière hiérarchique par produit, cycle, sous-produit et trace. .. , et ne .. fait *pas* référence à une base de données relationnelle (type *Postgres*) .. ni objet. Elle correspond .. Aujourd’hui (2020/07/02), la base de données CTOH est simplement une collection de fichiers répartis sur un ensemble hétérogène de disques, .. et unifiée via des liens symboliques. .. figure:: bd_organisation_#01.png :align: center Vue simplifiée de l'organisation de produits en cycles, gdrtypes et fichiers. Principes de la SAF ******************* La SAF a été construite selon les principes suivants : - le point d’entrée à la SAF est un fichier catalogue qui se trouve à un endroit référencé par la **variable d’environnement $GDR** (/ctoh/data/db) - le :ref:`catalogue ` décrit un ensemble de produits disponibles ; - chaque :ref:`utilisateur peut définir un ou plusieurs catalogues propres à lui ` combinant des données de la SAF à la gestion de ces propres produits de recherche, en beta-test. Quand ils sont prêts, ils intègrent le catalogue général ; - un produit est, virtuellement, un fichier netCDF et il est définit par le nom du produit, son cycle et son numéro de trace. - chaque produit à un chemin de données associé, des gdrtypes, et des conventions de nommage. - en réalité, le fichier-produit (virtuel) n’existe pas en tant que tel ; il est éclaté en plusieurs gdrtypes, chacun étant bien un fichier netCDF. Un fichier-produit est donc l’union potentielle de tous les fichiers gdrtypes. Pour pouvoir faire cette union de fichiers netCDF, les variables de dimensions doivent être identiques pour tous les gdrtypes . - chaque fichier netcdf gdrtype est donc un fichier netCDF complet et il doit pouvoir être visualisé, traité ou mise à jour de façon indépendante des autres. - les droits d’accès aux fichiers sont ceux des fichiers unix. En pratique, pour accéder aux produits qui sont stockés sur /ctoh/data/db il faut appartenir au groupe unix ctoh, et idem pour usrcto. Le groupe ctoh est un sous-ensemble de usrcto. .. _catalogue_doc_ref: Catalogues de données ********************* Il y a plusieurs *catalogues* décrivant la SAF: - Générale : Disponible à tous. Il est par défaut définit avec la variable d'environnement ALT_CATALOGUE .. code-block:: bash > echo $ALT_CATALOGUE > ALT_CATALOGUE=/ctoh/data/db/catalogue_yml/ctoh_products_base.yml - Personnalisée : :ref:`Créer par l'utilisateur ` sur la base du catalogue générale contenant des produits en phase beta ou enrichi de sous produits pour des besoins spécifiques. Dans ce cas la variable d'environnement ALT_CATALOGUE doit défini par l'utilisateur .. code-block:: bash > export ALT_CATALOGUE=/user/path/catalogue/custom_products_base.yml > echo $ALT_CATALOGUE > ALT_CATALOGUE=/user/path/catalogue/custom_products_base.yml .. Il y a .. Remise d’équerre des catalogues. Aujourd’hui l’implémentation du parser des fichiers de description et trop complexe car la grammaire des fichiers desc n’existe pas (à ma connaissance) et il y a beaucoup d’exceptions à prendre en compte (le cas de chemins terminant par ‘/’ ou pas, quand il y a un gdrpath défini ou pas…). Pour ne pas modifier les fichiers existants et risquer de tout casser, on a définit une grammaire standard simple, implémenté sous forme de fichiers YAML. .. Aussi, plutôt que permettre d’avoir des catalogues n’importe où dans l’arborescence qui se font référence les uns aux autres avec des liens symboliques, on demande à ce qu’ils soient tous ensemble dans un seul et même répertoire, ça favorise la lisibilité. .. On limite le nombre de catalogues à 2 : un catalogue général pour tout le monde et un autre pour le ctoh, qui contient tous les produits en phase beta. Chaque utilisateur (ou groupe) peut en plus avoir son propre catalogue, pour les produits en plein développement (phase alpha). Services ******** .. Les services à proposer à partir de la base sont : .. - extraction : le service essentiel. .. - plot : une visualisation rapide du contenu d’un sous-enesemble de la base .. la base doit être stable et robuste. Droits d’accès à la base ************************ .. Aujourd’hui les droits d’accès sont calqués sur la distinction de propriété unix. Cette distinction est fictive et en réalité, tous les utilisateurs Legos devraient pouvoir avoir accès en lecture aux produits qu’on veut leur proposer. La distinction usrcto/ctoh pour les données est donc fictive et doit pouvoir disparaître. .. On est en train d’écrire une commande d’extraction qui ne accède pas directement aux fichiers, mais via un daemon d’extraction qui, lui, a les droits d’accès usrcto et ctoh. Ainsi, tous les produits ctoh sont disponibles à tous les utilisateurs sans avoir besoin de dupliquer les fichiers. Seule contrainte : ça marche via des extractions. L’accès direct à l’arborescence n’est pas possible pour un utilisateur lambda – il faut être ctoh. .. _tree_strust_access_ref: Les produits de la SAF ###################### Le contenu des produits de la SAF CTOH se trouve dans : .. code-block:: text /ctoh/data/db/products La liste des répertoires de produits disponibles en base est la suivante: .. code-block:: text cs2_b_gop_c_gdr/ ja1_a_cnes_e_gdr/ s3a_a_lan_%_sgdr/ cs2_b_ice_d_gdr/ ja1_b_cnes_e_gdr/ s3a_a_wat_%_sgdr/ env_a_ctoh_v0210_gdr/ ja1_c_cnes_e_gdr/ s3b_a_lan_%_sgdr/ env_a_esa_v0300_sgdr/ ja2_a_cnes_d_gdr/ s3b_a_wat_%_sgdr/ env_b_ctoh_v0210_gdr/ ja2_b_cnes_d_gdr/ s3b_b_lan_%_sgdr/ env_b_esa_v0300_sgdr/ ja3_a_cnes_%_sgdr/ s3b_b_wat_%_sgdr/ ers2_a_ctoh_v0100_gdr/ ja3_a_cnes_f_sgdr/ srl_a_cnes_%_sgdr/ ers2_a_reaper_v0108_gdr/ ja3_a_cnes_%_sigdr/ srl_b_cnes_%_sgdr/ ers2_a_reaper_v0108_sgdr/ srl_b_cnes_%_sigdr/ tpx_a_cash_v0100_gdr/ .. _product_name_ref: Convention de nommage des produits ********************************** Chaque produit est identifié par un nom unique comportant 5 champs: 'mission_phase_fournisseur_version_type' détaillés ici: :mission: Le nom de la mission (en abrégé: ja1 pour jason-1, etc) :phase: phase d'orbite de la mission (on commence par a, puis b si elle change, etc) :fournisseur: Nom de l'organisme ayant traité/fournis les données (cnes,esa,ctoh), cela peut être aussi le nom d'un projet (cash, reaper). :version: version du produit si homogène ("e" pour GDR-E ou "v0210" pour version 2.1) sinon le caractère % est utilisé (mélange de version). :type: le type de produit d'origine (gdr, sgdr, sigdr). Cette convention de nommage est définie une expression regex dans le :ref:`fichier catalogue ` sous le paramètre ``prod_name_pattern``. .. admonition:: Par exemple, le produit *ja3_a_cnes_%_sgdr*. **ja3_a_cnes_%_sgdr** : Il décrit le produit de la mission Jason-3 en phase A (orbite nominale) fourni par le CNES. Le symbole *%* indique que la version du produit n'est pas homogène (mélange GDR-D et GDR-f) et pour finir le type du produit : *sgdr*. .. _db_jason3_example_ref: .. admonition:: SAF du produit *ja3_a_cnes_%_sgdr* L'exemple ci dessous, montre la structure du produit *ja3_a_cnes_%_sgdr* dans la base de données du CTOH. Le premier niveau de l'arborescence est le nom du produit, dans le deuxième niveau sont les cycles d'orbite et le troisième niveau sont les paramètres de type (définis par gdrtypes). Le type principale est fournis par les agences spatiales : ceux sont les paramètres d'origines (gdr ou sgdr). Sans ces paramètres origines, le produit ne peut exister. Les autres types de paramètres (gdrtypes) tels que *ctoh2* et *normpass*, sont des paramètres complémentaires ajoutés par le CTOH dans sa base de données. Dans ces répertoires gdrtypes se trouvent les fichiers NetCDF de *paramètres type*. .. code-block:: text ja3_a_cnes_%_sgdr # Nom du produit dans la base de données CTOH ├── cycle_000 # Numéro du cycle │ ├── sgdr # Produit sgdr original │ │ ├── JA3_GPS_2PTP000_118_20160212_020721_20160212_030333.nc │ │ ├── JA3_GPS_2PTP000_120_20160212_035946_20160212_045559.nc │ │ ├── JA3_GPS_2PTP000_122_20160212_055212_20160212_064825.nc │ │ └── ... │ │ │ ├── ctoh2 # Paramètres CTOH complémentaires ajoutés au produit sgdr original │ │ ├── ctoh2_JA3_GPS_2PTP000_118_20160212_020721_20160212_030333.nc │ │ ├── ctoh2_JA3_GPS_2PTP000_120_20160212_035946_20160212_045559.nc │ │ ├── ctoh2_JA3_GPS_2PTP000_127_20160212_103316_20160212_112929.nc │ │ └── ... │ │ │ │ │ ├── normpass # Paramètres CTOH complémentaires ajoutés au produit sgdr original │ │ ├── normpass_JA3_GPS_2PTP000_118_20160212_020721_20160212_030333.nc │ │ ├── normpass_JA3_GPS_2PTP000_120_20160212_035946_20160212_045559.nc │ │ ├── normpass_JA3_GPS_2PTP000_122_20160212_055212_20160212_064825.nc │ │ └── ... │ ├── cycle_001 │ ├── ctoh2 │ ├── gdr │ ├── gpd │ └── normpass ├── cycle_002 │ ├── ctoh2 │ ├── gdr │ ├── gpd │ └── normpass ├── ... . . Les sous-produits (gdrtype) *************************** Le contenu du produit est organisé par cycle et par sous produit (aussi appelé gdrtype). Il existe plusieurs types de sous produit. Le principal est de type gdr, sgdr ou sigdr. Il est fourni par les agences spatiales et contient les paramètres originaux de la mesure altimètrique. Les autres types complètent ce produit type de base pour fournir des paramètres et des corrections complémentaires afin d'avoir des produits les plus homogènes et à jour possible. Voici les types de sous produit que l'on peut trouver: :CTOH1: corrections complémentaires atmosphériques et de marée calculés à 1 Hz, :CTOH2: paramètres complémentaires interpolés provenant de données grillées (distance à la cote, géoïde, mdt,mss, etc). :GPD: correction complémentaire de troposphère humide et sèche fournie par J Fernandez de l’université de Porto. :Normpass: paramètres d'indexation calculés le long de la trace, permettant la création de la structure de trace normalisée pour l'analyse colinéaire de données altimétrique :Meanpass: traces moyennes du produit calculées avec les traces normalisées .. warning:: Les fichiers de données sont au format NetCDF. **Mais ils ne sont pas tous de la même version : netCDF3, netCDF4 classic model ou netCDF4/HDF-5.** Fichiers de configuration de la SAF ################################### La base de données utilise deux types fichiers de configuration. Le premier décrit la SAF de la base de données : le fichier catalogue. Le deuxième décrit les produits : les fichiers de description de produit. .. _catalogue_ref: Le catalogue ************ Le fichier **catalogue** liste les produits disponibles en base de données. Ci-dessous le **catalogue** de la base de données du CTOH (/ctoh/data/db/catalogue/ctoh_products_base.yml) .. code-block:: yaml # Description of the CTOH DATA BASE prod_name_pattern : (?P[a-z,0-9]*)_(?P[a-z]{1})_(?P[a-z]*)_(?P[a-z,0-9]*|%)_(?P[a-z]*) # Regex pattern of product name default_path: /ctoh/data/db/products # common absolute path products: ja3_a_cnes_f_sgdr : /ctoh/data/db/catalogue_yml/current/ja3_a_cnes_f_sgdr.yml ja3_a_cnes_%_sgdr : /ctoh/data/db/catalogue_yml/current/ja3_a_cnes_%_sgdr.yml ja2_a_cnes_d_sgdr : /ctoh/data/db/catalogue_yml/current/ja2_a_cnes_d_sgdr.yml ja2_b_cnes_d_sgdr : /ctoh/data/db/catalogue_yml/current/ja2_b_cnes_d_sgdr.yml ja2_c_cnes_d_sgdr : /ctoh/data/db/catalogue_yml/current/ja2_c_cnes_d_sgdr.yml ja2_d_cnes_d_sgdr : /ctoh/data/db/catalogue_yml/current/ja2_d_cnes_d_sgdr.yml ja1_a_cnes_e_gdr : /ctoh/data/db/catalogue_yml/current/ja1_a_cnes_e_gdr.yml ja1_b_cnes_e_gdr : /ctoh/data/db/catalogue_yml/current/ja1_b_cnes_e_gdr.yml ja1_c_cnes_e_gdr : /ctoh/data/db/catalogue_yml/current/ja1_c_cnes_e_gdr.yml srl_a_cnes_f_sgdr : /ctoh/data/db/catalogue_yml/current/srl_a_cnes_f_sgdr.yml srl_b_cnes_f_sgdr : /ctoh/data/db/catalogue_yml/current/srl_b_cnes_f_sgdr.yml ers2_a_ctoh_v0100_gdr : /ctoh/data/db/catalogue_yml/current/ers2_a_ctoh_v0100_gdr.yml ers2_a_reaper_v0108_gdr : /ctoh/data/db/catalogue_yml/current/ers2_a_reaper_v0108_gdr.yml ers2_a_reaper_v0108_sgdr : /ctoh/data/db/catalogue_yml/current/ers2_a_reaper_v0108_sgdr.yml env_a_ctoh_v0210_gdr : /ctoh/data/db/catalogue_yml/current/env_a_ctoh_v0210_gdr.yml env_b_ctoh_v0210_gdr : /ctoh/data/db/catalogue_yml/current/env_b_ctoh_v0210_gdr.yml env_a_esa_v0300_sgdr : /ctoh/data/db/catalogue_yml/current/env_a_esa_v0300_sgdr.yml env_b_esa_v0300_sgdr : /ctoh/data/db/catalogue_yml/current/env_b_esa_v0300_sgdr.yml s3a_a_lan_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3a_a_lan_%_sgdr.yml s3b_a_lan_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3b_a_lan_%_sgdr.yml s3b_b_lan_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3b_b_lan_%_sgdr.yml s3a_a_wat_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3a_a_wat_%_sgdr.yml s3b_a_wat_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3b_a_wat_%_sgdr.yml s3b_b_wat_%_sgdr : /ctoh/data/db/catalogue_yml/current/s3b_b_wat_%_sgdr.yml cs2_b_ice_d_gdr : /ctoh/data/db/catalogue_yml/current/cs2_b_ice_d_gdr.yml cs2_b_gop_c_gdr : /ctoh/data/db/catalogue_yml/current/cs2_b_gop_c_gdr.yml Les champs du fichier catalogue sont définis par : :prod_name_pattern: Expression Regex du nom produit. Ce format nom produit est décrit :ref:`ici `. :default_path: Chemin absolu du répertoire contenant les produits. :products: Liste des produits. Cette liste comprend \: - une valeur clé : nom de produit définit :ref:`ici `. - et un attibut : fichier de description .. _product_file_yaml: Fichier de description ********************** Le fichier de description du produits détaille le contenu du produit. Ci-dessous un exemple du produit ja2_a_cnes_d_sgdr: .. code-block:: yaml name : ja2_a_cnes_d_sgdr mission : Jason-2 orbit_phase : A provider : CNES product_version : GDR-D, SGDR doc : product_prefix : ja2_a_cnes_d_sgdr/ cycle_prefix : cycle_\d{3}/ gdrtype_prefix : sgdr : sgdr/JA2_GPS_ normpass: normpass/normpass_JA2_GPS_ file_postfix : (?PJA2)_GPS_2P(?P[A-Z,a-z])P(?P\d{3})_(?P\d{3})_\d{4}[01]\d[0-3]\d_[0-2]\d[0-5]\d[0-5]\d_\d{4}[01]\d[0-3]\d_[0-2]\d[0-5]\d[0-5]\d\.nc ref_gdr : sgdr meanpass_dir : dims_alias: # ^(?Plf|hf)_dim(?P.*) --> exemples: lf_dim, hf_dim_ku, hf_dim_c, hf_dim_sar_ku, hf_dim_lrm_ku, etc. lf_dim : time wf_dims_alias: meas_ind: meas_ind wf_sample: wvf_ind coords_alias : time: lon: lon lat: lat time: time coords_alias_2d : # Product having coordinates parameters in 2d (time versus meas_ind) time_hf : lon : lon_20hz lat : lat_20hz time : time_20hz aliases: etc/ctoh_aliases_jason2d.desc # Gridded tracks (for regional access optimization) tracksgrid: etc/tracksgrid/ orbit: topex ellipsoid: 'name': 'TP' 'a': 6378136.30 'f': 1/298.257 Ci-dessous le détail des différents champs: - L'identité du produit :name: Nom du produit conformément à la nomenclature décrite :ref:`ici ` :mission: Nom de la mission :orbit_phase: Phase d'orbite. La premère est désigné par A, puis le suivante par B, ... Ainsi de suite. :provider: L'organisme qui a créé le produit (ex : ctoh, cnes, esa, etc). Cela peut aussi être une désignation (ex: lan, wat, GOP, ice, etc) :product_version: Un paramétre qui défini la version du produit. :doc: Element de documentation - Accès au données. Ces champs décrivent :ref:`la structure arboresente du produit dans la base `. :product_prefix: Le nom du répertoire du produit. Il est normalement identique au nom du produit. :cycle_prefix: Le nom du répertoire du cycle. Par défaut, il doit être \: `cycle_\d{3}` :gdrtype_prefix: La liste de gdrtype. Cette liste contient en premier lieu le produit altimètrique GDR (ou SGDR) de base. La clé doit être définit par *gdr* ou par *sgdr* et l'attribut correspond au nom du répertoire et du préfixe du fichier \: .. code-block:: text sgdr : sgdr/JA2_GPS_ Puis viennent les paramètres/corrections complémentaires. .. code-block:: text normpass: normpass/normpass_JA2_GPS_ :file_postfix: Suffixe fichier format regex avec description. Les champs disponibles si ils existent sont \: - start_date : date de début d'acquisition - end_date : date de fin d'acquisition - proc_date : date de traitement - duration : durée de l'acquisition - relative_orbit : orbite relative - cycle : numéro de cycle - pass : numéro de trace - product_generating_center : organisme de traitement - platform : classe operationnel/validation/reprocessing - processing_workflow : type de traitement (gdr, igdr, ntc, stc) - baseline_collection : version de produit - mode : mode instrumental LRM/SAR/SARin (sar, lrm, hf, lf, etc) Exemple : .. code-block:: bash file_pattern : (?PJA2)_GPS_2P(?P[A-Z,a-z])P(?P\d{3})_(?P\d{3})_\d{4}[01]\d[0-3]\d_[0-2]\d[0-5]\d[0-5]\d_\d{4}[01]\d[0-3]\d_[0-2]\d[0-5]\d[0-5]\d\.nc :ref_gdr: spécifie le nom gdrtype du produit altimétrique de base (reférence) :meanpass_dir: chemin complet du répertoire de meanpass :dbfs_file: fichier dbfs. Il est généré avec la commande ``alt_dbfs `` :metadata_file: fichier de métadonnées. Il est généré avec la commande ``alt_metadata `` - Structuration des données :dims_alias: liste les dimensions du produit. Chaque dimension est défini par une clé et une valeur. Le nom de la clé doit suivre une convention de nomage `^(?Plf|hf)_dim(?P.*)` --> exemples: lf_dim, hf_dim_ku, hf_dim_c, hf_dim_sar_ku, hf_dim_lrm_ku, etc. La value est le nom du paramètre de dimension du fichier GDR. .. code-block:: text lf_dim : time :wf_dims_alias: liste les dimensions de forme d'onde. .. code-block:: text meas_ind: meas_ind wf_sample: wvf_ind :coords_alias: liste les coordonnées associées au dimension défini dans dims_alias .. code-block:: text time: lon: lon lat: lat time: time :coords_alias_2d: Pour les produits ayant des paramètres haute fréquence en 2 dimension (time versus meas_ind). .. code-block:: text time_hf : lon : lon_20hz lat : lat_20hz time : time_20hz