Skip to content

The Dataset of titration metadata

A Calkulate Dataset is just a pandas DataFrame with some extra methods added.

You can make a Dataset from an existing DataFrame or by importing a spreadsheet from various formats.

There are some example Dataset spreadsheets in various formats to look at on GitHub.

Whichever way you do it, each row of the Dataset corresponds to a separate titration, and each column contains a different piece of metadata. Some columns are required, others are optional. The columns must be named as follows.

Dataset column names

Click on each banner to expand and see more detail.

Extra columns will be ignored by Calkulate and should not cause any problems.

Required columns

file_name : name of the titration file

This should include the file extension (e.g. .dat). The file path can either be included in the file name or be specified separately in a file_path column.

salinity : practical salinity of the analyte

This is dimensionless.

analyte_mass or analyte_volume : mass (kg) or volume (ml) of the analyte

Mass must be in kg and volume in ml.

If volume is provided, it is converted into mass following MP81.

If both are provided for a given titration, mass is used and volume is ignored.

Not strictly essential, but you'll need these most of the time. If values are only needed for some of your titrations, just use np.nan in rows where they are not required.

alkalinity_certified : known alkalinity value (e.g. for a reference material)

Must be in μmol/kg-solution.

analysis_batch : identifies subsets that can be calibrated together

A list of analysis batch names or numbers. It is assumed that all titrations with the same analysis_batch value have a common titrant. If nothing is provided, all titrations are assumed to have a common titrant.

dic : dissolved inorganic carbon (μmol/kg-solution)

In μmol/kg-solution.

Defaults to zero if not provided.

file_path : path to the titration file

This is prefixed to file_name.

total_* : total salt concentrations (μmol/kg-solution)

These must all be in μmol/kg-solution.

Some default to zero if not provided:

  • total_ammonia : total ammonia + ammonium
  • total_phosphate : total phosphate
  • total_silicate : total silicate
  • total_sulfide : total hydrogen sulfide

Others are estimated from salinity by PyCO2SYS if not provided:

  • total_borate : total borate
  • total_fluoride : total fluoride
  • total_sulfate : total sulfate

Optional columns

Like for the recommended columns, if optional column values are only needed for some of your titrations, just use np.nan in rows where they are not required.

file_good : is the titration file valid?

Where set to False, Calkulate does not attempt to import the corresponding titration file.

k_* : stoichiometric equilibrium constants

If not provided, then these are calculated from temperature and salinity by PyCO2SYS.

They must all be on the Free pH scale.

  • k_borate : boric acid equilibrium constant.
  • k_carbonic_1 and k_carbonic_2 : carbonic acid dissociation constants.
  • k_fluoride : HF equilibrium constant.
  • k_phosphoric_1, k_phosphoric_2 and k_phosphoric_3 : phosphoric acic dissociation constants.
  • k_silicate : orthosilicic acid equilibrium constant.
  • k_sulfide : hydrogen sulfide equilibrium constant.
  • k_bisulfate : bisulfate dissociation constant.
  • k_water : water equilibrium constant.
molinity_HCl : approximate HCl molinity in the HCl titrant

In mol/kg-solution. Defaults to 0.1 mol/kg-solution if not provided. Used only to estimate titrant density, not for calibration.

molinity_NaCl : approximate NaCl molinity in the HCl titrant

In mol/kg-solution. Defaults to 0.6 mol/kg-solution if not provided. Used only to estimate titrant density.

molinity_H2SO4 : approximate NaCl molinity in the H2SO4 titrant

In mol/kg-solution. Defaults to 0.1 mol/kg-solution if not provided. Used only to estimate titrant density, not for calibration.

opt_k_bisulfate : which bisulfate dissociation constant to use

Sets whether the bisulfate dissociation constant is estimated from salinity and temperature by PyCO2SYS following:

opt_k_carbonic : which carbonic acid dissociation constants to use

Sets which carbonic acid constants to use from PyCO2SYS, can be any integer from 1 to 16 inclusive. Default is 16 for SLH20. See the PyCO2SYS docs on opt_k_carbonic for details.

opt_k_fluoride : which HF dissociation constant to use

Sets whether the HF dissociation constant is estimated from salinity and temperature by PyCO2SYS following:

opt_total_borate : which total borate:salinity relationship to use

Sets whether total borate is estimated from salinity by PyCO2SYS following:

read_dat_method : which file format are your titration data in?

Indicates the format of the titration data file:

reference_good : use this reference material to calibrate?

Set to False for reference materials that you do not wish to include in determining batch-mean titrant concentrations.

temperature_override : titration temperature

Must be in °C. If not supplied, the values in the titration file are used. Otherwise, this value overrides them.

titrant : The titrant being used

Use "HCl" (default) for hydrochloric acid or "H2SO4" for sulfuric acid.

titrant_amount_unit : unit for the amount of titrant in the titration file

Either "ml" (default) for volume in ml or "g" / "kg" for mass in g / kg.

If volume is provided, then if titrant="HCl" or by default, it is converted into mass following DSC07, assuming the acid contains 0.6 M NaCl and 0.1 M HCl and is at 25 °C. If you used a different ratio, use the columns molinity_NaCl and molinity_HCl to set this.

If you used titrant="H2SO4", then titrant density is calculated at 25 °C following a basic parameterisation of E-AIM results against molinity.

Regardless of the titrant, these density equations can also be overwritten with a specific value in the titrant_density column.

titrant_density : density of the titrant

Titrant density in kg/dm3. If provided, this is used only when titrant_amount_unit="ml", and it takes precedence over density calculated from the equations described in that section.

titrant_molinity : molinity of the titrant

Must be in mol/kg-solution.