# Calkulate¶

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

## Installation¶

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 https://github.com/mvdh7/calkulate/archive/v3.0.0-beta.2.tar.gz


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")
tdata.calibrate_and_solve()


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 = calk.io.read_dbs("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!
tdata.calibrate_and_solve()

# 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.

## About¶

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

## Citation¶

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
calk.say_hello()


## License¶

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