FramePeek

Lightweight exploratory data analysis for pandas DataFrames.

Documentation

• Getting started
• API reference
• Product requirements
• Changelog
• Contributing
• Code of Conduct
• Release guide

Usage

import framepeek as fp

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

fp.print_report(report)

The report contains overview, columns, missing, duplicates, numeric, categorical, outliers, correlations, target, and warnings. print_report() gives each section a title and prints tables without formatter-generated ellipses.

Each analysis is also available directly:

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_column="churn")
fp.quality_warnings(df, target_column="churn")

All functions validate their inputs and leave the original DataFrame unchanged. Object columns containing lists, tuples, dictionaries, sets, frozensets, or NumPy arrays use recursive structural identity for duplicate and categorical analysis. Arrays match when their concrete type, shape, dtype, and nested values match. Other unhashable custom objects use scalar boolean equality; objects whose equality raises or returns a non-scalar result are treated as distinct unless they are the same instance. Cyclic references likewise use instance identity at the cycle boundary.

Outputs

Thresholds for missingness, cardinality, outliers, correlations, and class imbalance can be configured through the corresponding function parameters. Warning text parsing is sampled reproducibly for large columns. Correlation analysis supports column subsets, limits, pair-only output, top pairs, and reproducible row sampling. Serialization schema 1.0 stores DataFrames as explicit index, column, and data arrays. Mappings with non-string keys use entry records so distinct labels cannot overwrite each other; the envelope's exact field identifies lossy fallback display values. warnings() remains available as a compatibility alias. Pass deep_memory=False to overview() or profile() when a shallow memory estimate is sufficient.

Run the bounded runtime and peak-memory smoke benchmarks with:

python benchmarks/benchmark_profile.py

Development

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