mlreadyscore 0.1.0

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

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

Check	What It Catches
Dataset Size	Too few rows, too many columns, curse of dimensionality
Missing Values	Null/NaN values per column with severity rating
Duplicate Rows	Exact duplicate rows that can bias your model
Data Types	Numbers stored as text, dates as strings, mixed types
Outliers	Extreme values using IQR method
Multicollinearity	Highly correlated features (>0.85)
Class Imbalance	Skewed target distribution for classification
Constant Features	Zero-variance columns that add no information
High Cardinality	Categorical columns with too many unique values

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