Quickstart

This example shows the shortest meaningful path through design-research-analysis.

1. Install

python -m pip install --upgrade pip
pip install design-research-analysis

Or install from source:

git clone https://github.com/cmudrc/design-research-analysis.git
cd design-research-analysis
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install .

Install extras when you need optional analysis families:

pip install "design-research-analysis[seq]"
pip install "design-research-analysis[lang,embeddings]"
pip install "design-research-analysis[maps]"
pip install "design-research-analysis[stats,data]"

2. Minimal Runnable Example

from design_research_analysis import (
    coerce_unified_table,
    fit_markov_chain_from_table,
    validate_unified_table,
)

rows = coerce_unified_table(
    [
        {"timestamp": "2026-01-01T00:00:00", "session_id": "s1", "actor_id": "a", "event_type": "ideate"},
        {"timestamp": "2026-01-01T00:00:05", "session_id": "s1", "actor_id": "a", "event_type": "refine"},
        {"timestamp": "2026-01-01T00:00:10", "session_id": "s1", "actor_id": "a", "event_type": "evaluate"},
    ]
)

report = validate_unified_table(rows)
if not report.is_valid:
    raise RuntimeError("; ".join(report.errors))

result = fit_markov_chain_from_table(rows)
print(result.states)

You can also point the API at exported files directly when that is more convenient:

from design_research_analysis import coerce_unified_table, profile_dataframe

rows = coerce_unified_table("data/events.csv")
profile = profile_dataframe("data/events.csv")
print(len(rows), profile["n_columns"])

3. What Happened

You validated a unified event table and fit a sequence model from those records. This demonstrates the package design: schema discipline first, analysis second.

4. Where To Go Next

• Concepts

• Experiments-To-Analysis Handoff

• Typical Workflow

• Workflows

• Examples Guide

Ecosystem Note

In a typical study, design-research-agents provides executable participants, design-research-problems supplies the task, design-research-experiments defines the study structure, and design-research-analysis interprets the resulting records.

If you are starting from exported study artifacts rather than an in-memory table, use Experiments-To-Analysis Handoff for the recommended events.csv to analysis path.