Basic Usage#

Source: examples/basic_usage.py

Introduction#

Use a tiny unified table from one team session to run the most common baseline: schema validation, event-sequence transitions, and language convergence.

Technical Implementation#

  1. Validate required and recommended unified-table columns.

  2. Fit a first-order Markov chain from event transitions.

  3. Compare the fitted Markov chain to a small alternate session trace.

  4. Compute semantic convergence using a deterministic custom embedder.

 1from __future__ import annotations
 2
 3import design_research_analysis as dran
 4
 5
 6def main() -> None:
 7    """Run a lightweight unified-table analysis workflow."""
 8    print("Package version:", dran.__version__)
 9
10    rows = [
11        {
12            "timestamp": "2026-01-01T10:00:00Z",
13            "session_id": "team-a",
14            "actor_id": "alice",
15            "event_type": "propose",
16            "text": "initial concept sketch",
17        },
18        {
19            "timestamp": "2026-01-01T10:01:00Z",
20            "session_id": "team-a",
21            "actor_id": "bob",
22            "event_type": "evaluate",
23            "text": "review constraints and compare options",
24        },
25        {
26            "timestamp": "2026-01-01T10:02:00Z",
27            "session_id": "team-a",
28            "actor_id": "alice",
29            "event_type": "refine",
30            "text": "refined concept around shared constraints",
31        },
32    ]
33
34    report = dran.validate_unified_table(rows)
35    if not report.is_valid:
36        raise RuntimeError(f"Invalid table: {report.errors}")
37
38    markov = dran.fit_markov_chain_from_table(rows, order=1, smoothing=1.0)
39    print("Markov states:", markov.states)
40    print("Transition matrix:")
41    print(markov.transition_matrix)
42
43    alternate_rows = [
44        {
45            "timestamp": "2026-01-01T10:00:00Z",
46            "session_id": "team-b",
47            "actor_id": "alice",
48            "event_type": "propose",
49            "text": "initial concept sketch",
50        },
51        {
52            "timestamp": "2026-01-01T10:01:00Z",
53            "session_id": "team-b",
54            "actor_id": "bob",
55            "event_type": "refine",
56            "text": "refined concept around shared constraints",
57        },
58        {
59            "timestamp": "2026-01-01T10:02:00Z",
60            "session_id": "team-b",
61            "actor_id": "alice",
62            "event_type": "evaluate",
63            "text": "review constraints and compare options",
64        },
65    ]
66    alternate_markov = dran.fit_markov_chain_from_table(alternate_rows, order=1, smoothing=1.0)
67    print("Markov difference:", (markov - alternate_markov).to_dict())
68
69    custom_vectors = {
70        "initial concept sketch": [3.0, 0.0],
71        "review constraints and compare options": [1.5, 0.0],
72        "refined concept around shared constraints": [0.0, 0.0],
73    }
74    convergence = dran.compute_language_convergence(
75        rows,
76        window_size=1,
77        embedder=lambda texts: [custom_vectors[text] for text in texts],
78    )
79    print("Language direction:", convergence.direction_by_group)
80
81
82if __name__ == "__main__":
83    main()

Expected Results#

Run Command

PYTHONPATH=src python examples/basic_usage.py

Prints the ordered Markov states, transition matrix, one model-comparison summary, and one convergence label for team-a.

References#

  • docs/workflows.rst