The Dataset of titration metadata¶
A Calkulate Dataset is a pandas DataFrame with some extra methods added.
A Dataset can be made 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 it is done, 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.
Recommended columns¶
Not strictly essential, but these will be needed most of the time. If values are only needed for some 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-sol.
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-sol)
In µmol/kg-sol.
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-sol)
These must all be in µmol/kg-sol.
Some default to zero if not provided:
total_ammonia: total ammonia + ammoniumtotal_phosphate: total phosphatetotal_silicate: total silicatetotal_sulfide: total hydrogen sulfide
Others are estimated from salinity by PyCO2SYS if not provided:
total_borate: total boratetotal_fluoride: total fluoridetotal_sulfate: total sulfate
Optional columns¶
Like for the recommended columns, if optional column values are only needed for some titrations. Just use np.nan in rows where they are not required.
dilute_totals_for_ks : account for dilution when calculating equilibrium constants?
If False (default if not provided), then don't account for dilution of total sulfate and fluoride when calculating equilibrium constants.
Introduced in v23.7 - in earlier versions, default behaviour was like dilute_totals_for_ks=True.
double : solve twice to improve pH range?
If True (default if not provided), then solve each titration twice, using the EMF0 from the first solution as the start-point for the second. This means that the set of data points used more accurately matches the pH range specified by pH_min and pH_max.
Introduced in v23.7 - in earler versions, default behaviour was like double=False.
file_good : is the titration file valid?
Where set to False, Calkulate does not attempt to import the corresponding titration file.
file_type : which file format are your titration data in?
Indicates the format of the titration data file:
"genfromtxt": the default VINDTA-style format, or"pclims": PC-LIMS report files generated by e.g. a Metrohm Titrino unit."tiamo_de": files from German-language Tiamo software.
Alias for read_dat_method, added in v23.7.
gran_logic : which points to use for Gran-plot estimates
Prior to v23.7, Gran-plot initial estimates of alkalinity and EMF0 were determined using data points that were above 10% and below 90% of the maximum value of the Gran function. From v23.7, the 90% upper cutoff was removed.
"v23.7+": use the new behaviour without upper cutoff (default)."legacy": use the original approach with upper and lower cutoffs.
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_1andk_carbonic_2: carbonic acid dissociation constants.k_fluoride: HF equilibrium constant.k_phosphoric_1,k_phosphoric_2andk_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-sol. Defaults to 0.1 mol/kg-sol if not provided. Used only to estimate titrant density, not for calibration.
molinity_NaCl : approximate NaCl molinity in the HCl titrant
In mol/kg-sol. Defaults to 0.6 mol/kg-sol if not provided. Used only to estimate titrant density.
molinity_H2SO4 : approximate NaCl molinity in the H2SO4 titrant
In mol/kg-sol. Defaults to 0.1 mol/kg-sol 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:
pH_min and pH_max : range of pH values to use for solving
Specify the range of pH values from the titration to use to calculate the final alkalinity value.
Added in v23.7 to replace previous pH_range kwarg.
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.
solve_mode : how to solve for alkalinity
The options (which are case-insensitive) are:
"emf"(default): use least-squares fitting for titration data given in EMF in mV."pH": use least-squares fitting for titration data given in pH."pH_adjust": use least-squares fitting for titration data given in pH, but allowing the pH to be adjusted as if its EMF0 was not perfectly calibrated."pH_gran": use a Gran-plot approach for titration data given in pH.
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-sol.