For each parameter in the data vector the following primary arguments are recognized by
the CIF to define the corresponding part of the control vector.
- lower_bound : float, optional
lower boundary for the value of this control variable
- upper_bound : float, optional
upper boundary for the value of this control variable.
- 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
- Argument structure:
- total : float, mandatory
the area-weighted sum of all prior values
is scaled according to this value
- unit_scale : float, optional, default 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
- surface_unit : bool, optional, default False
set to True if the total value is given per unit of surface
- frequency_unit : bool, optional, default False
set to True if the total value is given per unit of time
- account_correlations : bool, optional, default True
account or not for correlations to compute the total errors, i.e. also summing non-diagonal terms of the covariance matrix
- lowlim_error : optional
lower limit for the standard deviation of
prior uncertainties. The threshold is computed using the physical values of the
prior data
- Argument structure:
- err : float, mandatory
lower threshold for errors
- unit_scale : float, optional, default 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
- Argument structure:
- sigma : float, optional
the horizontal correlation length in kilometers
- landsea : bool, optional, default False
separate land and sea pixels
- sigma_land : float, optional
the horizontal correlation length for land pixels
- sigma_sea : float, optional
the horizontal correlation length for sea pixels
- filelsm : str, optional
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 : bool, optional, default 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 : str, optional
where to look for pre-computed
correlations; files are looked for in the folder following the same format
as for dump_hcorr
- evalmin : float, optional, default 0
minimal value for eigen values to filter out
- crop_chi : bool, optional, default 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
- Argument structure:
- multi_sigmas : bool, optional, default 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.
- sigmas : optional
temporal correlation lengths and types, to be used with multi_sigmas
- Argument structure:
- any_key : optional
correlation length and type
- Argument structure:
- sigma_t : float, mandatory
correlation length
- type : str, mandatory
correlation type
- sigma_t : str, optional
temporal correlation length; should be a pandas frequency string
- type : “isotrope” or “frequency” or “category”, optional
the horizontal correlation length for land pixels
“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,:bash: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 : bool, optional, default 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 : str, optional
where to look for pre-computed correlations
- evalmin : float, optional, default 0
minimal value for eigen values to filter out
- crop_chi : None, optional, default False
if True, the regularized vector
\(\mathbf{\chi}\) has a reduced dimension (consistent with
evalmin) compared to the full control vector
Depending on the choice of primary arguments, secondary arguments may be specified.
The argument between brackets corresponds to the primary arguments triggering the use
of the corresponding secondary argument:
