<div align="right">
<a href="https://github.com/oscarbranson/cbsyst/actions"><img src="https://github.com/oscarbranson/cbsyst/actions/workflows/tests.yml/badge.svg" alt="GHA" height="18"></a>
<a href="https://badge.fury.io/py/cbsyst"><img src="https://badge.fury.io/py/cbsyst.svg" alt="PyPI version" height="18"></a>
<a href="https://anaconda.org/conda-forge/cbsyst"> <img src="https://anaconda.org/conda-forge/cbsyst/badges/version.svg" alt="conda-forge version" height="18"/></a>
<a href="https://doi.org/10.5281/zenodo.1402261"> <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.1402261.svg" alt="DOI" height="18"></a>
</div>
<div align="left">
<img src="https://raw.githubusercontent.com/oscarbranson/cbsyst/master/logo/cbsyst.png" alt="CBsyst" height="96">
</div>
**A Python module for calculating seawater carbon and boron chemistry.**
This will be particularly useful for anyone thinking about oceans in the distant past, when Mg and Ca concentrations were different. I use [Mathis Hain's MyAMI model](http://www.mathis-hain.net/resources/Hain_et_al_2015_GBC.pdf) to adjust speciation constants for Mg and Ca concentration.
***Tested** in the modern ocean against GLODAPv2 data (see below). Performs as well as Matlab CO2SYS.*
## Work in Progress:
- [ ] [Compare to CO2SYS](https://github.com/oscarbranson/cbsyst/issues/6), a la [Orr et al (2015)](http://www.biogeosciences.net/12/1483/2015/bg-12-1483-2015.pdf)?
If anyone wants to help with any of this, please do contribute!
A full list of bite-sized tasks that need doing is available on the [Issues](https://github.com/oscarbranson/cbsyst/issues) page.
## Acknowledgement
The development of `cbsyst` has been greatly aided by [CO2SYS](http://cdiac.ornl.gov/oceans/co2rprt.html), and the [Matlab conversion of CO2SYS](http://cdiac.ornl.gov/ftp/oceans/co2sys/).
In particular, these programs represent a gargantuan effort to find the most appropriate coefficient formulations and parameterisations from typo-prone literature.
CO2SYS has also provided an invaluable benchmark throughout development.
## Data Comparison
I have used the [GLODAPv2 data set](cbsyst/test_data/GLODAP_data/Olsen_et_al-2016_GLODAPv2.pdf) to test how well `cbsyst` works with modern seawater.
### Method:
Import the entire GLODAPv2 data set, remove all data where `flag != 2` (2 = good data), and exclude all rows that don't have all of (salinity, temperature, pressure, tco2, talk, phosphate, silicate and phtsinsitutp) - i.e. salinity, temperature, pressure, nutrients and all three measured carbonate parameters.
The resulting dataset contains 79,896 bottle samples.
The code used to process the raw GLODAPv2 data is available [here](cbsyst/test_data/GLODAP_data/get_GLODAP_data.py).
Next, calculate the carbonate system from sets of two of the measured carbonate parameters, and compare the calculated third parameter to the measured third parameter (i.e. calculate Alkalinity from pH and DIC, then compared calculated vs. measured Alkalinities). The code for making these comparison plots is [here](cbsyst/test_data/GLODAP_data/plot_GLODAPv2_comparison.py).
### Results:
**Calculated pH** (from DIC and Alkalinity) is offset from measured values by -0.00061 (-0.029/+0.029).
**Calculated Alkalinity** (from pH and DIC) is offset from measured values by 0.23 (-12/+11) umol/kg.
**Calculated DIC** (from pH and Alkalinity) is offset from measured values by -0.22 (-11/+11) umol/kg.
Reported statistics are median ±95% confidence intervals extracted from the residuals (n = 79,896).
Data are idential to within rouding errors as values calculated by Matlab CO2SYS (v1.1).
### Conclusions:
`cbsyst` does a good job of fitting the GLODAPv2 dataset!
## Technical Details
### Constants
Constants calculated by an adaptation of [Mathis Hain's MyAMI model](http://www.mathis-hain.net/resources/Hain_et_al_2015_GBC.pdf).
The [original MyAMI code](https://github.com/MathisHain/MyAMI) is available on GitHub.
A stripped-down version of MyAMI is [packaged with cbsyst](cbsyst/MyAMI_V2.py).
It has been modified to make it faster (by vectorising) and more 'Pythonic'.
All the Matlab interface code has been removed.
Constants not provided by MyAMI (KP1, KP2, KP3, KSi, KF) are formulated following [Dickson, Sabine & Christian's (2007) 'Guide to best practices for ocean CO<sub>2</sub> measurements.'](http://cdiac.ornl.gov/oceans/Handbook_2007.html).
Pressure corrections are applied to the calculated constants following Eqns. 38-40 of [Millero et al (2007)](cbsyst/docs/Millero_2007_ChemicalReview.pdf), using (typo-corrected) constants in their Table 5.
All constants are on the pH Total scale.
### Calculations
Speciation calculations follow [Zeebe and Wolf-Gladrow (2001)](https://www.elsevier.com/books/co2-in-seawater-equilibrium-kinetics-isotopes/zeebe/978-0-444-50946-8).
Carbon speciation calculations are described in Appendix B, except where Alkalinity is involved, in which cases the formulations of [Ernie Lewis' CO2SYS](http://cdiac.ornl.gov/oceans/co2rprt.html) are used.
Boron speciation calculations in Eqns. 3.4.43 - 3.4.46.
Boron isotopes are calculated in terms of fractional abundances instead of delta values, as outlines [here](cbsyst/docs/B_systematics.pdf).
Delta values can be provided as an input, and are given as an output.
# Installation
**Requires Python 3.5+**.
Does *not* work in 2.7. Sorry.
### PyPi
```bash
pip install cbsyst
```
### Conda-Forge
```bash
conda install cbsyst -c conda-forge
```
## Example Usage
```python
import cbsyst as cb
import numpy as np
# Create pH master variable for demo
pH = np.linspace(7,11,100) # pH on Total scale
# Example Usage
# -------------
# The following functions can be used to calculate the
# speciation of C and B in seawater, and the isotope
# fractionation of B, given minimal input parameters.
#
# See the docstring for each function for info on
# required minimal parameters.
# Carbon system only
Csw = cb.Csys(pHtot=pH, DIC=2000.)
# Boron system only
Bsw = cb.Bsys(pHtot=pH, BT=433., dBT=39.5)
# Carbon and Boron systems
CBsw = cb.CBsys(pHtot=pH, DIC=2000., BT=433., dBT=39.5)
# NOTE:
# At present, each function call can only be used to
# calculate a single minimal-parameter combination -
# i.e. you can't pass it multiple arrays of parameters
# with different combinations of parameters, as in
# the Matlab CO2SYS code.
# Example Output
# --------------
# The functions return a Bunch (modified dict with '.'
# attribute access) containing all system parameters
# and constants.
#
# Output for a single input condition shown for clarity:
out = cb.CBsys(pHtot=8.1, DIC=2000., BT=433., dBT=39.5)
out
>>> {'ABO3': array([ 0.80882931]),
'ABO4': array([ 0.80463763]),
'ABT': array([ 0.80781778]),
'BO3': array([ 328.50895695]),
'BO4': array([ 104.49104305]),
'BT': array([ 433.]),
'CO2': array([ 9.7861814]),
'CO3': array([ 238.511253]),
'Ca': array([ 0.0102821]),
'DIC': array([ 2000.]),
'H': array([ 7.94328235e-09]),
'HCO3': array([ 1751.7025656]),
'Ks': {'K0': array([ 0.02839188]),
'K1': array([ 1.42182814e-06]),
'K2': array([ 1.08155475e-09]),
'KB': array([ 2.52657299e-09]),
'KS': array([ 0.10030207]),
'KW': array([ 6.06386369e-14]),
'KspA': array([ 6.48175907e-07]),
'KspC': array([ 4.27235093e-07])},
'Mg': array([ 0.0528171]),
'S': array([ 35.]),
'T': array([ 25.]),
'TA': array([ 2333.21612227]),
'alphaB': array([ 1.02725]),
'dBO3': array([ 46.30877684]),
'dBO4': array([ 18.55320208]),
'dBT': array([ 39.5]),
'deltas': True,
'fCO2': array([ 344.68238018]),
'pCO2': array([ 345.78871573]),
'pHtot': array([ 8.1]),
'pdict': None}
# All of the calculated output arrays will be the same length as the longest
# input array.
# Access individual parameters by:
out.CO3
>>> array([ 238.511253])
# Output data for external use:
df = cb.data_out(out, 'example_export.csv')
# This returns a pandas.DataFrame object with all C and B parameters.
# It also saves the data to the specified file. The extension of the
# file determined the format it is saved in (see data_out docstring).
```
## Technical Note: Whats is a `Bunch`?
For code readability and convenience, I've used Bunch objects instead of traditional dicts.
A [Bunch](cbsyst/helpers.py#L6) is a modification of a dict, which allows attribute access via the dot (.) operator.
Apart from that, it works *exactly* like a normal dict (all the usual methods are available transparrently).
**Example:**
```python
from cbsyst.helpers import Bunch
# Make a bunch
bun = Bunch({'a': 1,
'b': 2})
# Access items of bunch...
# as a dict:
bun['a']
>>> 1
# as a Bunch:
bun.a
>>> 1
```
Raw data
{
"_id": null,
"home_page": "https://github.com/oscarbranson/cbsyst",
"name": "cbsyst",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "science,chemistry,oceanography,carbon",
"author": "Oscar Branson",
"author_email": "ob266@cam.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/ed/2e/221d7b8d2721dd0f63ef34832c925eb4f0f1b2cefa10aa07ffdeeebd94f4/cbsyst-0.4.9.tar.gz",
"platform": null,
"description": "<div align=\"right\">\n <a href=\"https://github.com/oscarbranson/cbsyst/actions\"><img src=\"https://github.com/oscarbranson/cbsyst/actions/workflows/tests.yml/badge.svg\" alt=\"GHA\" height=\"18\"></a>\n <a href=\"https://badge.fury.io/py/cbsyst\"><img src=\"https://badge.fury.io/py/cbsyst.svg\" alt=\"PyPI version\" height=\"18\"></a>\n <a href=\"https://anaconda.org/conda-forge/cbsyst\"> <img src=\"https://anaconda.org/conda-forge/cbsyst/badges/version.svg\" alt=\"conda-forge version\" height=\"18\"/></a>\n <a href=\"https://doi.org/10.5281/zenodo.1402261\"> <img src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.1402261.svg\" alt=\"DOI\" height=\"18\"></a>\n</div>\n\n<div align=\"left\">\n <img src=\"https://raw.githubusercontent.com/oscarbranson/cbsyst/master/logo/cbsyst.png\" alt=\"CBsyst\" height=\"96\">\n</div>\n\n**A Python module for calculating seawater carbon and boron chemistry.** \n\nThis will be particularly useful for anyone thinking about oceans in the distant past, when Mg and Ca concentrations were different. I use [Mathis Hain's MyAMI model](http://www.mathis-hain.net/resources/Hain_et_al_2015_GBC.pdf) to adjust speciation constants for Mg and Ca concentration.\n\n***Tested** in the modern ocean against GLODAPv2 data (see below). Performs as well as Matlab CO2SYS.*\n\n## Work in Progress:\n- [ ] [Compare to CO2SYS](https://github.com/oscarbranson/cbsyst/issues/6), a la [Orr et al (2015)](http://www.biogeosciences.net/12/1483/2015/bg-12-1483-2015.pdf)?\n\nIf anyone wants to help with any of this, please do contribute!\nA full list of bite-sized tasks that need doing is available on the [Issues](https://github.com/oscarbranson/cbsyst/issues) page.\n\n## Acknowledgement\nThe development of `cbsyst` has been greatly aided by [CO2SYS](http://cdiac.ornl.gov/oceans/co2rprt.html), and the [Matlab conversion of CO2SYS](http://cdiac.ornl.gov/ftp/oceans/co2sys/).\nIn particular, these programs represent a gargantuan effort to find the most appropriate coefficient formulations and parameterisations from typo-prone literature.\nCO2SYS has also provided an invaluable benchmark throughout development.\n\n## Data Comparison\nI have used the [GLODAPv2 data set](cbsyst/test_data/GLODAP_data/Olsen_et_al-2016_GLODAPv2.pdf) to test how well `cbsyst` works with modern seawater.\n\n### Method:\nImport the entire GLODAPv2 data set, remove all data where `flag != 2` (2 = good data), and exclude all rows that don't have all of (salinity, temperature, pressure, tco2, talk, phosphate, silicate and phtsinsitutp) - i.e. salinity, temperature, pressure, nutrients and all three measured carbonate parameters.\nThe resulting dataset contains 79,896 bottle samples. \nThe code used to process the raw GLODAPv2 data is available [here](cbsyst/test_data/GLODAP_data/get_GLODAP_data.py).\n\nNext, calculate the carbonate system from sets of two of the measured carbonate parameters, and compare the calculated third parameter to the measured third parameter (i.e. calculate Alkalinity from pH and DIC, then compared calculated vs. measured Alkalinities). The code for making these comparison plots is [here](cbsyst/test_data/GLODAP_data/plot_GLODAPv2_comparison.py).\n\n### Results:\n**Calculated pH** (from DIC and Alkalinity) is offset from measured values by -0.00061 (-0.029/+0.029).\n\n\n**Calculated Alkalinity** (from pH and DIC) is offset from measured values by 0.23 (-12/+11) umol/kg.\n\n\n**Calculated DIC** (from pH and Alkalinity) is offset from measured values by -0.22 (-11/+11) umol/kg.\n\n\nReported statistics are median \u00b195% confidence intervals extracted from the residuals (n = 79,896).\n\nData are idential to within rouding errors as values calculated by Matlab CO2SYS (v1.1).\n\n### Conclusions:\n`cbsyst` does a good job of fitting the GLODAPv2 dataset!\n\n## Technical Details\n### Constants\nConstants calculated by an adaptation of [Mathis Hain's MyAMI model](http://www.mathis-hain.net/resources/Hain_et_al_2015_GBC.pdf). \nThe [original MyAMI code](https://github.com/MathisHain/MyAMI) is available on GitHub.\nA stripped-down version of MyAMI is [packaged with cbsyst](cbsyst/MyAMI_V2.py).\nIt has been modified to make it faster (by vectorising) and more 'Pythonic'.\nAll the Matlab interface code has been removed.\n\nConstants not provided by MyAMI (KP1, KP2, KP3, KSi, KF) are formulated following [Dickson, Sabine & Christian's (2007) 'Guide to best practices for ocean CO<sub>2</sub> measurements.'](http://cdiac.ornl.gov/oceans/Handbook_2007.html).\n\nPressure corrections are applied to the calculated constants following Eqns. 38-40 of [Millero et al (2007)](cbsyst/docs/Millero_2007_ChemicalReview.pdf), using (typo-corrected) constants in their Table 5.\nAll constants are on the pH Total scale.\n\n### Calculations\nSpeciation calculations follow [Zeebe and Wolf-Gladrow (2001)](https://www.elsevier.com/books/co2-in-seawater-equilibrium-kinetics-isotopes/zeebe/978-0-444-50946-8).\nCarbon speciation calculations are described in Appendix B, except where Alkalinity is involved, in which cases the formulations of [Ernie Lewis' CO2SYS](http://cdiac.ornl.gov/oceans/co2rprt.html) are used.\nBoron speciation calculations in Eqns. 3.4.43 - 3.4.46.\n\nBoron isotopes are calculated in terms of fractional abundances instead of delta values, as outlines [here](cbsyst/docs/B_systematics.pdf).\nDelta values can be provided as an input, and are given as an output.\n\n\n# Installation\n\n**Requires Python 3.5+**. \nDoes *not* work in 2.7. Sorry.\n\n### PyPi\n```bash\npip install cbsyst\n```\n\n### Conda-Forge\n```bash\nconda install cbsyst -c conda-forge\n```\n\n## Example Usage\n\n```python\nimport cbsyst as cb\nimport numpy as np\n\n# Create pH master variable for demo\npH = np.linspace(7,11,100) # pH on Total scale\n\n# Example Usage\n# -------------\n# The following functions can be used to calculate the\n# speciation of C and B in seawater, and the isotope\n# fractionation of B, given minimal input parameters.\n#\n# See the docstring for each function for info on\n# required minimal parameters.\n\n# Carbon system only\nCsw = cb.Csys(pHtot=pH, DIC=2000.)\n\n# Boron system only\nBsw = cb.Bsys(pHtot=pH, BT=433., dBT=39.5)\n\n# Carbon and Boron systems\nCBsw = cb.CBsys(pHtot=pH, DIC=2000., BT=433., dBT=39.5)\n\n# NOTE:\n# At present, each function call can only be used to\n# calculate a single minimal-parameter combination -\n# i.e. you can't pass it multiple arrays of parameters\n# with different combinations of parameters, as in\n# the Matlab CO2SYS code.\n\n# Example Output\n# --------------\n# The functions return a Bunch (modified dict with '.' \n# attribute access) containing all system parameters\n# and constants.\n#\n# Output for a single input condition shown for clarity:\n\nout = cb.CBsys(pHtot=8.1, DIC=2000., BT=433., dBT=39.5)\nout\n\n>>> {'ABO3': array([ 0.80882931]),\n 'ABO4': array([ 0.80463763]),\n 'ABT': array([ 0.80781778]),\n 'BO3': array([ 328.50895695]),\n 'BO4': array([ 104.49104305]),\n 'BT': array([ 433.]),\n 'CO2': array([ 9.7861814]),\n 'CO3': array([ 238.511253]),\n 'Ca': array([ 0.0102821]),\n 'DIC': array([ 2000.]),\n 'H': array([ 7.94328235e-09]),\n 'HCO3': array([ 1751.7025656]),\n 'Ks': {'K0': array([ 0.02839188]),\n 'K1': array([ 1.42182814e-06]),\n 'K2': array([ 1.08155475e-09]),\n 'KB': array([ 2.52657299e-09]),\n 'KS': array([ 0.10030207]),\n 'KW': array([ 6.06386369e-14]),\n 'KspA': array([ 6.48175907e-07]),\n 'KspC': array([ 4.27235093e-07])},\n 'Mg': array([ 0.0528171]),\n 'S': array([ 35.]),\n 'T': array([ 25.]),\n 'TA': array([ 2333.21612227]),\n 'alphaB': array([ 1.02725]),\n 'dBO3': array([ 46.30877684]),\n 'dBO4': array([ 18.55320208]),\n 'dBT': array([ 39.5]),\n 'deltas': True,\n 'fCO2': array([ 344.68238018]),\n 'pCO2': array([ 345.78871573]),\n 'pHtot': array([ 8.1]),\n 'pdict': None}\n\n# All of the calculated output arrays will be the same length as the longest\n# input array.\n\n# Access individual parameters by:\nout.CO3\n\n>>> array([ 238.511253])\n\n# Output data for external use:\ndf = cb.data_out(out, 'example_export.csv')\n\n# This returns a pandas.DataFrame object with all C and B parameters.\n# It also saves the data to the specified file. The extension of the\n# file determined the format it is saved in (see data_out docstring).\n\n```\n\n## Technical Note: Whats is a `Bunch`?\n\nFor code readability and convenience, I've used Bunch objects instead of traditional dicts.\nA [Bunch](cbsyst/helpers.py#L6) is a modification of a dict, which allows attribute access via the dot (.) operator.\nApart from that, it works *exactly* like a normal dict (all the usual methods are available transparrently).\n\n**Example:**\n```python\nfrom cbsyst.helpers import Bunch\n\n# Make a bunch\nbun = Bunch({'a': 1,\n 'b': 2})\n\n# Access items of bunch...\n# as a dict:\nbun['a']\n\n>>> 1\n\n# as a Bunch:\nbun.a\n\n>>> 1\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tools for calculating ocean C and B chemistry.",
"version": "0.4.9",
"project_urls": {
"Homepage": "https://github.com/oscarbranson/cbsyst"
},
"split_keywords": [
"science",
"chemistry",
"oceanography",
"carbon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e7f2a14f7dbe0cced5d2bbec9383233720fa45382108b7a831853cd248d0fbe4",
"md5": "58fac67045864afa04ad7474315de5d0",
"sha256": "91a3780538b335b831c918a7885a57e3792b8210ee2b100b9b35e4b4b0c96d23"
},
"downloads": -1,
"filename": "cbsyst-0.4.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58fac67045864afa04ad7474315de5d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9000162,
"upload_time": "2024-02-29T18:14:21",
"upload_time_iso_8601": "2024-02-29T18:14:21.839700Z",
"url": "https://files.pythonhosted.org/packages/e7/f2/a14f7dbe0cced5d2bbec9383233720fa45382108b7a831853cd248d0fbe4/cbsyst-0.4.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed2e221d7b8d2721dd0f63ef34832c925eb4f0f1b2cefa10aa07ffdeeebd94f4",
"md5": "4e134ac1aecd95152cab6a840d794cdd",
"sha256": "19548a57a0b3641f97a81959af24776bfb8b11f0da55d3164c3ffcfac12379c2"
},
"downloads": -1,
"filename": "cbsyst-0.4.9.tar.gz",
"has_sig": false,
"md5_digest": "4e134ac1aecd95152cab6a840d794cdd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8991254,
"upload_time": "2024-02-29T18:14:25",
"upload_time_iso_8601": "2024-02-29T18:14:25.107911Z",
"url": "https://files.pythonhosted.org/packages/ed/2e/221d7b8d2721dd0f63ef34832c925eb4f0f1b2cefa10aa07ffdeeebd94f4/cbsyst-0.4.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-29 18:14:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oscarbranson",
"github_project": "cbsyst",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cbsyst"
}
JSON
