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 metadata, overview, columns, missing, duplicates, numeric, categorical, outliers, correlations, target, and warnings. print_report() gives each section a title and limits table output to 20 rows, 12 columns, and 40 characters per cell by default. Increase max_rows, max_columns, and max_colwidth when you need more detail.

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. Those correlation controls belong to correlations(); profile() retains the 50 numeric-column limit and the 10,000-row limit for unsampled Kendall. Missing patterns remain exact and untruncated, so the returned table can still be large when many rows have different missing-column combinations.

Numeric statistics exclude infinity separately from missing values. Coefficient of variation is sample standard deviation divided by a positive mean; it is NaN for zero/negative means or fewer than two finite values. Non-applicable IQR analyses return NaN outlier measurements, not a claim of zero outliers. Sampling metadata records actual text parsing: whether any column was sampled and the largest number of values parsed for one column, or zero if none. 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
# Include the one-million-row numeric and missingness cases:
python benchmarks/benchmark_profile.py --large

Development

python -m pip install -e ".[dev,release]"
python -m ruff check .
python -m mypy src/framepeek
python -m pytest --cov=framepeek --cov-branch --cov-fail-under=100
python -m build --outdir dist/check
python -m twine check --strict dist/check/*
python scripts/verify_artifacts.py dist/check

Use a fresh artifact directory for each build. The artifact verifier checks archive contents, installs the wheel and sdist in separate new environments, validates report/serialization schemas, and checks a typed public consumer.