Metadata-Version: 2.4
Name: framepeek
Version: 0.1.0
Summary: Lightweight exploratory data analysis for pandas DataFrames
Author: Sal
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pandas-stubs>=2.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.0; extra == "release"
Dynamic: license-file

# FramePeek

Lightweight exploratory data analysis for pandas DataFrames.

## Documentation

- [Getting started](https://github.com/Salajalaludin/framepeek/blob/main/docs/getting-started.md)
- [API reference](https://github.com/Salajalaludin/framepeek/blob/main/docs/api-reference.md)
- [Product requirements](https://github.com/Salajalaludin/framepeek/blob/main/docs/PRD.md)
- [Changelog](https://github.com/Salajalaludin/framepeek/blob/main/CHANGELOG.md)
- [Contributing](https://github.com/Salajalaludin/framepeek/blob/main/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/Salajalaludin/framepeek/blob/main/CODE_OF_CONDUCT.md)
- [Release guide](https://github.com/Salajalaludin/framepeek/blob/main/docs/releasing.md)

## Usage

```python
import framepeek as fp

report = fp.profile(
    df,
    target="churn",
    correlation_method="spearman",
    outlier_multiplier=1.5,
    top_n_categories=5,
)
```

The report contains `overview`, `columns`, `missing`, `duplicates`, `numeric`,
`categorical`, `outliers`, `correlations`, `target`, and `warnings`.

Each analysis is also available directly:

```python
fp.overview(df)
fp.columns(df)
fp.missing(df)
fp.duplicates(df)
fp.numeric(df)
fp.categorical(df)
fp.outliers(df)
fp.correlations(df)
fp.target(df, target="churn")
fp.warnings(df, target="churn")
```

All functions validate their inputs and leave the original DataFrame unchanged.

## Outputs

| Function | Return value |
| --- | --- |
| `overview` | `DataFrame` of dataset-level metrics |
| `columns` | `DataFrame` with one profile row per column |
| `missing` | `DataFrame`; row totals are stored in `.attrs["rows"]` |
| `duplicates` | Dictionary containing totals, groups, and examples |
| `numeric` | `DataFrame` of descriptive numeric statistics |
| `categorical` | `DataFrame` of frequency and cardinality statistics |
| `outliers` | `DataFrame` of IQR bounds and potential outlier counts |
| `correlations` | Dictionary containing `matrix` and tidy `pairs` tables |
| `target` | Dictionary containing categorical or numeric target analysis |
| `warnings` | `DataFrame` of actionable quality warnings |
| `profile` | Dictionary containing all analyses above |

Thresholds for missingness, cardinality, outliers, correlations, and class
imbalance can be configured through the corresponding function parameters.

## Development

```bash
python -m pip install -e ".[dev]"
python -m ruff check .
python -m mypy src/framepeek
python -m pytest --cov=framepeek --cov-fail-under=100
```
