# carbcor

[![PyPI](https://img.shields.io/pypi/v/carbcor)](https://pypi.org/project/carbcor/)
[![Python](https://img.shields.io/pypi/pyversions/carbcor)](https://pypi.org/project/carbcor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python package to calculate [Placco et al. (2014)](https://ui.adsabs.harvard.edu/abs/2014ApJ...797...21P) carbon abundance evolutionary corrections with online tool at [vplacco.pythonanywhere.com](https://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

```bash
pip install carbcor
```

## Quick start

### Python API

```python
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

```bash
# 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

```python
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

```bash
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](https://ui.adsabs.harvard.edu/abs/2014ApJ...797...21P) | [arXiv:1410.2223](https://arxiv.org/abs/1410.2223))

## License

MIT
