.. _quick_start_ref:

Pour commencer rapidement
=========================

Ici des exemples basic pour créer des :ref:`structures de données PyCTOH (Track, Grid et TimeSeries) <data_structure_ref>` :


.. _read_product_ref:

Lire un fichier GDR
-------------------

Pour créer un objet Track à partir d'un fichier trace GDR il faut utiliser la fonction **read_product**
qui appelle le constructor approprié au type de produit fourni par le CTOH.

.. py:function:: track_obj=read_product(filename, product_kind=None, memory_optimization=True, decode_times=True, no_maskedarray=True)

    :param filename: Nom du fichier GDR.

    :param product_kind:
        Type de produit. Les types de produit définis dans la bibliothèque PyCTOH. Ils sont disponibles via la fonction
        `**idproduct()**` (lien vers cette fonction). Egale à None par défaut, la fonction `product_factory` recherche
        automatiquement le type de produit en fonction du nom du fichier GDR.

    :param memory_optimization:
        Optimisation de la mémoire. Egale à True par défaut, cette option permet de choisir, à la lecture du
        fichier netCDF, le type (numpy.dtype) le mieux approprié aux variables ayant des attributs 'scale_factor' et/ou
        'add_offset'. Sinon ces variables sont toutes définies en type `numpy.dtype('float64')`.

    :param decode_times:
        Décodage de la variable time en un objet Datetime. Egale à True par défaut, cette option permet de convertir,
        à la lecture du fichier netCDF, la variable time de type 'float64' en un type 'datatime64[ms]'. Pour cela les
        attributs "units" et "calendar" de la variable time doit être défini suivant la `convention-CF`_.

    :param no_maskedarray:
        Pas d'objet numpy.ma.MaskedArray. Egale à True par défaut, cette option permet de convertir, à la lecture du
        fichier netCDF, les variables numpy.ma.MaskedArray de type 'float' en varaibles numpy.ndarray de type 'float'. 
        La valeur `numpy.nan` est affectée à toutes les valeurs masquées (masked). Toutes les variables qui ne sont pas de 
        type 'float' restent numpy.ma.MaskedArray.


.. _convention-CF: http://cfconventions.org/


Exemples d'utilisation
^^^^^^^^^^^^^^^^^^^^^^

Création d'un objet Track à partir d'un fichier GDR trace Jason-3 fourni par le CTOH. Dans ce cas le type de produit
est automatiquement reconnu par le nom du fichier telque défini par le CTOH.

.. code-block:: python

    >>> from pyctoh.track import read_product
    >>> filename = "test_data/JA3_GPS_2PfP031_009_20161211_051419_20161211_061031.nc"
    >>> track_obj = read_product(filename)


Dans le cas où le nom du fichier n'est pas conforme au type de produit CTOH, le type peut être "forcé" avec l'option
`product_kind`. La liste des types est fournie par la fonction get_producttype(). Ici, est choisi `jason_f` pour 
définir le fichier GDR comme produit de type jason GDR-F.

.. _get_producttype_ref:

.. code-block:: python

    >>> from pyctoh.track import get_producttype
    >>> get_producttype()
     ['topex_cash',
     'cryosat2_c',
     'cryosat2_d',
     'ers2_ctoh',
     'envisatv21_ctoh',
     'envisatv3_esa',
     'jason_d',
     'jason_e',
     'jason_f',
     'saral_t',
     'saral_f',
     'sentinel3_b003',
     'sentinel6_f']
    >>> filename = "test_data/JA3_GPS_2PfP031_009_20161211_051419_20161211_061031.nc"
    >>> track_obj = read_product(filename,product_kind='jason_f')

Plus de détailles sur :ref:`l'objet Track <trackref>`.


.. _query_product_ref:

Accès à la base de données
--------------------------

L'accès aux données de la base du CTOH se fait via la méthode **query_product** de la classe :ref:`Catalogue <catalogue_ref>`. 
Cette méthode envoie une requête à la base de données et retourne un objet Track.

.. py:function:: track_obj = Catalogue.query_product(product_name, track_num, cycle_num, memory_optimization=True, decode_times=True, no_maskedarray=True)

  :param product_name:
        Nom du produit défini dans la catalogue de la base de données. La liste des produits disponibles 
        est fournie avec la méthode **product_list()** de la classe :ref:`Catalogue <catalogue_ref>`.
  :param track_num:
        Numéro de la trace. La liste des numéros de traces disponibles est fournie avec la méthode 
        **product_cycle_track()** de la classe :ref:`Catalogue <catalogue_ref>`.
  :param cycle_num:
        Numéro du cycle. Idem que pour **track_num**.

  Les autres options sont les mêmes que pour la fonction `read_product <read_product_ref_>`__


Exemples d'utilisation
^^^^^^^^^^^^^^^^^^^^^^

Création d'un objet Track à partir d'une requête à la base de données CTOH. Ici le cas du produit 
Jason-3 GDR-F (ja3_a_cnes_f_sgdr) avec la trace numéro 200 et le cycle 150.

.. code-block:: python

    >>> # Import de la classe 'Catalogue'
    >>> from pyctoh.db.catalogue import Catalogue
    >>> # Selection du catalogue CTOH
    >>> cat = Catalogue(os.environ["ALT_CATALOGUE"])
    >>> # Requête trace 200 cycle 150 du produit 'ja3_a_cnes_f_sgdr' 
    >>> track_obj = cat.query_product('ja3_a_cnes_f_sgdr', 200, 150)