Metadata-Version: 2.5
Name: shirabe-profiling
Version: 0.2.0
Summary: High-performance Polars data profiling with web reports and quality warnings.
Project-URL: Homepage, https://github.com/shuretokki/shirabe-profiling
Project-URL: Repository, https://github.com/shuretokki/shirabe-profiling
Project-URL: Changelog, https://github.com/shuretokki/shirabe-profiling/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/shuretokki/shirabe-profiling/issues
Author: shuretokki
License-Expression: Apache-2.0 AND OFL-1.1-RFN AND OFL-1.1-no-RFN AND ISC AND MIT
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/ISC.txt
License-File: LICENSES/MIT.txt
License-File: LICENSES/OFL-1.1-RFN.txt
License-File: LICENSES/OFL-1.1-no-RFN.txt
License-File: REUSE.toml
Keywords: data-profiling,data-quality,eda,exploratory-data-analysis,pandas-profiling,polars,profiling,ydata-profiling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: numpy>=1.22.4
Requires-Dist: phik>=0.12
Requires-Dist: polars-statistics>=0.4
Requires-Dist: polars>=1.0
Requires-Dist: scipy>=1.12
Provides-Extra: pandas
Requires-Dist: pandas; extra == 'pandas'
Requires-Dist: polars[pyarrow]; extra == 'pandas'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: Copyright © 2026 shuretokki
SPDX-License-Identifier: Apache-2.0
-->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/logo/wordmark-on-dark.svg">
    <img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/logo/wordmark-on-light.svg" alt="shirabe" width="240">
  </picture>
</p>

<h1 align="center">shirabe-profiling</h1>

<p align="center">
A fast, Polars-native data profiling tool that generates interactive HTML reports equipped with automated data quality alerts to streamline your exploratory data analysis.
</p>

<p align="center">
  <a href="https://github.com/shuretokki/shirabe-profiling/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache 2.0"></a>
  <a href="https://github.com/shuretokki/shirabe-profiling"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
</p>

<p align="center">
  <a href="#quickstart">Quickstart</a> |
  <a href="#report-tour">Report tour</a> |
  <a href="#use-it-in-code">Use it in code</a> |
  <a href="#license">License</a>
</p>

<p align="center">
  <a href="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-overview.webp">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-overview-dark.webp">
      <img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-overview.webp" alt="The overview of a report, with the facts of the dataset and the list of alerts" width="880">
    </picture>
  </a>
</p>

shirabe-profiling reads a Polars DataFrame and writes one HTML report that you open in a browser.
The report shows the facts of each column, flags quality problems as alerts, and explains how to fix each alert.

- **Fast,** the engine is Polars, and overview mode skips the slow parts for a quick first look. See the [benchmarks](https://github.com/shuretokki/shirabe-profiling/tree/main/benchmarks/README.md).
- **A guide for every alert,** the Guide tab covers all 12 alerts, with each limit, and with some possible fixes and the sources for most of them.
- **Made for modeling,** the target section shows how columns link to the target and warns about leakage, and skewed columns get `log1p` and Yeo-Johnson tabs.
- **Easy to use in code,** read the numbers with `.to_dict()`, `.to_json()`, `.stats`, and `.alerts`, and the package is fully typed.
- **Easy on the eyes,** the report follows the theme of your system, and you can switch between dark and light in the settings menu.
- **Open to many inputs,** Polars frames, pandas frames, CSV paths, and Parquet paths all work.

## Quickstart

Install the package from PyPI:

```bash
pip install shirabe-profiling
```

With uv, run `uv add shirabe-profiling` in a project, or `uv pip install shirabe-profiling` in a virtual environment.

For pandas tables with text columns, install the extra: `pip install "shirabe-profiling[pandas]"`.

Then write a report:

```python
import polars as pl
from shirabe_profiling import ProfileReport

df = pl.read_csv("data.csv")
report = ProfileReport(df)
report.to_html("report.html")
```

You can name the column that you want to predict to add a target section:

```python
report = ProfileReport(df, target="price")
```

The report loads ECharts and Tailwind CSS from a CDN, so it needs an internet connection to display correctly.

## Report tour

Click any picture to open it full size.

| Target |
|:--|
| <a href="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-target.webp"><img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-target.webp" alt="Target section with the link of each column to the target" width="100%"></a> |

| Column details |
|:--|
| <a href="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-columns.webp"><img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-columns.webp" alt="Column details with alert tags and skew tabs" width="100%"></a> |

| Correlations |
|:--|
| <a href="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-correlations.webp"><img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-correlations.webp" alt="Correlation heatmap with the strongest pairs" width="100%"></a> |

| Guide |
|:--|
| <a href="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-guide.webp"><img src="https://raw.githubusercontent.com/shuretokki/shirabe-profiling/main/assets/screenshots/report-guide.webp" alt="The Guide tab with the High Missing alert open" width="100%"></a> |

The report also has:

- A correlation heatmap for each method (Phik, Pearson, Spearman, Cramér's V, and Kendall), with a list of the strongest pairs.
- An Interactions section with scatter plots, box plots, and a column picker.
- A Missing Patterns table and an Outliers table.
- A Sample section with the first rows, the last rows, random rows, and the rows with the most gaps.

## Use it in code

<details>
<summary>Read the results</summary>

```python
report = ProfileReport(df, title="Home Prices Profile")

stats = report.to_dict()
alerts = report.alerts
column_stats = report.stats["area_m2"]
correlations = report.correlations
```

</details>

<details>
<summary>Change the settings</summary>

```python
from shirabe_profiling import ProfileReport, ProfileConfig

config = ProfileConfig(
    title="Home Prices Profile",
    mode="overview",
    missing_threshold=0.1,
    histogram_bins=30,
)
report = ProfileReport(df, config=config)
```

</details>

<details>
<summary>Pick a mode</summary>

Use `"overview"` when you want a fast first look, because it skips the slow parts of the report.

| Feature | `"complete"` | `"overview"` |
|---|:-:|:-:|
| Basic stats | ✓ | ✓ |
| Histograms and value counts | ✓ | ✓ |
| Correlations | ✓ | ✗ |
| Interactions | ✓ | ✗ |
| Skew transform tabs | ✓ | ✗ |
| Missing patterns and outliers tables | ✓ | ✗ |
| Random and most missing samples | ✓ | ✗ |
| Character analysis | ✓ | ✗ |
| Duplicate rows table | ✓ | ✗ |

</details>

<details>
<summary>Choose an output format</summary>

| Format | Method | Use |
|---|---|---|
| HTML | `report.to_html("report.html")` | The interactive report |
| JSON | `report.to_json("report.json")` | Other programs |
| Dict | `report.to_dict()` | Python code |

</details>

## License

This project is a derivative work based on [dataxid-profiling](https://github.com/dataxid/dataxid-profiling) by DataXID, originally licensed under the Apache License 2.0.

- [LICENSE](https://github.com/shuretokki/shirabe-profiling/tree/main/LICENSE), the Apache-2.0 grant for the whole repository
- [LICENSES/](https://github.com/shuretokki/shirabe-profiling/tree/main/LICENSES), the full text of each license that the files use
- [REUSE.toml](https://github.com/shuretokki/shirabe-profiling/tree/main/REUSE.toml), the license and the copyright holder of each file
