Uncertainty propagation¶
Independent uncertainties are defined and propagated with the set_uncertainty
and propagate
methods.
All derivatives needed for uncertainty propagation are calculated with automatic differentiation.
Define independent uncertainties¶
If the uncertainty in each argument is independent – i.e. there is no covariance between the uncertainties in different parameters – then the set_uncertainty
and propagate
methods can be used to propagate the parameter uncertainties through into any result:
import PyCO2SYS as pyco2
# Set up the CO2System
co2s = pyco2.sys(dic=2100, alkalinity=2250, temperature=20)
# Define uncertainties in the known parameters
co2s.set_uncertainty(dic=2, alkalinity=1)
set_uncertainty
kwargs
set_uncertainty
can take the same kwargs as pyco2.sys
, excepting the settings (keys beginning with "opt_"
). It is not necessary to provide an uncertainty for every parameter - those that are not specified are assumed to have zero uncertainty.
The values provided should be the 1σ uncertainty in each parameter. They can be single scalar values or arrays matching the shape of the correpsonding parameter.
To provide a fractional value for any uncertainty, append "__f"
to the end of its key in uncertainty_from
.
The "standard" uncertainties in the equilbrium constants and total borate used by CO2SYS for MATLAB following OEDG18 are available as a dict in the correct format for set_uncertainty
at pyco2.uncertainty_OEDG18
:
# Also include equilibrium constant uncertainties
co2s.set_uncertainty(**pyco2.uncertainty_OEDG18)
If set_uncertainty
is run multiple times on the same CO2System
, each successive call adds to the existing set of uncertainties, overwriting where an uncertainty for that parameter was already declared.
set_uncertainty
after propagate
If set_uncertainty
is run after running propagate
on a system, then propagate
will automatically be run again with the new set uncertainties, so that the values in co2s.uncertainty
are all correct for the current set of assigned uncertainties.
Propagate independent uncertainties¶
# Propagate uncertainties set with set_uncertainty
co2s.propagate(["pH", "fCO2"])
# Access uncertainty results
uncert_fCO2 = co2s.uncertainty["fCO2"]
uncert_pH_due_to_dic = co2s.uncertainty["pH"]["dic"]
The total uncertainties are the Pythagorean sum of all the components. This calculation assumes that all argument uncertainties are independent from each other and that they are provided in terms of single standard deviations.
propagate
arguments
uncertainty_into
: a list of the parameter keys that uncertainties are to be propagated into.
If propagate
is run with no arguments, then uncertainties will be propagated into all results that have been currently solved for.
propagate
results
The uncertainty results are stored in co2s.uncertainty
, for which co2s.u
can be used as a shortcut.
-
For each result
into
inuncertainty_into
, there is a new sub-dictco2s.uncertainty[into]
containing the total and component uncertainties in that result. -
The total uncertainty is in
co2s.uncertainty[into]
. -
The uncertainties from each argument
from
that has had an uncertainty defined withset_uncertainty
are also in the sub-dict with the corresponding keys:co2s.uncertainty[into][from]
.
All into
and from
values can be accessed with dot notation instead of with square brackets, and the shortcuts can be used.
Uncertainties with covariances¶
PyCO2SYS does not currently have a generalised function for the complete process of propagating uncertainties that co-vary. However, it does allow the derivative of any result with respect to any argument to be calculated:
grads_of = ["pH"] # Get derivatives of pH...
grads_wrt = ["dic", "alkalinity"] # ... with respect to DIC and alkalinity
co2s.get_grads(grads_of, grads_wrt)
# Access derivatives
dpH_ddic = co2s.grads["pH"]["dic"]
dpH_dalk = co2s.grads["pH"]["alkalinity"]
get_grads
arguments
grads_of
: a list of parameter keys for which the derivatives of are to be calculated.grads_wrt
: a list of parameter keys for which the derivatives with respect to are to be calculated.
get_grads
results
For each result of
in grads_of
and argument wrt
in grads_wrt
, the corresponding derivative is stored in co2s.grads[of][wrt]
.
No shortcuts here
The shortcuts cannot be used in the arguments grads_of
and grads_wrt
in the get_grads
function, nor when accessing keys from co2s.grads
.