firstlook

Drop in any dataframe and get models worth trying plus the right charts. The first look you take at any dataset, done for you.

import firstlook
firstlook.at(df, target="species")

One call and you get three things back:

1. The problem type: regression, classification, or clustering, inferred from the data.
2. Models to try: ranked, with a one-line reason each, plus data-aware warnings (class imbalance, categoricals that need encoding, missing values, too few rows).
3. The right charts: a dark, interactive Plotly dashboard that picks the chart per column: bar/histogram for the target, a scatter colored by class (or feature-vs-target for regression), a correlation heatmap, and a closer look.

It works in Jupyter (rich card + interactive charts render inline) and in plain scripts (prints the recommendation; report.to_html("out.html") for the visuals).

See it on real data: examples/ runs the full understand → visualize → model arc on three datasets — breast cancer, diabetes, and a messy churn set — with the dashboards rendered.

Why

Every project starts the same way: load the data, squint at it, remember which chart goes with which column, half-remember the sklearn cheat-sheet. firstlook does that opening move for you so you can get to the actual modeling without writing a wall of matplotlib.

Install

pip install firstlook

From source, for development:

git clone https://github.com/siddhant-rajhans/firstlook
cd firstlook
pip install -e ".[dev]"

Use

import firstlook
from sklearn.datasets import load_iris

iris = load_iris(as_frame=True).frame
report = firstlook.at(iris, target="target")

report.task          # "classification"
report.start         # "LogisticRegression"
report.models        # [("LogisticRegression", "..."), ...]
report.notes         # ["3 classes", ...]
report.figure        # the Plotly figure (restyle or export it)
report.to_html("iris.html")

Need just one piece?

firstlook.detect_task(df, target="price")   # "regression"
firstlook.recommend(df, target="price")     # a Recommendation (task, start, models, notes)
firstlook.visualize(df, target="price")     # a Plotly figure

The dark theme is also a registered Plotly template you can use on your own figures:

fig.update_layout(template="firstlook")

(firstlook.at and firstlook.play are the same call.)

Get a baseline score, too

Pass fit=True and firstlook trains the recommended model and cross-validates it, so the recommendation comes with a real score attached. Preprocessing (impute, scale, one-hot) is built in, so it fits straight on messy data:

report = firstlook.at(df, target="price", fit=True)
report.baseline      # Baseline(model="LinearRegression", metric="R2", score=0.97, ...)

Needs scikit-learn: pip install "firstlook[fit]".

What it handles today

Tabular regression, classification, and clustering. Image / text / time-series problems are out of scope for now.

Roadmap

• More chart types (pair plots, missingness maps, target-vs-time).
• A light/lab theme alongside the dark one.
• Image / text / time-series support beyond tabular.

License

MIT