mlreadyscore

Give any dataset an ML-readiness score from 0–100 with actionable suggestions.

Stop guessing if your data is ready for Machine Learning. mlreadyscore analyzes your dataset and gives you a clear score, issues list, and fix suggestions — all in one line of code.

Installation

pip install mlreadyscore

Quick Start

from mlreadyscore import check

# From a CSV file
report = check("my_data.csv")
print(report)

# From a DataFrame
import pandas as pd
df = pd.read_csv("sales.csv")
report = check(df, target="revenue")
print(report.score)       # 72.5
print(report.grade)       # B-
print(report.suggestions) # ['DROP column X...', 'IMPUTE column Y...']

Output

============================================================
   ML READINESS REPORT
============================================================
   Dataset:  5000 rows × 12 columns
   Score:    72.5 / 100  (B-)
------------------------------------------------------------

   CHECK SCORES:
   --------------------------------------------
   Dataset Size             [###############]  100.0
   Missing Values           [##########.....]   68.3
   Duplicate Rows           [###############]  100.0
   Data Types               [############...]   85.0
   Outliers                 [##########.....]   70.2
   Multicollinearity        [#########......]   60.0
   Class Imbalance          [########.......]   55.0
   Constant Features        [###############]  100.0
   High Cardinality         [############...]   82.0

   ISSUES FOUND (5):
   --------------------------------------------
    1. 'address' has 42.3% missing — significant gaps
    2. 'price' has 8.2% outliers
    3. 'area' & 'sqft' have 0.97 correlation — near identical
    4. Moderate imbalance: minority/majority ratio = 0.25
    5. 'zipcode' has 847 unique values — high cardinality

   SUGGESTIONS (5):
   --------------------------------------------
    1. IMPUTE 'address' with median/mode
    2. CLIP or TRANSFORM 'price' (log transform or winsorize)
    3. DROP one of 'area' or 'sqft'
    4. TRY class_weight='balanced' or stratified sampling
    5. REDUCE 'zipcode' cardinality with grouping

   --------------------------------------------
   VERDICT: Needs work. Address the suggestions before training.
============================================================

What It Checks

Supported File Formats

• .csv — CSV files
• .tsv — Tab-separated files
• .xlsx / .xls — Excel files (requires pip install mlreadyscore[excel])
• .json — JSON files
• .parquet — Parquet files (requires pip install mlreadyscore[parquet])

API Reference

check(data, target=None)

Main function. Accepts a file path or DataFrame.

report = check("data.csv")
report = check(df, target="label")

ReadinessReport

The returned report object:

report.score        # float: 0-100
report.grade        # str: "A+" to "F"
report.issues       # list[str]: all issues found
report.suggestions  # list[str]: actionable fixes
report.checks       # list[dict]: individual check results
report.summary      # str: one-line verdict

report.to_dict()    # export as dictionary
report.to_json()    # export as JSON string
report.save("report.json")  # save to file

Individual Checks

Run specific checks independently:

from mlreadyscore import check_missing, check_outliers, check_imbalance

result = check_missing(df)
print(result["score"])      # 85.0
print(result["issues"])     # ["'age' has 12.3% missing"]
print(result["suggestions"])  # ["IMPUTE 'age' with mean/median/mode"]

Use Cases

• Before training: Run check() to catch problems early
• In CI/CD pipelines: Automate data validation with score thresholds
• Teaching/learning: Understand what makes data ML-ready
• Data handoff: Share reports with teammates when passing datasets

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

git clone https://github.com/yourusername/mlreadyscore.git
cd mlreadyscore
pip install -e ".[dev]"
pytest

License

MIT