design-research-analysis

design-research-analysis is the unified-table analysis layer in the cmudrc design research ecosystem.

It provides typed, reusable workflows for sequence, language, embedding-map, and statistical analysis over recurring event logs.

Quality Signals

• Coverage reports total line coverage for the default deterministic test suite; CI requires at least 95%.
• Examples Passing reports checked-in example scripts that execute successfully in the examples workflow.
• API in Examples reports curated top-level __all__ exports referenced by runnable examples. N/N means every supported top-level export appears in at least one example, and CI requires 100%.

Run make coverage, make examples-test, and make examples-coverage to reproduce these checks locally.

Overview

This package centers on reproducible analysis workflows with a small top-level API:

• Unified-table coercion, validation, and mapper-based derived columns
• Dataset profiling, schema checks, and codebook generation
• Sequence modeling (Markov chains, discrete HMM, Gaussian HMM)
• Language analysis (semantic convergence trajectories, topic modeling, sentiment scoring)
• Embedding maps (PCA, t-SNE, UMAP, PaCMAP, TriMap) with clustering, comparison, and trajectory-plotting helpers
• Statistical wrappers (group comparisons, OLS regression, mixed-effects models, nonparametrics, and power)
• Runtime provenance capture for reproducibility manifests
• Top-level artifact handoff helpers for experiment exports
• A thin CLI for deterministic pipeline runs

Quickstart

Requires Python 3.12+. Maintainer workflows target Python 3.12 (.python-version). For a VS Code path that starts from PyPI and then shows the repository example workflow, see VS Code Start.

Install from PyPI:

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

Common install profiles:

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]"
pip install "design-research-analysis[all]"

Unified-table coercion, validation, and derived-column helpers ship in the base install, so there is no separate table extra.

For contributor workflows:

python -m venv .venv
source .venv/bin/activate
make dev
make test

Run a compact end-to-end example:

PYTHONPATH=src python examples/basic_usage.py

For dependency profiles and release-check guidance, see Dependencies and Extras.

CLI

The package installs a design-research-analysis CLI:

design-research-analysis validate-table --input data/events.csv --summary-json artifacts/validate.json
design-research-analysis run-sequence --input data/events.csv --summary-json artifacts/sequence.json --mode markov
design-research-analysis run-language --input data/events.csv --summary-json artifacts/language.json --trajectory-csv artifacts/language_trajectory.csv
design-research-analysis run-embedding-maps --input data/events.csv --summary-json artifacts/embedding_maps.json --map-csv artifacts/embedding_maps.csv
design-research-analysis run-stats --input data/events.csv --summary-json artifacts/stats.json --mode regression --x-columns x1,x2 --y-column y

The Python API can start from files too at the main ingestion points, for example coerce_unified_table("data/events.csv") and profile_dataframe("data/events.csv").

Examples

Start with examples/README.md for runnable scripts across all analysis families.

Docs

See the published documentation for quickstart, workflow guidance, schema details, CLI reference, and API docs.

Build docs locally with:

make docs

Public API

The supported public surface is whatever is exported from design_research_analysis.__all__.

Top-level exports include:

• Package metadata: __version__
• Artifact handoff helpers: validate_experiment_events, build_condition_metric_table_from_artifacts, build_event_table_from_artifacts
• Table contracts: UnifiedTableConfig, UnifiedTableValidationReport, coerce_unified_table, derive_columns, validate_unified_table
• Sequence: fit_markov_chain_from_table, fit_discrete_hmm_from_table, fit_text_gaussian_hmm_from_table, decode_hmm, plotting helpers, and result types
• Language: compute_language_convergence, compute_semantic_distance_trajectory, fit_topic_model, score_sentiment
• Embedding maps: embed_records, build_embedding_map, cluster_embedding_map, compare_embedding_maps, plot_embedding_map, plot_embedding_map_grid
• Statistics: compare_groups, fit_regression, fit_mixed_effects, permutation_test, bootstrap_ci, power helpers
• Dataset + runtime: profile_dataframe, validate_dataframe, generate_codebook, capture_run_context, attach_provenance, write_run_manifest

Contributing

Contribution workflow and validation gates are documented in CONTRIBUTING.md.