Skip to content

Quick-start guide

All the code examples assume the following import convention:

import PyCO2SYS as pyco2

Solve the marine carbonate system

The only function most users will need from PyCO2SYS is pyco2.sys. For example:

# Set up a CO2System
co2s = pyco2.sys(alkalinity=2250, dic=2100, temperature=15, salinity=34)

# Solve for and return the value of pH
pH = co2s["pH"]

# Solve for and return pCO2 and fCO2 at the same time
# (`results` is a dict with the keys "pCO2" and "fCO2")
results = co2s[["pCO2", "fCO2"]]

As seen above, results can be calculated and accessed with square brackets, as if co2s were a dict. It isn't a dict, it's a CO2System, so it can do some other things too.

Each call of pyco2.sys may include up to two known core marine carbonate system parameters, which are DIC (dic), total alkalinity (alkalinity), pH (pH), pCO2 (pCO2), fCO2 (fCO2), xCO2 (xCO2), (bi)carbonate ion content (HCO3 and CO3), and the saturation state of aragonite (saturation_aragonite) and calcite (saturation_calcite).

Find out more

See User guide / Arguments and results for the full sets of keyword arguments that can be provided to pyco2.sys and the results parameters that can be calculated.

See User guide / Advanced tips and tricks for a more detailed overview of how results can be solved for and accessed from a CO2System.

A few common examples are given below.

Calculate without core parameters

Some properties (mainly equilibrium constants and total salt contents) can be calculated without solving the marine carbonate system, so pyco2.sys can be run with no core parameters:

# Set up a CO2System under default conditions 
# (temperature 25 °C, salinity 35, hydrostatic pressure 0 dbar
#   - other values could be specified with the appropriate kwargs)
co2s = pyco2.sys()

# Get water dissociation constant
pk_H2O = co2s["pk_H2O"]

Use different parameterisations

PyCO2SYS contains many different options for the parameterisations of equilibrium constants and total salt contents. These can be selected using kwargs beginning with opt_, for example:

# Set up a CO2System with non-default equilibrium constants for carbonic acid
# and non-default total borate from salinity
co2s = pyco2.sys(opt_k_carbonic=3, opt_total_borate=2)

All settings arguments must be single, scalar, integer values.

Convert to different temperatures and/or pressures

Find out more

See User guide / Adjust conditions for more detail on temperature and pressure conversions.

With two known parameters

To convert parameters to different temperatures and/or pressures, use the adjust method.

For example, to calculate the saturation state with respect to aragonite under in situ conditions from alkalinity and pH measured in the laboratory at 25 °C:

# Set up the initial CO2System under lab conditions
co2s_lab = pyco2.sys(alkalinity=2250, pH=8.1, temperature=25, salinity=32)

# Adjust to in situ conditions (10 °C and 1500 dbar hydrostatic pressure)
co2s_insitu = co2s_lab.adjust(temperature=10, pressure=1500)
saturation_aragonite = co2s_insitu["saturation_aragonite"]

With one known parameter

The partial pressure (pCO2), fugacity (fCO2), dry-air mole fraction (xCO2) and aqueous content (CO2) of CO2 can be interconverted and adjusted to different temperatures without a second parameter:

# Set up the initial CO2System with known pCO2
co2s_lab = pyco2.sys(pCO2=400, temperature=25)

# Calculate fCO2 under lab conditions (optional step)
fCO2_lab = co2s_lab["fCO2"]

# Adjust fCO2 to in situ conditions(10 °C and 1500 dbar hydrostatic pressure)
co2s_insitu = co2s_lab.adjust(temperature=10, pressure=1500)
fCO2_insitu = co2s_insitu["fCO2"]

Propagate uncertainties

Find out more

See User guide / Uncertainty propagation for more detail on propagating uncertainties.

Uncertainties are defined and propagated using the set_uncertainty and propagate methods:

  • set_uncertainty is used to define the independent uncertainties in input parameters. The kwargs used are the same as for the main pyco2.sys function.

  • propagate propagates the defined uncertainties through to the calculated results.

For example, to get the total uncertainty in pH from independent uncertainties in alkalinity and DIC:

# Set up a CO2System
co2s = pyco2.sys(alkalinity=2250, dic=2100, temperature=15, salinity=34)

# Uncertainties in alkalinity and DIC are both 2 µmol/kg
co2s.set_uncertainty(alkalinity=2, dic=2)

# Propagate through to pH
co2s.propagate("pH")

# Retrieve total uncertainty in pH
pH_uncertainty = co2s.uncertainty["pH"]

# Retrieve component of pH uncertainty due to DIC
pH_uncertainty = co2s.uncertainty.parts["pH"]["dic"]

Multidimensional data

NumPy arrays

All arguments other than settings can be provided as lists or multidimensional numpy arrays. The dimensions of different arguments can be different as long as they can be broadcasted together.

# Define multidimensional arguments
dic = np.array([2000, 2100, 2200])
pCO2 = np.array([400, 450, 485])

# Set up a CO2System
co2s_1D = pyco2.sys(dic=dic, pCO2=pCO2)
alkalinity_1D = co2s_1D["alkalinity"]  # shape is (3,)

co2s_2D = pyco2.sys(dic=dic, pCO2=np.vstack(pCO2))
alkalinity_2D = co2s_2D["alkalinity"]  # shape is (3, 3)

Data structures

Some common data structures can be provided to pyco2.sys using the data kwarg.

Dict(ionarie)s

If your data are in a dict, you can provide this as data:

# Define known parameters
df = {"dic": [2000, 2100, 2200], "pCO2": [400, 450, 485]}

# Set up a CO2System, including an extra parameter that was not
# in the dict (total_silicate), and an optional setting
co2s = pyco2.sys(data=df, total_silicate=1.5, opt_k_carbonic=9)

If some of the dict keys do not match the kwargs expected by pyco2.sys, the correct keys can be given as the corresponding kwargs:

# Define known parameters
df = {"dic_calibrated": [2000, 2100, 2200], "pCO2_data": [400, 450, 485]}

# Set up a CO2System
co2s = pyco2.sys(
    data=df,
    dic="dic_calibrated",
    pCO2="pCO2_data",
    total_silicate=1.5,
    opt_k_carbonic=9,
)

Pandas DataFrames

DataFrame not Series

Pandas data must be collected into a DataFrame and passed together through the data kwarg. It's not possible to pass individual pandas Seriess separately as kwargs to pyco2.sys. If this is necessary, then each Series must first be converted into a NumPy array.

If data are in a pandas DataFrame, this can be provided as data, and results returned as a pandas Series or DataFrame with consistent indexing:

# Define known parameters
df = pd.DataFrame({"dic": [2000, 2100, 2200], "pCO2": [400, 450, 485]})

# Set up a CO2System
co2s = pyco2.sys(data=df, total_silicate=1.5, opt_k_carbonic=9)

# Solve for and return a parameter as a Series
pH = co2s.to_pandas("pH")

# Solve for and return parameters as a DataFrame
df_results = co2s.to_pandas(["pH", "alkalinity"])

Running to_pandas with no arguments will return a DataFrame containing all currently calculated parameters.

Xarray Datasets

Dataset not DataArray

Xarray data must be collected into a Dataset and passed together through the data kwarg. It's not possible to pass individual xarray DataArrays separately as kwargs to pyco2.sys. If this is necessary, then each DataArray must first be converted into a NumPy array.

If data are in an xarray Dataset, this can be provided as data, and results returned as an xarray DataArray or Dataset with consistent dimensions:

# Define known parameters
ds = xr.Dataset({
    "temperature": ("dim_t", np.arange(0, 35)),
    "salinity": ("dim_s", np.arange(30, 40)),
})

# Set up a CO2System
co2s = pyco2.sys(data=ds)

# Solve for and return a parameter as a DataArray
k_CO2 = co2s.to_xarray("k_CO2")

# Solve for and return parameters as a Dataset
ds_results = co2s.to_xarray(["k_H2CO3", "k_HCO3"])

Running to_xarray with no arguments will return a Dataset containing all currently calculated parameters.