.. _timeseries_ref:


TimeSeries
==========

Ce cookbook montre des exemples concrets d'utilisation de l'objet `TimeSeries` de la bibliothèque PyCTOH.

Création d'un objet TimeSeries
-------------------------------

Pour créer un objet `TimeSeries`, suivez ces étapes :

.. code-block:: python

    # Importer les modules nécessaires
    from pyctoh.db.catalogue import Catalogue
    from pyctoh.track.timeseries import TimeSeries

    # Charger le catalogue de produits CTOH
    # Remplacez le chemin par celui de votre catalogue
    cat = Catalogue(filepath="/ctoh/data/db/catalogue_yml/ctoh_products_base.yml")

    # Sélectionner une trace spécifique
    # Ici, on choisit la trace numéro 9
    track_num = 9
    track_obj = cat.query('ja3_a_cnes_f_sgdr', tracks=[track_num])

    # Créer un objet TimeSeries à partir de la trace sélectionnée
    ts = TimeSeries(track_obj, track_num)

Visualisation
-------------

Vous pouvez visualiser les données de la série temporelle de différentes façons :

.. code-block:: python

    # Visualiser les données en fonction du temps
    # 'data_20/ku/sig0_ocog' est le chemin de la variable à visualiser
    # 'time' est utilisé comme axe des abscisses
    # Le résultat est sauvegardé dans un fichier nommé 'sig0.png'
    ts.plot('data_20/ku/sig0_ocog', abs_x='time', filename='sig0.png')

    # Visualiser les données sur une carte géographique
    # Le résultat est sauvegardé dans un fichier nommé 'sig0_map.png'
    ts.map_plot('data_20/ku/sig0_ocog', filename='sig0_map.png')

Création de la trace normalisée d'un produit
---------------------------------------------

Voici un exemple complet pour le produit `ja3_a_cnes_f_sgdr` :

.. code-block:: python

    # Importer les modules nécessaires
    from pathlib import Path
    from pyctoh.db.catalogue import Catalogue
    from pyctoh.track.timeseries import TimeSeries

    # Nom du produit à traiter
    prod_name = "ja3_a_cnes_f_sgdr"

    # Charger le catalogue de la base de données
    # Remplacez les chemins par ceux de votre base de données
    catalogue_filepath = "/ctoh/data/projects/normpass_test_XTrack/ctoh_products_base.yml"
    metadata_dir = "/ctoh/data/projects/normpass_test_XTrack/metadb"
    cat = Catalogue(catalogue_filepath, metadata_dir=metadata_dir)

    # Répertoire où les traces normalisées seront sauvegardées
    db_dir = Path("/ctoh/data/projects/normpass_test_XTrack")

    # Parcourir chaque trace du produit
    for t in range(1, 255):
        print(f"Traitement de la trace : {t}")

        # Sélectionner la trace actuelle
        tracks = [t]

        # Charger le produit en mémoire
        # `decode_times=False` permet d'optimiser le temps de chargement
        tr = cat.query_product(
            prod_name, tracks=tracks, decode_times=False
        )

        # Créer un objet TimeSeries pour la trace actuelle
        ts = TimeSeries(tr, tracks[0])
        ts.prod_name = prod_name
        
        # Trace de référence 
        reftrack_filepath=db_dir.joinpath("ja3_a_cnes_f_sgdr","reftrack",f"JA3_A_RefTrack_{t:04d}.nc")
        # Chargement de l'index précalculé en base de données
        ts.load_norm_index(reftrack_filepath=reftrack_filepath)

        # Calculer la structure de trace normalisée
        ts.to_normpass([])

        # export de la trace normalisée
        ts.export_normpass(output_dir=output_dir.joinpath("normpass"))

Calcul d'une trace de référence d'un produit
--------------------------------------------

Exemple pour le produit `ja3_a_cnes_f_sgdr` :

.. code-block:: python

    # Importer les modules nécessaires
    from pathlib import Path
    from pyctoh.db.catalogue import Catalogue
    from pyctoh.track.timeseries import TimeSeries

    # Nom du produit à traiter
    prod_name = "ja3_a_cnes_f_sgdr"

    # Charger le catalogue de la base de données
    # Remplacez les chemins par ceux de votre base de données
    catalogue_filepath = "/ctoh/data/projects/normpass_test_XTrack/ctoh_products_base.yml"
    metadata_dir = "/ctoh/data/projects/normpass_test_XTrack/metadb"
    cat = Catalogue(catalogue_filepath, metadata_dir=metadata_dir)

    # Répertoire où les traces normalisées seront sauvegardées
    db_dir = Path("/ctoh/data/projects/normpass_test_XTrack")

    # Parcourir chaque trace du produit
    for t in range(1, 255):
        print(f"Traitement de la trace : {t}")

        # Sélectionner la trace actuelle
        tracks = [t]

        # Charger le produit en mémoire
        # `decode_times=False` permet d'optimiser le temps de chargement
        tr = cat.query_product(
            prod_name, tracks=tracks, decode_times=False
        )

        # Créer un objet TimeSeries pour la trace actuelle
        ts = TimeSeries(tr, tracks[0])
        ts.prod_name = prod_name
        
        # Calculer l'index normalisé
        # Les paramètres doivent être configurés en fonction du produit
        # - ref_freq : fréquence de référence
        # - delta_lat_eq : seuil de latitude à l'équateur
        # - delta_lon_apex : seuil de longitude pour les apex
        # - index_length : longueur du segment de trace pour l'interpolation
        # - apex_idx_offset : décalage de l'index pour les apex
        # - dist_max : distance maximale entre le point de référence et la trace
        ts.calc_norm_index(ref_freq=20., delta_lat_eq=5., delta_lon_apex=5., index_length=50, apex_idx_offset=300, dist_max=110)

        # Calculer la structure de trace normalisée
        ts.to_normpass([])

        # Calculer la trace de référence
        ts.calc_reftrack()

        # Exporter la trace de référence
        # Remplacez le chemin par celui de votre répertoire de sortie
        ts.export_reftrack(output_dir=db_dir.joinpath("reftrack"))