Skip to content


Calkulate is a Python package for finding total alkalinity from titration data using PyCO2SYS.


This documentation site is for version 3, which is in development. For now, install with:

conda create -n calkenv python=3.8 numpy scipy matplotlib seaborn pandas xlrd
conda activate calkenv
pip install PyCO2SYS==1.5.1
pip install

For version 2, install with:

pip install calkulate

Get started very quickly

If you had a perfect titration table set up and your .dat files were all VINDTA-formatted, then all you need to do with Calkulate is:

import calkulate as calk
tdata = calk.Dataset("titration-table.csv")

All the results you need are stored in a standard pandas DataFrame at tdata.table.

However, we have to put a little more preparatory work in to start from e.g. a VINDTA dbs file, but it's essentially the same process as above:

import calkulate as calk

# Import the dbs file generated by the VINDTA as a pandas DataFrame
tdata ="filename.dbs", analyte_volume=100)
# analyte_volume is optional, assumed 100 (ml) if you don't set it,
# should be the volume of the TA pipette (in ml)

# Add extra field definitely needed by Calkulate
tdata["alkalinity_certified"] = ...  # must contain certified TA values for CRMs, np.nan everywhere else

# These are optional, assumed zero if you don't provide values:
tdata["total_carbonate"] = ...  # DIC for each sample in micromol/kg
tdata["total_phosphate"] = ...  # total phosphate in micromol/kg
tdata["total_silicate"] = ...  # total silicate in micromol/kg
tdata["total_sulfide"] = ...  # total sulfide in micromol/kg
tdata["total_ammonia"] = ...  # total ammonia in micromol/kg
# Also update the "salinity" column (imported from the dbs) if the values there aren't correct

# Other extra fields that you might need, but can leave out
tdata["file_path"] = "path/to/the/dat/files/"
tdata["analysis_batch"] = ...  # identify which samples and CRMs can be calibrated together,
                               # e.g. based on the batch of HCl titrant used.
tdata["temperature_override"] = 25  # use this if the temperature values in your .dat files
                                    # are not reliable (in degrees C)
tdata["reference_good"] = True  # set to False for any CRMs that you don't want to use for calibration

##### Now the actual alkalinity solving: #####
# Convert the table to a titration Dataset, and import all the .dat files
tdata = calk.Dataset(tdata)
# the original table can now be found in tdata.table

# Calibrate acid concentrations for the CRMs, and solve every titration for alkalinity!

# Final results have now been added to the titration table.
# If you need to pull them out:
titrant_molinity_calibrated  = tdata.table.titrant_molinity_calibrated  # calibrated acid concentration
                                                                        # for each CRM individually
titrant_molinity = tdata.table.titrant_molinity  # calibrated acid concentration used to calculate
                                                 # TA i.e. averaged across the analysis_batch
alkalinity = tdata.table.alkalinity  # the final TA results in micromol/kg

# Plot all the calibrations.
# Shows offsets between solved and certified alkalinity for the CRMs.
# Obviously this will be centred on zero because the CRMs were used to calibrate -
# but the scatter gives some indication of measurement precision.
tdata.plot_calibration()  # plots all analysis batches together
# Or use batches kwarg to just plot for a specific analysis_batch:
tdata.plot_calibration(batches=5)  # e.g. just plots CRMs where "analysis_batch" is 5

In a bit more detail

  1. Check what settings you need to use (if any) to import your titration data files.
  2. Read how to import and work with data from a single titration.
  3. See the additional tools for efficiently investigating datasets of multiple titrations.


Calkulate is being developed by Dr Matthew Humphreys at the Royal Netherlands Institute for Sea Research (NIOZ, Texel, the Netherlands).


If you use Calkulate in your work, please cite it as:

Calkulate citation

Humphreys, M. P. and Matthews, R. S. (2020). Calkulate: total alkalinity from titration data in Python. Zenodo. doi:10.5281/zenodo.2634304.

Please specify which version you are using. To find this:

import calkulate as calk


Calkulate is licensed under the GNU General Public License version 3 (GPLv3).