carbcor 1.0.0

Apply Placco et al. (2014) carbon abundance evolutionary corrections.

carbcor

Python package to calculate Placco et al. (2014) carbon abundance evolutionary corrections with online tool at vplacco.pythonanywhere.com.

Corrects observed [C/Fe] abundances for the depletion of carbon due to CN processing on the upper red giant branch. Inputs are observed [C/Fe], logg, and [Fe/H].

Installation

pip install carbcor

Quick start

Python API

from carbcor import get_carbon_correction, apply_carbon_corrections
import pandas as pd

# Single star
res = get_carbon_correction(logg=0.88, feh=-4.82, cfe=0.50) # these are the parameters for star GDR3_526285 [Limberg, Placco et al. (2025)](https://ui.adsabs.harvard.edu/abs/2025ApJ...989L..18L/abstract)
print(res["cfe_corrected"])   # corrected [C/Fe]
print(res["correction"])      # correction delta

# Batch from a DataFrame
# You can test for the whole JINAbase [Abohalima & Frebel 2018](https://ui.adsabs.harvard.edu/abs/2018ApJS..238...36A/abstract) following the tests folder.
# Since it parses 1 star at a time, it takes ~10min for each 1k stars.
df = pd.DataFrame({
    "logg": [1.4,  1.5,  3.7],
    "feh":  [-2.7, -3.1, -5.4],
    "cfe":  [0.2,  1.0,  3.0],
})
df_cor = apply_carbon_corrections(df)
print(df_cor[["cfe", "cfe_corrected", "correction"]])

Command line

# Query a single star
carbcor query 1.0 -3.0 1.5

# Process a CSV file
carbcor batch stars.csv -o corrected.csv

# Inspect the web form structure
carbcor discover

Parameter space

The underlying correction grid covers:

Parameter	Range	Step
log(g)	0.0 to 5.0	0.1
[Fe/H]	−5.5 to 0.0	0.1
[C/Fe]	−1.0 to 3.0	0.1

Values outside these ranges are clipped to the nearest grid point.

Custom column names

apply_carbon_corrections(df, logg_col="logg", feh_col="Fe/H", cfe_col="CFe") # example for the JINAbase_2021.csv table

How it works

1. The package carbcor fetches the website HTML and auto-discovers the form structure (action URL, HTTP method, field names).
2. For each star, it submits the parameters and parses the correction delta from the HTML response.
3. Corrected [C/Fe] = input [C/Fe] + correction delta.
4. Missing / NaN inputs produce NaN outputs (standard float('nan'), which is to be compatible with pandas, i.e., you can just plot it afterwards).

Development

git clone https://github.com/guilimberg/carbcor.git
cd carbcor
pip install -e ".[dev]"
pytest

Reference

If you use this tool, you SHOULD cite:

Placco, V.M., Frebel, A., Beers, T.C., & Stancliffe, R.J. 2014, ApJ, 797, 21 (ADS | arXiv:1410.2223)

License

MIT