I'm a clinician — I want to look at donors

Browse the STAR registry, look up a specific donor, leave notes for the team.

1. Sign in at /login with your VitalMatch credentials.
2. Click Legacy v1 Data on the Projects page (or any project you've been added to).
3. In the project header, click STAR.
4. To find one donor: type a DONOR_ID (e.g. 724468) or a DICOM StudyInstanceUID. The donor record + a Recipients table (TRR ID · Organ · Transplant date · Latest status · Last follow-up) appear below. Full per-recipient field dump and the follow-up timeline are available in collapsible sections.
5. To browse the cohort: click Browse cohort →. Use the quick-filter chips at the top (DCD, DBD, ABO O/A, lung-only, age buckets) or the sidebar facets. An inline cohort overview chart updates live as filters change.
6. To leave a note on a donor: open the donor lookup, scroll to Annotations, type a tag and a note, click + Add. Other project members see it instantly.

Then explore the analytics tabs (top of every analytics page):

• Analyze — run the rule-based screening pipeline (lung volume, aeration %, density symmetry, suspicious regions) on selected scans.
• Survival — Kaplan–Meier survival on the recipient cohort. KM-corrected 1y / 3y / 5y rates, stratifications (ABO, DBD vs DCD, donor age), one-click CSV export.
• Rejection — time-to-first-acute-rejection KM. ≈ 92% rejection-free at 1y, median time to rejection ≈ 378 days.
• Cox PH — multivariate Cox regression with a forest plot. Adjusted HR + 95% CI per donor / recipient feature. Concordance, log-likelihood, Schoenfeld PH-violation diagnostic.
• CT outcomes — does the screening pipeline predict outcome? KM stratified by aeration / volume / suspicious-region tertile, with log-rank p-value per metric.
• Heatmap — empirical KM survival grid by donor age × DBD/DCD × ABO. Color-coded baseline any ML model has to beat.
• Trends — yearly transplant counts, DCD adoption curve, donor-age shift, COD + ABO mix over time. Contextualizes the cohort.
• DICOM meta — vendor / scanner / slice thickness / kVp distributions across the CT pool. Surfaces domain-shift challenges before training.
• ML pilot — XGBoost on STAR features predicting 1y graft survival. AUC, calibration curve, feature importance, confusion matrix. Baseline for the multimodal model.
• Multi-organ — for donors with lung + kidney recipients, do their 1y outcomes correlate? Tests the donor-level "quality signal" hypothesis.
• 3D viewer — marching-cubes mesh of any donor CT. Lungs / tissue / bone modes, threshold slider, step-size control. Plotly.js renderer.

I'm a researcher — I want to build a cohort and export it

Filter STAR donors, save the result, pull it into a notebook for analysis.

1. Pick a project (or create a new one for your research question — + New project on the Projects page).
2. Open the project → STAR → Browse cohort →.
3. Apply filters in the sidebar. Common patterns: ABO_DON = O, NON_HRT_DON = Y (DCD donors), has_ct = True.
4. Click Save as cohort, give it a name, save. The donor list is now frozen so re-runs always return the same set.
5. Switch to the Saved Cohorts tab. Click CSV, XLSX, or Parquet to download. Click Scan overlap to see how many donors in the cohort have an imaging scan in this project.
6. For programmatic access, mint an API token: Tokens → enter a label → + Mint. Copy the vmt_… string immediately — it's shown only once.

Next step: follow the SDK walkthrough below to use the token from a Jupyter notebook.

Skip the notebook? The platform also ships built-in analytics pages (Survival, CT outcomes, Rejection) that produce KM curves, log-rank tests, and per-recipient CSV exports without leaving the browser. Useful for quick sanity checks before pulling data into a notebook.

I'm a project admin — I want to invite collaborators

Add team members with the right role; check who did what.

1. Open the project → Members tab.
2. Type a username, pick a role:
   • reader — view-only
   • editor — can create subjects, scans, metadata, annotations, saved cohorts
   • admin — full project control + audit log access
3. Click + Add. The collaborator now sees the project on their Projects page.
4. To audit activity: Audit tab. Filter by user, action, date range. Click ↓ CSV to export.
5. Need a custom de-identification rule for this project? De-id → clone a system profile → tweak rules → assign to project.

Tip: failed access attempts are also recorded in the audit log with success=0 and the rejection reason in the detail column.

I'm a developer — I want the SDK

pip install, paste a token, reach every endpoint from Python.

# Install (once)
pip install -e ./vitalmatch_sdk
pip install pandas pyarrow             # for .as_dataframe()

# Set a token in your shell
export VM_TOKEN='vmt_…'                # from project's Tokens tab
export VM_PROJECT='legacy'

# Use
python -c "
from vitalmatch import Client
import os
c = Client(
    base_url='https://vitalmatch.ai',
    token=os.environ['VM_TOKEN'],
    project=os.environ['VM_PROJECT'],
)
print(c.me())
print(c.star.summary())
df = c.star.cohort.search(filters={'ABO_DON': ['O']}, page_size=50).as_dataframe()
print(df.head())
"

Notebooks: notebooks/01_load_a_cohort.ipynb walks through cohort building end-to-end. notebooks/02_train_on_multimodal_cohort.ipynb trains a small tabular model and writes predictions back as STAR annotations.

Cross-project tokens are not supported by design — one token per (user, project). Need access to multiple projects? Mint multiple tokens.