Metadata-Version: 2.4
Name: carbcor
Version: 1.0.1
Summary: Apply Placco et al. (2014) carbon abundance evolutionary corrections.
Project-URL: Homepage, https://github.com/guilimberg/carbcor
Author-email: Guilherme Limberg <limberg@uchicago.edu>, "Vinicius M. Placco" <vinicius.placco@noirlab.edu>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: CEMP,abundance,astronomy,astrophysics,carbon,metal-poor,spectroscopy,stellar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.9
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.4
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: responses>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# 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 2.5k stars.
df = pd.DataFrame({
    "logg": [0.88, -4.82, 0.50], # GDR3_526285  [Limberg, Placco et al. (2025)](https://ui.adsabs.harvard.edu/abs/2025ApJ...989L..18L/abstract)
    "feh":  [1.89, -4.11, 2.20],  # HE 0144-4657 [Placco, Limberg et al. (2026)](https://ui.adsabs.harvard.edu/abs/2026ApJ..1000L..34P/abstract)
    "cfe":  [2.02, -4.06, 1.53],   # GDR3 47959   [Limberg, Placco et al. (2026)] --> submitted
})
df_cor = apply_carbon_corrections(df)
print(df_cor[["cfe", "cfe_corrected", "correction"]])
```

### Command line

```bash
# Query a single star
carbcor query 0.88 -4.82 0.50

# 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
