`hresol`

(**mandatory**): the horizontal resolution of the control vector.

**accepted values**:

`hpixels`

: use the native resolution of the corresponding data

`regions`

: aggregate pixels into regions using a mask specified by the user

`hbands`

: aggregate pixels by lon/lat bands

`ibands`

: aggregate pixels by column/row index bands

`global`

: optimize one factor for the whole spatial extent of the data

Warning

This argument determines whether the parameter is included in the control vector.
All other arguments will be ignored if this one is not specified.

`vresol`

(**optional**): the vertical resolution of the control vector.

**accepted values**:

`vpixels`

: use the native resolution of the corresponding data

`kbands`

: aggregate pixels into vertical bands by level index

`column`

(**default**): optimize one factor for the whole vertical
extent of the data

`tresol`

(**optional**): the main temporal resolution of the control vector. Should be a
pandas syntax string value. If not specified, only one increment for the full
inversion window

`tsubresol`

(**optional**): secondary resolution for the control vector. If
`tsubresol`

is not a divider of `tresol`

, the final temporal resolution will
keep `tresol`

as anchors and them split them accordingly to `tsubresol`

and fitting the size of the last sub-period of each period.

For instance if `tresol`

is `1MS`

and `tsubresol`

is `10D`

,
the control vector will have a monthly resolution with 3 sub-periods per month:
the two first periods are 10-days long according to `tsubresol`

and the third sub-period
fills the remaining days of the months, hence between 8 days (for February) to 11
days for 31-day-long months

`type`

(**optional**): type of increments:

**accepted values**:

`scalar`

(**default**): multiplicative increments.
The control vector and the uncertainty matrix store unitless scaling factors

`physical`

: additive increments.
The control vector and the uncertainty matrix store the values in the
original prior data set

`xb_scale`

: a scalar to apply to the prior before any computation

`xb_value`

: an offset to apply to the prior before any computation

`err`

: scaling factor to apply to the prior to compute the standard
deviation of prior uncertainties.

`err_type`

(**optional**): complement to `err`

; approach used to compute
prior uncertainties from prior values; used only when `type`

= `physical`

:

`glob_err`

(**optional**): used only when `type`

= `physical`

.
Can be used to specify a total error for the spatial extent of the prior. The
standard deviation of each spatial component of the control vector is scale,
so that the total error (accounting for the horizontal correlations if any) matches the one specified

**structure**:

`total`

(**mandatory**): the area-weighted sum of all prior values
is scaled according to this value.

`unit_scale`

(**optional**, default is 1): scaling factor to apply to
the sum of prior values. Use if the value specified in `total`

is not
in the same unit as the one in the prior values

`lowlim_error`

(**optional**): lower limit for the standard deviation of
prior uncertainties. The threshold is computed using the physical values of the
prior data

**structure**:

`err`

(**mandatory**): lower threshold for errors

`unit_scale`

(**optional**, default is 1): scaling factor to apply to
prior values. Use if the value specified in `err`

is not in the
same unit as the one in the prior values

`hcorrelations`

(**optional**): horizontal correlations. In most cases,
the matrix **B** is not explicitly built. Instead, Kronecker products are used for
each temporal slice of the control vector, horizontal correlations are used

**structure**:

`sigma`

: the horizontal correlation length in kilometers

`landsea`

(**optional**, default is False): separate land and sea pixels

`sigma_land`

: the horizontal correlation length for land pixels

`sigma_sea`

: the horizontal correlation length for sea pixels

`filelsm`

: the path to the land-sea mask; it is a NetCDF with a
variable `lsm`

; ocean pixels are pixels with `lsm`

< 0.5

`dump_hcorr`

(**optional**, default is False):
save horizontal correlations (as eigen vectors and values) for later use;
they are saved in the folder `$WORKDIR/controlvect/correlations/`

;
the name of each file is: ```
horcor_{hresol}_{nlon}x{nlat}_cs{
sigma_sea}_cl{sigma_land}.bin
```

; a suffix `_lbc`

is appended if
correlations are computed for a lateral boundary condition component

`dircorrel`

(**optional**): where to look for pre-computed
correlations; files are looked for in the folder following the same format
as for `dump_hcorr`

`evalmin`

(**optional**, default is 0): minimal value for eigen
values to filter out

`crop_chi`

(**optional**, default is False): if True, the regularized vector
\(\mathbf{\chi}\) has a reduced dimension (consistent with
`evalmin`

) compared to the full control vector

`tcorrelations`

(**optional**): lower limit for the standard deviation of
prior uncertainties. The threshold is computed using the physical values of the
prior data

**structure**:

`multi_sigmas`

(default is False): it is possible to convolve multiple
temporal correlation lengths and type (see below).
if `multi_sigmas`

is True, add a sub-paragraph `sigmas`

,
with multiple entries; for each entry (the name has no importance), specify the `sigma_t`

and
`type`

; this read as follows:

tcorrelations:
multi_sigmas: True
sigmas:
sigma1:
type: isotrope
sigma_t: "3D"
sigma2:
type: frequency
freq: "1D"
sigma_t: "10D"
sigma3:
type: category
scale: "hourofday"
sigma_t: "50D"

Note

Please note the if `multi_sigmas`

is True, only the correlation
values below `sigmas`

will be accounted for.

`sigma_t`

(**mandatory**): temporal correlation length; should be a
pandas frequency string

`type`

(**mandatory**): type of temporal correlation

**accepted values**:

`isotrope`

: correlations are simply computed following the
temporal distance:
\(r = \exp((\delta t / \sigma_t) ^ 2)\)

`frequency`

: only control vector components separated by a period of
exactly the given `frequency`

will be correlated,
still following the same formula as for `isotrope`

;

for instance if `frequency`

= `1D`

, only components at the
same hour of the day will be correlated with each others

`category`

: the temporal distance to apply the correlation
formula is calculated by temporal categories

**accepted values**: [`hourofday`

, `dayofweek`

,
`monthofyear`

]

for instance, with `hourofday`

, a component at `12:00`

on a given day
will be more correlated to a component at `13:00`

for another
day, than with a component at `18:00`

of the same day

`dump_tcorr`

(**optional**, default is False):
save horizontal correlations (as eigen vectors and values) for later use;
they are saved in the folder `$WORKDIR/controlvect/correlations/`

;
the name of each file is: ```
tempcor_{datei}_{datef}_per{period}_ct{
sigma_t}_{sigma_type}.bin
```

; a suffix `_lbc`

is appended if

`dircorrel`

(**optional**): where to look for pre-computed correlations

`evalmin`

(**optional**, default is 0): minimal value for eigen
values to filter out

`crop_chi`

(**optional**, default is False): if True, the regularized vector
\(\mathbf{\chi}\) has a reduced dimension (consistent with
`evalmin`

) compared to the full control vector