Metadata-Version: 2.4
Name: pandas-characteristic
Version: 0.1.0
Summary: Characteristic cells of weighted pandas distributions
Author: Nicolas Graves
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: pytest>=7 ; extra == "dev"
Requires-Dist: scipy ; extra == "dev"
Project-URL: Repository, https://github.com/nicolas-graves/pandas-characteristic
Provides-Extra: dev

# pandas-characteristic

`pandas-characteristic` identifies characteristic cells of weighted conditional
distributions. It has one runtime dependency: pandas.

```python
import pandas_characteristic

result = df.characteristic.rule(
    distribution="occupation",
    given="sector",
    within="region",
    weight="employment",
    min_share=0.02,
    min_ratio=1.0,
)
```

For every observed cell, the rule returns its mass, conditional share,
distribution baseline, expected mass under conditional independence, and the
observed/expected ratio:

```text
conditional_share       = P(distribution | given, within)
baseline_share          = P(distribution | within)
observed_expected_ratio = conditional_share / baseline_share
```

`selected` uses strict comparisons by default. Pass `strict=False` for inclusive
thresholds or `selected_only=True` to return only matching cells. Column lists
are accepted for `distribution`, `given`, and `within`.

The core function is also directly composable with `DataFrame.pipe`:

```python
from pandas_characteristic import characteristic_cells

result = df.pipe(
    characteristic_cells,
    distribution="occupation",
    given="sector",
    within="region",
    weight="employment",
    min_share=0.02,
    min_ratio=1.0,
)
```

