From: Jean-Philippe ARGAUD Date: Wed, 2 Dec 2020 20:11:37 +0000 (+0100) Subject: Documentation example improvement with figures X-Git-Tag: V9_7_0b1~65 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=dd94d7c1ba3dcd186cf8e8de6912efca4de00905;p=modules%2Fadao.git Documentation example improvement with figures --- diff --git a/doc/en/ref_algorithm_KalmanFilter.rst b/doc/en/ref_algorithm_KalmanFilter.rst index 83050e1..24de1ca 100644 --- a/doc/en/ref_algorithm_KalmanFilter.rst +++ b/doc/en/ref_algorithm_KalmanFilter.rst @@ -184,6 +184,18 @@ StoreSupplementaryCalculations .. literalinclude:: scripts/simple_KalmanFilter1.res +.. include:: snippets/Header2Algo11.rst + +.. _simple_KalmanFilter1_state: +.. image:: scripts/simple_KalmanFilter1_state.png + :align: center + :width: 90% + +.. _simple_KalmanFilter1_variance: +.. image:: scripts/simple_KalmanFilter1_variance.png + :align: center + :width: 90% + .. ------------------------------------ .. .. include:: snippets/Header2Algo06.rst diff --git a/doc/en/scripts/simple_KalmanFilter1.py b/doc/en/scripts/simple_KalmanFilter1.py index fa5322a..1a2cb5a 100644 --- a/doc/en/scripts/simple_KalmanFilter1.py +++ b/doc/en/scripts/simple_KalmanFilter1.py @@ -45,3 +45,31 @@ Pa = case.get("APosterioriCovariance") print("") print(" Final a posteriori variance:",Pa[-1]) print("") +# +#------------------------------------------------------------------------------- +# +Observations = array([yo[0] for yo in Yobs]) +Estimates = array([xa[0] for xa in case.get("Analysis")]) +Variances = array([pa[0,0] for pa in case.get("APosterioriCovariance")]) +# +import matplotlib.pyplot as plt +plt.rcParams['figure.figsize'] = (10, 4) +# +plt.figure() +plt.plot(Observations,'kx',label='Noisy measurements') +plt.plot(Estimates,'r-',label='Estimated state') +plt.axhline(Xtrue,color='b',label='Truth value') +plt.legend() +plt.title('Estimate of the state', fontweight='bold') +plt.xlabel('Observation step') +plt.ylabel('Voltage') +plt.savefig("simple_KalmanFilter1_state.png") +# +plt.figure() +iobs = range(1,len(Observations)) +plt.plot(iobs,Variances[iobs],label='A posteriori error variance') +plt.title('Estimate of the a posteriori error variance', fontweight='bold') +plt.xlabel('Observation step') +plt.ylabel('$(Voltage)^2$') +plt.setp(plt.gca(),'ylim',[0,.01]) +plt.savefig("simple_KalmanFilter1_variance.png") diff --git a/doc/en/scripts/simple_KalmanFilter1.rst b/doc/en/scripts/simple_KalmanFilter1.rst index 3b2282a..f6423e7 100644 --- a/doc/en/scripts/simple_KalmanFilter1.rst +++ b/doc/en/scripts/simple_KalmanFilter1.rst @@ -6,3 +6,22 @@ is already known at the beginning of the time windows that it is called *reanalysis*, even if the iterative analysis keeps unkown the future observations at a given time step. +This example describes iterative estimation of a constant physical quantity (a +voltage) following seminal example of [Welch06]_ (pages 11 and following, also +available in the SciPy Cookbook). This model allows to illustrate the excellent +behavior of this algorithm with respect to the measurement noise when the +evolution model is simple. The physical problem is the estimation of the +voltage, observed on 50 time steps, with noise, which imply 50 analysis steps +by the filter. The idealized state (said the "true" value, unknown in a real +case) is specified as ``Xtrue`` in the example. The observations +:math:`\mathbf{y}^o` (denoted by ``Yobs`` in the example) are to be set, using +the keyword "*VectorSerie*", as a measure time series. We choose to emphasize +the observations versus the background, by setting a great value for the +background error variance with respect to the observation error variance. The +first observation is not used because the background :math:`\mathbf{x}^b` is +used as the first state estimate. + +The adjustment is carried out by displaying intermediate results during +iterative filtering. Using these intermediate results, one can also obtain +figures that illustrate the state estimation and the associated *a posteriori* +covariance estimation. diff --git a/doc/en/scripts/simple_KalmanFilter1_state.png b/doc/en/scripts/simple_KalmanFilter1_state.png new file mode 100644 index 0000000..fce0c7c Binary files /dev/null and b/doc/en/scripts/simple_KalmanFilter1_state.png differ diff --git a/doc/en/scripts/simple_KalmanFilter1_variance.png b/doc/en/scripts/simple_KalmanFilter1_variance.png new file mode 100644 index 0000000..9b13815 Binary files /dev/null and b/doc/en/scripts/simple_KalmanFilter1_variance.png differ diff --git a/doc/en/snippets/Header2Algo11.rst b/doc/en/snippets/Header2Algo11.rst new file mode 100644 index 0000000..0c4db3c --- /dev/null +++ b/doc/en/snippets/Header2Algo11.rst @@ -0,0 +1 @@ +The figures illustrating the result of its execution are as follows: diff --git a/doc/fr/ref_algorithm_KalmanFilter.rst b/doc/fr/ref_algorithm_KalmanFilter.rst index 656c85a..6153115 100644 --- a/doc/fr/ref_algorithm_KalmanFilter.rst +++ b/doc/fr/ref_algorithm_KalmanFilter.rst @@ -185,6 +185,18 @@ StoreSupplementaryCalculations .. literalinclude:: scripts/simple_KalmanFilter1.res +.. include:: snippets/Header2Algo11.rst + +.. _simple_KalmanFilter1_state: +.. image:: scripts/simple_KalmanFilter1_state.png + :align: center + :width: 90% + +.. _simple_KalmanFilter1_variance: +.. image:: scripts/simple_KalmanFilter1_variance.png + :align: center + :width: 90% + .. ------------------------------------ .. .. include:: snippets/Header2Algo06.rst diff --git a/doc/fr/scripts/simple_KalmanFilter1.py b/doc/fr/scripts/simple_KalmanFilter1.py index 71f6c70..adf3107 100644 --- a/doc/fr/scripts/simple_KalmanFilter1.py +++ b/doc/fr/scripts/simple_KalmanFilter1.py @@ -45,3 +45,31 @@ Pa = case.get("APosterioriCovariance") print("") print(" Variance a posteriori finale :",Pa[-1]) print("") +# +#------------------------------------------------------------------------------- +# +Observations = array([yo[0] for yo in Yobs]) +Estimates = array([xa[0] for xa in case.get("Analysis")]) +Variances = array([pa[0,0] for pa in case.get("APosterioriCovariance")]) +# +import matplotlib.pyplot as plt +plt.rcParams['figure.figsize'] = (10, 4) +# +plt.figure() +plt.plot(Observations,'kx',label='Mesures bruitées') +plt.plot(Estimates,'r-',label='État estimé') +plt.axhline(Xtrue,color='b',label='Valeur vraie') +plt.legend() +plt.title('Estimation de l\'état', fontweight='bold') +plt.xlabel('Pas d\'observation') +plt.ylabel('Tension') +plt.savefig("simple_KalmanFilter1_state.png") +# +plt.figure() +iobs = range(1,len(Observations)) +plt.plot(iobs,Variances[iobs],label='Variance d\'erreur a posteriori') +plt.title('Estimation de la variance d\'erreur a posteriori', fontweight='bold') +plt.xlabel('Pas d\'observation') +plt.ylabel('$(Tension)^2$') +plt.setp(plt.gca(),'ylim',[0,.01]) +plt.savefig("simple_KalmanFilter1_variance.png") diff --git a/doc/fr/scripts/simple_KalmanFilter1.rst b/doc/fr/scripts/simple_KalmanFilter1.rst index b71f2b8..3fc4fa9 100644 --- a/doc/fr/scripts/simple_KalmanFilter1.rst +++ b/doc/fr/scripts/simple_KalmanFilter1.rst @@ -6,3 +6,23 @@ complet de l'observation est déjà connu au début des fenêtres temporelles qu parle de *réanalyse*, même si l'analyse itérative conserve inconnues les observations futures à un pas de temps donné. +Cet exemple décrit l'estimation itérative d'une quantité physique constante +(une tension électrique) selon l'exemple de [Welch06]_ (pages 11 et suivantes, +aussi disponible dans le SciPy Cookbook). Ce modèle permet d'illustrer +l'excellent comportement de cet algorithme vis-à-vis du bruit de mesure lorsque +le modèle d'évolution est simple. Le problème physique est l'estimation d'une +tension électrique, observée sur 50 pas de temps, avec du bruit, ce qui +implique ensuite 50 étapes d'analyses par le filtre. L'état idéalisé (valeur +dite "vraie", inconnu dans un cas réel) est désigné par ``Xtrue`` dans +l'exemple. Les observations :math:`\mathbf{y}^o` (désignée par ``Yobs`` dans +l'exemple) sont à renseigner, en utilisant le mot-clé "*VectorSerie*", comme +une série chronologique de mesures. On privilégie les observations au détriment +de l'ébauche, par l'indication d'une importante variance d'erreur d'ébauche par +rapport à la variance d'erreur d'observation. La première observation n'est pas +utilisée car l'ébauche :math:`\mathbf{x}^b` sert de première estimation de +l'état. + +L'estimation s'effectue en affichant des résultats intermédiaires lors du +filtrage itératif. Grâce à ces informations intermédiaires, on peut aussi +obtenir les graphiques illustrant l'estimation de l'état et de la covariance +d'erreur a posteriori associée. diff --git a/doc/fr/snippets/Header2Algo11.rst b/doc/fr/snippets/Header2Algo11.rst new file mode 100644 index 0000000..5f1ef1a --- /dev/null +++ b/doc/fr/snippets/Header2Algo11.rst @@ -0,0 +1 @@ +Les graphiques illustrant le résultat de son exécution sont les suivants :