Skip to content

Latest commit

 

History

History
202 lines (143 loc) · 5.27 KB

getting-started.md

File metadata and controls

202 lines (143 loc) · 5.27 KB
layout title
default
Getting Started

Getting Started with RobustiPy

A practical, end‑to‑end guide for fitting robust specifications, managing compute, and interpreting outputs.

At a Glance

  1. Prepare a clean pandas.DataFrame with your outcome(s), main predictor(s), and candidate controls.
  2. Fit a model across many specifications with draws and/or kfold.
  3. Review results.summary() for key robustness statistics.
  4. Generate the multi‑panel figure with results.plot().
  5. Interpret the panels using the guide linked at the end.

Installation

pip install robustipy

For the latest development version:

git clone https://github.com/RobustiPy/robustipy.git
cd robustipy
pip install .

Data Preparation

RobustiPy expects a tidy pandas.DataFrame where each column corresponds to a variable.

Recommendations:

  • Make sure your y, x, and controls columns are numeric or properly encoded.
  • Handle missing values in advance (drop, impute, or encode).
  • Keep a small subset of rows for quick smoke tests before scaling up.

Model Types

  • OLSRobust: continuous outcomes.
  • LRobust: binary outcomes (logistic regression).

Both accept single outcomes or lists of outcomes (run separately) and produce a unified results object.

Quick Start (OLS)

import pandas as pd
from robustipy.models import OLSRobust

# data = pd.read_csv("your_data.csv")

y = "your_outcome"
x = "your_key_predictor"
controls = ["control_1", "control_2", "control_3", "control_4"]

model = OLSRobust(y=y, x=x, data=data)
model.fit(
    controls=controls,
    draws=1000,
    kfold=10,
    oos_metric="pseudo-r2",
    seed=192735,
    n_cpu=4,
)

results = model.get_results()
results.summary(digits=3)
results.plot(ic="aic", project_name="union_example", figpath="./figures")

Quick Start (Logistic Regression)

from robustipy.models import LRobust

model = LRobust(y="outcome_binary", x="treatment", data=data)
model.fit(
    controls=controls,
    draws=500,
    kfold=5,
    oos_metric="pseudo-r2",
    seed=123,
)

results = model.get_results()
results.summary()
results.plot(ic="bic", oddsratio=True)

Specification Space Basics

RobustiPy builds many “reasonable” specifications by varying which controls are included. The control list you pass to fit() defines the candidate set. The full specification space can be large, so RobustiPy lets you sample or downscale.

Core Fit Parameters (Reference)

Parameter Purpose Notes
controls Candidate control variables Required list of column names
draws Bootstrap resamples per spec If None, bootstrapping is skipped
kfold Folds for cross‑validation Requires oos_metric
oos_metric OOS metric 'pseudo-r2' or 'rmse'
n_cpu Parallel processes Defaults to all available CPUs minus one if not provided
seed Reproducibility Propagated to all random ops
group Fixed effects grouping De‑means outcomes by group
z_specs_sample_size Sample specs Randomly samples control‑set combinations
composite_sample Composite bootstrap Reduces compute by sampling before specs
rescale_y/x/z Standardization Rescales variables to mean 0, sd 1
threshold Workload warning Warns if specs × draws × folds is too large

Compute‑Friendly Run Example

model.fit(
    controls=controls,
    draws=200,
    kfold=5,
    z_specs_sample_size=300,
    threshold=200000,
    n_cpu=4,
)

Results Object: What You Get

After get_results(), the results object includes:

  • results.summary() for a compact robustness overview.
  • results.plot() for the multi‑panel figure.
  • results.summary_df with per‑spec metrics (ICs, OOS performance, etc.).
  • results.estimates, results.p_values, results.r2_values for full matrices of outcomes.

Plotting Options You’ll Use Most

  • ic: 'aic', 'bic', or 'hqic'.
  • specs: list of specific control sets to highlight (max 3).
  • ci: confidence interval width.
  • loess: smooth CI bounds.
  • colormap: colormap for highlights and colorbars.
  • highlights: toggle full‑model and null‑model highlights.
  • oddsratio: show exponentiated coefficients for logistic models.
  • figpath, project_name, ext: output location and file format.

Highlighting Specific Specifications

specs = [
    ["age", "tenure", "hours"],
    ["age", "tenure", "hours", "collgrad"],
]

results.plot(specs=specs, ic="hqic")

Output Files

results.plot(...) saves a combined multi‑panel figure and a set of individual panels. Use figpath and project_name to control the output directory and filename prefix.

Common Pitfalls

  • The x‑axis in the spec curve is rank‑ordered, not time.
  • Cross‑validation requires oos_metric.
  • Large control sets can explode the spec space. Use sampling parameters early.
  • If you change colormap or highlights, verify the legend colors line up across panels.

Next Steps

  • For a full subfigure‑by‑subfigure interpretation, read INTERPRETATION_GUIDE.MD.
  • Browse the empirical example notebooks on GitHub: empirical_examples