doc/fr/ref_observations_requirements.rst

   1 ..
   2    Copyright (C) 2008-2024 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. _section_ref_observations_requirements:
  25
  26 Conditions requises pour la description d'observations ou de mesures expérimentales
  27 -----------------------------------------------------------------------------------
  28
  29 .. index:: single: setObservation
  30 .. index:: single: setObservationError
  31
  32 L'ensemble des mesures du système physique que l'on considère sont appelées
  33 "*des observations*", ou même simplement "*une observation*". Comme cela a déjà
  34 été mentionné dans :ref:`section_theory`, cette observation est notée de
  35 manière la plus générique par :
  36
  37 .. math:: \mathbf{y}^o
  38
  39 Elle peut dépendre en général de l'espace et du temps, voire de variables
  40 paramétriques, et cela de manière plus ou moins complexe. On particularise
  41 usuellement la dépendance en temps en considérant que, à chaque instant, la
  42 quantité :math:`\mathbf{y}^o` est un vecteur de
  43 :math:`\mbox{I\hspace{-.15em}R}^d` (avec la dimension :math:`d` de l'espace
  44 pouvant éventuellement varier en temps). Autrement dit, **une observation est
  45 une série (temporelle) de mesures (variées)**. On parlera donc de manière
  46 équivalente d'une observation (vectorielle), d'une série ou d'un vecteur
  47 d'observations, et d'un ensemble d'observations. Dans sa plus grande
  48 généralité, l'aspect séquentiel de la série d'observations est relatif
  49 conjointement à l'espace, et/ou au temps, et/ou à une dépendance paramétrique.
  50
  51 On peut classer les manières de représenter l'observation en fonction des
  52 usages que l'on en a ensuite et des liens avec les méthodes algorithmiques. Le
  53 classement que l'on propose est le suivant, dont chaque catégorie est détaillée
  54 ensuite :
  55
  56 #. `Utilisation d'une unique observation spatiale`_
  57 #. `Utilisation d'une série temporelle d'observations spatiales`_
  58 #. `Utilisation d'une unique observation spatio-temporelle`_
  59 #. `Utilisation d'une série paramétrée d'observations spatiales`_
  60
  61 Les représentations numériques des observations utilisent toutes les
  62 possibilités décrites dans la :ref:`section_ref_entry_types`. On spécialise ici
  63 leurs usages pour indiquer différentes manières possible d'écrire cette
  64 information.
  65
  66 Utilisation d'une unique observation spatiale
  67 +++++++++++++++++++++++++++++++++++++++++++++
  68
  69 .. index:: single: Vector
  70 .. index:: single: DataFile
  71
  72 Cela fait référence à l'usage d'une série vectorielle dépendante uniquement de
  73 l'espace. Cette observation est de plus utilisée en une seule fois,
  74 c'est-à-dire en étant entièrement connue au début de l'analyse algorithmique.
  75 Cela peut par exemple être un champ spatial de mesures, ou de plusieurs champs
  76 physiquement homogènes ou pas.
  77
  78 - La représentation mathématique est :math:`\mathbf{y}^o\,\in\,\mbox{I\hspace{-.15em}R}^d`.
  79
  80 - La représentation numérique canonique est **un vecteur**.
  81
  82 - La représentation numérique dans ADAO se fait avec le mot-clé "*Vector*". La
  83   totalité de l'information, déclarée dans l'une des représentations suivantes,
  84   est transformée en un unique vecteur (remarque : listes et tuples sont
  85   équivalents) :
  86
  87     - variable "*numpy.array*" : ``numpy.array([1, 2, 3])``
  88     - variable "*liste*"       : ``[1, 2, 3]``
  89     - chaîne de caractères     : ``'1 2 3'``
  90     - chaîne de caractères     : ``'1,2,3'``
  91     - chaîne de caractères     : ``'1;2;3'``
  92     - chaîne de caractères     : ``'[1,2,3]'``
  93     - fichier Python de données, avec variable "*Observation*" dans l'espace de nommage, indiqué par le mot-clé "*Script*" avec la condition ``Vector=True``
  94     - fichier texte de données (TXT, CSV, TSV, DAT), avec pointeur de variable par nom en colonne ou en ligne, indiqué par le mot-clé "*DataFile*" avec la condition ``Vector=True``
  95     - fichier binaire de données (NPY, NPZ), avec pointeur de variable par nom, indiqué par le mot-clé "*DataFile*" avec la condition ``Vector=True``
  96
  97 Exemples de déclaration en interface TUI :
  98 ::
  99
 100     case.setObservation( Vector = [1, 2, 3] )
 101     case.setObservation( Vector = numpy.array([1, 2, 3]) )
 102     case.setObservation( Vector = '1 2 3' )
 103     case.setObservation( Vector=True, Script = 'script.py' )
 104     case.setObservation( Vector=True, DataFile = 'data.csv' )
 105     case.setObservation( Vector=True, DataFile = 'data.npy' )
 106
 107 Remarque d'utilisation : dans une étude donnée, seul le dernier enregistrement
 108 (que ce soit un vecteur unique ou une série de vecteurs) est utilisable, car un
 109 seul concept d'observation existe par étude ADAO.
 110
 111 Utilisation d'une série temporelle d'observations spatiales
 112 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 113
 114 .. index:: single: VectorSerie
 115 .. index:: single: DataFile
 116
 117 Cela fait référence une série ordonnée vectorielle d'observations, dépendantes
 118 de l'espace et du temps. A un instant donné, on suppose que l'on ne connaît que
 119 les observations des instants courant et précédents. Les observations
 120 successives en temps sont indexées par :math:`n`, leur instant d'existence ou
 121 de référence. Cela peut par exemple être un champs spatial de mesures,
 122 physiquement homogènes ou pas, dont on considère un historique.
 123
 124 - La représentation mathématique est :math:`\forall\,n\in\{0...N\},\,\mathbf{y}^o_n\,\in\mbox{I\hspace{-.15em}R}^d`.
 125
 126 - La représentation numérique canonique est **une série ordonnée de vecteurs**.
 127
 128 - La représentation numérique dans ADAO se fait avec le mot-clé
 129   "*VectorSerie*". L'indexation courante de l'information est utilisée pour
 130   représenter l'index temporel lors de la déclaration dans l'une des
 131   représentations suivantes, et l'information est transformée en une série
 132   ordonnée de vecteurs (remarque : listes et tuples sont équivalents) :
 133
 134     - "*liste*" de "*numpy.array*"      : ``[numpy.array([1,2,3]), numpy.array([1,2,3])]``
 135     - "*numpy.array*" de "*liste*"      : ``numpy.array([[1,2,3], [1,2,3]])``
 136     - "*liste*" de "*liste*"            : ``[[1,2,3], [1,2,3]]``
 137     - "*liste*" de chaîne de caractères : ``['1 2 3', '1 2 3']``
 138     - "*liste*" de chaîne de caractères : ``['1;2;3', '1;2;3']``
 139     - "*liste*" de chaîne de caractères : ``['[1,2,3]', '[1,2,3]']``
 140     - chaîne de "*liste*"               : ``'[[1,2,3], [1,2,3]]'``
 141     - chaîne de "*liste*"               : ``'1 2 3 ; 1 2 3'``
 142     - fichier Python de données, avec variable "*Observation*" dans l'espace de nommage, indiqué par le mot-clé "*Script*" avec la condition ``VectorSerie=True``
 143     - fichier texte de données (TXT, CSV, TSV, DAT), avec pointeur de variable par nom en colonne ou en ligne, indiqué par le mot-clé "*DataFile*" avec la condition ``VectorSerie=True``
 144     - fichier binaire de données (NPY, NPZ), avec pointeur de variable par nom, indiqué par le mot-clé "*DataFile*" avec la condition ``VectorSerie=True``
 145
 146 Exemples de déclaration en interface TUI :
 147 ::
 148
 149     case.setObservation( VectorSerie = [[1,2,3], [1,2,3]] )
 150     case.setObservation( VectorSerie = [numpy.array([1,2,3]), numpy.array([1,2,3])] )
 151     case.setObservation( VectorSerie =  ['1 2 3', '1 2 3'] )
 152     case.setObservation( VectorSerie =  '[[1,2,3], [1,2,3]]' )
 153     case.setObservation( VectorSerie =  '1 2 3 ; 1 2 3' )
 154     case.setObservation( VectorSerie=True, Script = 'script.py' )
 155     case.setObservation( VectorSerie=True, DataFile = 'data.csv' )
 156     case.setObservation( VectorSerie=True, DataFile = 'data.npy' )
 157
 158 Remarque d'utilisation : dans une étude donnée, seul le dernier enregistrement
 159 (que ce soit un vecteur unique ou une série de vecteurs) est utilisable, car un
 160 seul concept d'observation existe par étude ADAO.
 161
 162 Utilisation d'une unique observation spatio-temporelle
 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 164
 165 Cette unique observation spatio-temporelle est similaire à la précédente dans
 166 sa représentation de série vectorielle, mais elle impose qu'elle doit être
 167 utilisée en une seule fois, c'est-à-dire en étant entièrement connue au début
 168 de l'analyse algorithmique. Elle est donc représentable comme une série
 169 indexée, de la même manière que pour une `Utilisation d'une série temporelle
 170 d'observations spatiales`_.
 171
 172 Utilisation d'une série paramétrée d'observations spatiales
 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 174
 175 On représente cette fois une collection d'observations paramétrées par un
 176 indice ou un paramètre discret. Cette forme est encore similaire à la
 177 précédente. Elle est donc représentable comme une série indexée, de la même
 178 manière que pour une `Utilisation d'une série temporelle d'observations
 179 spatiales`_.
 180
 181 Remarques générales sur les observations
 182 ++++++++++++++++++++++++++++++++++++++++
 183
 184 .. warning::
 185
 186   Lorsque l'assimilation établit explicitement un **processus itératif
 187   temporel**, comme dans l'assimilation de données d'états, **la première
 188   observation est non utilisée mais elle doit être présente dans la description
 189   des données d'un cas ADAO**. Par convention, elle est donc considérée comme
 190   disponible au même instant que la valeur temporelle d'ébauche, et ne conduit
 191   pas à une correction à cet instant là. La numérotation des observations
 192   commençant à 0 par convention, ce n'est donc qu'à partir du numéro 1 que les
 193   valeurs d'observations sont utilisées dans les algorithmes itératifs
 194   temporels.
 195
 196 Les observations peuvent être fournies par pas de temps uniques ou par fenêtres
 197 successives pour les algorithmes itératifs. Dans ce cas, on doit fournir à
 198 chaque itération algorithmique relative à une fenêtre temporelle une série
 199 d'observations. Dans la pratique, pour chaque fenêtre, on fournit une série
 200 comme lors d'une `Utilisation d'une série temporelle d'observations
 201 spatiales`_.
 202
 203 Les options d'acquisition d'observations sont plus riches en interface
 204 textuelle TUI, toutes les options n'étant pas obligatoirement disponibles dans
 205 l'interface graphique GUI.
 206
 207 Pour l'entrée de données par fichiers, on se reportera à la description des
 208 possibilités autour du mot-clé "*DataFile*" dans les
 209 :ref:`section_ref_entry_types_info`.