doc/en/ref_algorithm_QuantileRegression.rst

   1 ..
   2    Copyright (C) 2008-2015 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 .. index:: single: QuantileRegression
  25 .. _section_ref_algorithm_QuantileRegression:
  26
  27 Calculation algorithm "*QuantileRegression*"
  28 --------------------------------------------
  29
  30 Description
  31 +++++++++++
  32
  33 This algorithm allows to estimate the conditional quantiles of the state
  34 parameters distribution, expressed with a model of the observed variables. These
  35 are then the quantiles on the observed variables which will allow to determine
  36 the model parameters that satisfy to the quantiles conditions.
  37
  38 Optional and required commands
  39 ++++++++++++++++++++++++++++++
  40
  41 .. index:: single: AlgorithmParameters
  42 .. index:: single: Background
  43 .. index:: single: Observation
  44 .. index:: single: ObservationOperator
  45 .. index:: single: Quantile
  46 .. index:: single: Minimizer
  47 .. index:: single: MaximumNumberOfSteps
  48 .. index:: single: CostDecrementTolerance
  49 .. index:: single: StoreSupplementaryCalculations
  50
  51 The general required commands, available in the editing user interface, are the
  52 following:
  53
  54   Background
  55     *Required command*. This indicates the background or initial vector used,
  56     previously noted as :math:`\mathbf{x}^b`. Its value is defined as a
  57     "*Vector*" or a *VectorSerie*" type object.
  58
  59   Observation
  60     *Required command*. This indicates the observation vector used for data
  61     assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It
  62     is defined as a "*Vector*" or a *VectorSerie* type object.
  63
  64   ObservationOperator
  65     *Required command*. This indicates the observation operator, previously
  66     noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to
  67     results :math:`\mathbf{y}` to be compared to observations
  68     :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or
  69     a "*Matrix*" type one. In the case of "*Function*" type, different
  70     functional forms can be used, as described in the section
  71     :ref:`section_ref_operator_requirements`. If there is some control :math:`U`
  72     included in the observation, the operator has to be applied to a pair
  73     :math:`(X,U)`.
  74
  75 The general optional commands, available in the editing user interface, are
  76 indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters
  77 of the command "*AlgorithmParameters*" allows to choose the specific options,
  78 described hereafter, of the algorithm. See
  79 :ref:`section_ref_options_Algorithm_Parameters` for the good use of this
  80 command.
  81
  82 The options of the algorithm are the following:
  83
  84   Quantile
  85     This key allows to define the real value of the desired quantile, between
  86     0 and 1. The default is 0.5, corresponding to the median.
  87
  88     Example : ``{"Quantile":0.5}``
  89
  90   MaximumNumberOfSteps
  91     This key indicates the maximum number of iterations allowed for iterative
  92     optimization. The default is 15000, which is very similar to no limit on
  93     iterations. It is then recommended to adapt this parameter to the needs on
  94     real problems.
  95
  96     Example : ``{"MaximumNumberOfSteps":100}``
  97
  98   CostDecrementTolerance
  99     This key indicates a limit value, leading to stop successfully the
 100     iterative optimization process when the cost function or the surrogate
 101     decreases less than this tolerance at the last step. The default is 1.e-6,
 102     and it is recommended to adapt it to the needs on real problems.
 103
 104     Example : ``{"CostDecrementTolerance":1.e-7}``
 105
 106   StoreSupplementaryCalculations
 107     This list indicates the names of the supplementary variables that can be
 108     available at the end of the algorithm. It involves potentially costly
 109     calculations or memory consumptions. The default is a void list, none of
 110     these variables being calculated and stored by default. The possible names
 111     are in the following list: ["BMA", "CostFunctionJ", "CurrentState", "OMA",
 112     "OMB", "Innovation", "SimulatedObservationAtBackground",
 113     "SimulatedObservationAtCurrentState", "SimulatedObservationAtOptimum"].
 114
 115     Example : ``{"StoreSupplementaryCalculations":["BMA","Innovation"]}``
 116
 117 *Tips for this algorithm:*
 118
 119     As the *"BackgroundError"* and *"ObservationError"* commands are required
 120     for ALL the calculation algorithms in the interface, you have to provide a
 121     value, even if these commands are not required for this algorithm, and will
 122     not be used. The simplest way is to give "1" as a STRING for both.
 123
 124 Information and variables available at the end of the algorithm
 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 126
 127 At the output, after executing the algorithm, there are variables and
 128 information originating from the calculation. The description of
 129 :ref:`section_ref_output_variables` show the way to obtain them by the method
 130 named ``get`` of the variable "*ADD*" of the post-processing. The input
 131 variables, available to the user at the output in order to facilitate the
 132 writing of post-processing procedures, are described in the
 133 :ref:`subsection_r_o_v_Inventaire`.
 134
 135 The unconditional outputs of the algorithm are the following:
 136
 137   Analysis
 138     *List of vectors*. Each element is an optimal state :math:`\mathbf{x}*` in
 139     optimization or an analysis :math:`\mathbf{x}^a` in data assimilation.
 140
 141     Example : ``Xa = ADD.get("Analysis")[-1]``
 142
 143   CostFunctionJ
 144     *List of values*. Each element is a value of the error function :math:`J`.
 145
 146     Example : ``J = ADD.get("CostFunctionJ")[:]``
 147
 148   CostFunctionJb
 149     *List of values*. Each element is a value of the error function :math:`J^b`,
 150     that is of the background difference part.
 151
 152     Example : ``Jb = ADD.get("CostFunctionJb")[:]``
 153
 154   CostFunctionJo
 155     *List of values*. Each element is a value of the error function :math:`J^o`,
 156     that is of the observation difference part.
 157
 158     Example : ``Jo = ADD.get("CostFunctionJo")[:]``
 159
 160 The conditional outputs of the algorithm are the following:
 161
 162   BMA
 163     *List of vectors*. Each element is a vector of difference between the
 164     background and the optimal state.
 165
 166     Example : ``bma = ADD.get("BMA")[-1]``
 167
 168   CurrentState
 169     *List of vectors*. Each element is a usual state vector used during the
 170     optimization algorithm procedure.
 171
 172     Example : ``Xs = ADD.get("CurrentState")[:]``
 173
 174   Innovation
 175     *List of vectors*. Each element is an innovation vector, which is in static
 176     the difference between the optimal and the background, and in dynamic the
 177     evolution increment.
 178
 179     Example : ``d = ADD.get("Innovation")[-1]``
 180
 181   OMA
 182     *List of vectors*. Each element is a vector of difference between the
 183     observation and the optimal state in the observation space.
 184
 185     Example : ``oma = ADD.get("OMA")[-1]``
 186
 187   OMB
 188     *List of vectors*. Each element is a vector of difference between the
 189     observation and the background state in the observation space.
 190
 191     Example : ``omb = ADD.get("OMB")[-1]``
 192
 193   SimulatedObservationAtBackground
 194     *List of vectors*. Each element is a vector of observation simulated from
 195     the background :math:`\mathbf{x}^b`.
 196
 197     Example : ``hxb = ADD.get("SimulatedObservationAtBackground")[-1]``
 198
 199   SimulatedObservationAtCurrentState
 200     *List of vectors*. Each element is an observed vector at the current state,
 201     that is, in the observation space.
 202
 203     Example : ``Ys = ADD.get("SimulatedObservationAtCurrentState")[-1]``
 204
 205   SimulatedObservationAtOptimum
 206     *List of vectors*. Each element is a vector of observation simulated from
 207     the analysis or optimal state :math:`\mathbf{x}^a`.
 208
 209     Example : ``hxa = ADD.get("SimulatedObservationAtOptimum")[-1]``
 210
 211 See also
 212 ++++++++
 213
 214 Bibliographical references:
 215   - [Buchinsky98]_
 216   - [Cade03]_
 217   - [Koenker00]_
 218   - [Koenker01]_
 219   - [WikipediaQR]_