margo

A terminal user interface (tui) for scaffolding margot causal inference projects.

Installation

If you don't have Rust

If you don't have Rust, install it:

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# then restart your terminal, or run:
source ~/.cargo/env

For Windows, download the installer from rustup.rs.

Once Rust is installed, run the cargo install command above.

Install via cargo

If you have Rust installed:

cargo install --git https://github.com/go-bayes/margo

Usage

# launch interactive mode
margo

# create a new GRF (Generalised Random Forests) project from the CLI
margo init grf church_attendance wellbeing life_satisfaction

# show help
margo --help

What it does

margo init grf <exposure> [outcomes...] creates a complete project scaffold:

my-study/
├── study.toml          # configuration (edit this first)
├── rproject.toml       # rv dependency manifest
├── README.md           # workflow documentation
├── .gitignore          # excludes data files
└── src/
    ├── 00-preflight.R   # shared package, path, and saved-object checks
    ├── 00-setup.R       # project setup (rv, dependencies)
    ├── 01-data-prep.R   # data wrangling, binary exposure
    ├── 02-wide-format.R # long→wide, two-stage IPCW weights
    ├── 03-causal-forest.R # GRF estimation, ATE plots
    ├── 04-heterogeneity.R # RATE/AUTOC tests, qini plots
    ├── 05-policy-tree.R # policy tree stability
    ├── 06-positivity.R  # transition tables
    ├── 07-tables.R      # summary tables
    └── 08-plots.R       # visualisation

Configuration

Edit study.toml with your study-specific settings:

[paths]
# legacy margo key for the source-data directory
pull_data = "/path/to/your/source/data"
source_arrow_name = "nzavs_arrow"
# legacy margo key for the output directory
push_mods = "/path/to/your/output/directory"

[waves]
baseline = "Time 11"
exposure = ["Time 12"]
outcome  = "Time 13"

[exposure]
name = "your_exposure_variable"
binary_cutpoints = [0, 5]

[outcomes]
vars = ["outcome_1", "outcome_2"]

[baseline]
vars = ["age", "male_binary", "education_level_coarsen"]

Then run scripts in order: src/01-data-prep.R, src/02-wide-format.R, etc.

The pull_data and push_mods names are retained for existing margo projects. Future workflow schemas should use clearer directory names such as source_data_dir and output_dir, with R function arguments named source_data_dir_path and output_dir_path.

Requirements

• R >= 4.0
• rv package manager: https://github.com/jColumn/rv

Run src/00-setup.R to install margot and the project dependencies. The generated rv files declare dependencies, but they are not a complete reproducibility guarantee across R versions, system libraries, package-cache state, or local operating-system settings.

Measures workspace docs

• Quickstart: docs/measures/quickstart.md
• Command reference: docs/measures/commands.md

Templates

Template	Description	Status
grf	Generalised Random Forests (3-wave heterogeneous treatment effects)	✓ Available
grf-event	GRF Event Study (multi-outcome waves for effect trajectories)	✓ Available
lmtp	Longitudinal Modified Treatment Policies	Planned

CLI Examples

Basic usage

# create a GRF project with exposure and outcomes specified directly
margo init grf church_attendance wellbeing life_satisfaction

# multiple outcomes
margo init grf hours_exercise kessler_6 self_esteem meaning_purpose

Using templates

Templates let you reuse predefined sets of outcomes and baselines:

# load outcomes from a template
margo init grf church_attendance -t wellbeing

# combine multiple outcome templates
margo init grf exercise -t wellbeing,health

# use a custom baseline template
margo init grf meditation life_satisfaction -b extended

Templates are stored in ~/.config/margo/outcomes/ and ~/.config/margo/baselines/.

Custom project names

# auto-generated name: church_attendance-wellbeing-life_satisfaction
margo init grf church_attendance wellbeing life_satisfaction

# custom name
margo init grf church_attendance wellbeing -n "nzavs-religion-study"

Configuration management

# create user config file
margo config init

# show config path
margo config path
# ~/.config/margo/config.toml

# edit config in your $EDITOR
margo config edit

GRF Event Study (multi-outcome waves)

For longitudinal event studies where a single exposure is followed by multiple outcome waves:

# basic event study
margo init grf-event earthquake_affected -o religion_religious

# specify outcome waves and reference wave (t=0)
margo init grf-event earthquake_affected \
  -o religion_religious \
  -w 2011,2012,2013,2014,2015,2016,2017,2018,2019,2020,2021,2022,2023 \
  -r 2011 \
  -n chch-earthquake-faith

# use custom baseline template
margo init grf-event flood_exposure -o mental_health -b extended

This generates scripts that:

1. Fit causal forests for each outcome wave
2. Collect ATEs across waves
3. Plot effect trajectory over time
4. Run heterogeneity tests on significant waves

Interactive mode

# launch the interactive REPL for guided project setup
margo

Getting help

margo --help
margo init --help
margo init grf --help
margo init grf-event --help
margo config --help

Licence

MIT