Uncertainty propagation¶
PyCO2SYS provides tools to propagate uncertainties in all arguments through to all results of its marine carbonate system calculations.
Evaluating the derivatives
All derivatives needed for uncertainty propagation are calculated using forward finitedifferences. Explicity, the derivative of result r with respect to argument a is estimated with:
\frac{\partial r(a)}{\partial a} \approx \frac{r(a + \Delta a)  r(a)}{\Delta a}
As the different arguments span many orders of magnitude, PyCO2SYS uses a different \Delta a value for each argument.
Independent uncertainties¶
If the uncertainty in each argument is independent – i.e. there is no covariance between uncertainties in different parameters – then you can use PyCO2SYS.uncertainty.propagate
to propagate the parameter uncertainties through into any result.
Syntax¶
Uncertainty propagation can be performed by adding some extra keyword arguments to pyco2.sys
.
import PyCO2SYS as pyco2
# Example arguments: known DIC and pH, at 10 degC
kwargs = {
"par1": 2150.0,
"par2": 8.1,
"par1_type": 2,
"par2_type": 3,
"temperature": 10,
}
# Normal way to run PyCO2SYS, without uncertainties:
results = pyco2.sys(**kwargs)
# Alternatively, calculate uncertainties at the same time:
results = pyco2.sys(
**kwargs,
uncertainty_into=["alkalinity", "k_carbonic_1"],
uncertainty_from={
"par1": 2.0,
"temperature": 0.05,
}
)
Arguments¶
pyco2.sys
uncertainty arguments
The same kwargs
as for pyco2.sys
¶
Provide all the necessary keyword arguments for pyco2.sys
.
Uncertainties¶

uncertainty_into
: a list of strings of the results keys to propagate uncertainties into. 
uncertainty_from
: a dict of the uncertainties in the arguments to propagate throughpyco2.sys
.
The keys of uncertainty_from
can include any arguments of pyco2.sys
that can have an uncertainty. The key for each uncertainty in uncertainty_from
should be the same as the corresponding key in the main pyco2.sys
results dict.
If you want to provide a fractional value for any uncertainty, append "__f"
to the end of its key in uncertainty_from
.
For the equilibrium constants, if you wish to propagate an uncertainty in terms of a pK value rather than K, prefix the corresponding key in uncertainty_from
with a "p"
(e.g. use "pk_carbonic_1"
instead of "k_carbonic_1"
). Uncertainties in equilibrium constants under input and output conditions are treated independently. To use the same (covarying) uncertainty for both, append "_both"
to the input condition key (e.g. "k_carbonic_1_both"
). In this case, you must have provided a value for either temperature_out
or pressure_out
.
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 uncertainty_from
at pyco2.uncertainty_OEDG18
.
The values of uncertainty_from
are the uncertainties in each input parameter as a standard deviation. You can provide a single value if all uncertainties are the same for a parameter, or an array the same size as the parameter if they are different. Any parameters not included are assumed to have zero uncertainty.
Results¶
pyco2.sys
uncertainty results
If uncertainty_into
and uncertainty_from
are provided, then the uncertainty results are added as additional entries to the standard results
dict. This includes the total uncertainty as well as individual components.

For each result in
uncertainty_into
, there is a new key"u_<into>"
in theresults
dict, containing the total uncertainty in the result from all arguments combined. 
For each result in
uncertainty_into
and argument inuncertainty_from
, there is a new key"u_<into>__<from>"
in theresults
dict, containing the uncertainty in the result from only the specified argument.
The combined 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.
Uncertainties with covariances¶
PyCO2SYS does not currently have a generalised function for the complete process of propagating uncertainties that covary. However, it does allow you calculate the forward finitedifference derivative of any result with respect to any argument. The syntax is similar as described above for uncertainties:
import PyCO2SYS as pyco2
# Example arguments: known DIC and pH, at 10 degC
kwargs = {
"par1": 2150.0,
"par2": 8.1,
"par1_type": 2,
"par2_type": 3,
"temperature": 10,
}
# Normal way to run PyCO2SYS, without derivatives:
results = pyco2.sys(**kwargs)
# Alternatively, calculate derivatives at the same time:
results = pyco2.sys(
**kwargs,
grads_of=["alkalinity", "k_carbonic_1"],
grads_wrt=["par1", "temperature"],
)
In general, this works the same as the uncertainty propagation approach described in the previous section. The main differences are:
grads_of
is equivalent touncertainty_into
.grads_wrt
(w.r.t. = with respect to) is equivalent touncertainty_from
, but values are not required, so it can be a list. A dict is also fine; its values are ignored. The
"__f"
key extension cannot be used ingrads_wrt
.  For each result in
grads_of
and argument ingrads_wrt
, there is a new key"d_<into>__d_<from>"
in theresults
dict, containing the derivative of the result with respect to the argument.