README.md

metadata

title: PathwayLab | Cohort Transition Intelligence
emoji: 🧭
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Offline cohort transitions and outcome analysis
tags:
  - education
  - statistics
  - data-analysis
  - markov-chains
  - decision-support
  - data-visualization
  - javascript

PathwayLab | Cohort Transition Intelligence

An interactive, offline-first laboratory for analyzing education, workforce and public-service pathways using absorbing Markov chains.

PathwayLab is an original open-source application for learning, exploration and reproducible research demonstrations. It is designed to run as a Hugging Face Static Space, using only HTML, CSS and JavaScript. No account tokens, back-end services, external dependencies, requests to an AI model or paid hosting are required by the app.

Capabilities

Workspace	What it does
Overview	Projects favorable, adverse and still-active outcomes over a configurable horizon (4 to 24 periods).
Journey map	Visualizes states and transition probabilities; supports interactive state inspection.
Cohort comparison	Contrasts segment-specific outcomes, gaps and expected absorption time.
Intervention studio	Applies a transparent hypothetical adjustment to a chosen transition probability and compares the before/after distributions.
Uncertainty lab	Computes an illustrative model-based central 80% interval by drawing alternative transition matrices from Dirichlet distributions.
Data & methods	Imports aggregated transition counts from CSV, full study definitions from JSON, and exports six different evidence artifacts.

The three synthetic example datasets concern university progression, workplace onboarding and public service requests. They do not claim to describe real institutions, people or outcomes.

Quick start

1. Create a Space in Hugging Face, with Static SDK, Blank template and Public visibility.
2. Upload the three files directly to the repository root: README.md, index.html and LICENSE.
3. Commit your changes and open the App tab. The default example should appear immediately.
4. Use the dataset selector, cohort selector and horizon selector to explore the application.

The short_description is well below 60 characters, and the supported Space card colors are green and blue. The YAML metadata above is the configuration for deployment. The index.html file is self-contained.

Mathematical approach

Let the state space have transient states and absorbing states. For each group, transition count data (c_{ij}) are normalized into a row-stochastic transition matrix:

[ P_{ij}=\frac{c_{ij}}{\sum_{k}c_{ik}}. ]

Absorbing states have probability 1 of staying in that state. Given an initial-state probability vector (\pi_0), the model projects (\pi_t=\pi_0P^t). At each period, the sum of favorable, adverse, and still-in-progress probabilities should equal 1, up to floating-point tolerance.

With the transient submatrix (Q), and when (I-Q) is invertible, the expected number of periods to any final outcome is computed using the fundamental matrix ((I-Q)^{-1}\mathbf{1}). A singular matrix is reported as unavailable, not fabricated.

Intervention studio: the selected transition probability is increased by a chosen number of percentage points, capped below 1. Remaining outgoing probabilities in the same row are scaled proportionally to keep the row total equal to 1. This is not an empirical causal effect estimate.

Uncertainty laboratory: 200 deterministic draws from independent Dirichlet distributions using a 0.5 pseudocount for observed positive outgoing transitions. Structural-zero edges are retained. We report the 10th and 90th percentiles of the resulting favorable outcome probability. These are conditional model-based intervals, not coverage guarantees.

Bring your own data

CSV must contain this exact header, and one row for each positive transition count:

segment,from,to,count,from_type,to_type
Urban,applied,applied,15,transient,transient
Urban,applied,enrolled,72,transient,transient
Urban,applied,withdrawn,13,transient,absorbing

For each group, all transient states must have positive total outgoing counts. At least one transient state and two distinct absorbing outcomes are required. When importing CSV, the first origin is treated as the starting state and the favorable/adverse outcome roles are assigned in order of discovery. Inspect these roles after importing. Cohort sizes are estimated from the initial state's outgoing transition counts, and are not treated as independently observed participant totals.

For exact cohort sizes and complete control of state labels and outcome roles, import JSON. A minimal valid JSON structure is:

{
  "id": "example",
  "name": "My study",
  "description": "Aggregated transition dataset",
  "initial": "start",
  "good": "completed",
  "bad": "departed",
  "states": [
    {"id":"start","label":"Starting point","type":"transient"},
    {"id":"completed","label":"Completed","type":"absorbing"},
    {"id":"departed","label":"Departed","type":"absorbing"}
  ],
  "rows": [
    {"segment":"A","from":"start","to":"start","count":20},
    {"segment":"A","from":"start","to":"completed","count":60},
    {"segment":"A","from":"start","to":"departed","count":20}
  ],
  "cohorts":{"A":400}
}

The app supports at most 14 states, 5 groups, 1,600 transition records, and 1 MB of input. Validation rejects duplicated transitions and structurally invalid data without replacing the current study.

Export formats

Audit JSON, transition CSV, period projection CSV, cohort comparison CSV, a Markdown executive report and a CSV import template. CSV exports include protection against common spreadsheet formula injection for cell values beginning with unsafe characters.

Research integrity and limitations

• All built-in data are synthetic. No empirical outcome claims may be inferred from them.
• The model assumes time-homogeneous, first-order, memoryless state transitions and a common period unit.
• Differences between groups do not prove causation, discrimination or intervention effectiveness.
• Transition rates can vary over time; selection, missing data, sampling biases and nonstationarity are not corrected by this tool.
• This browser app is a decision exploration prototype, not a validated prediction engine for high-stakes individual decisions.
• The app handles inputs locally. Do not publish personally identifying or restricted data to a public repository. Uploaded files are not transmitted to an application back end.

Tests and reproducibility

The extended developer package (distributed separately, not needed for deployment) contains dev/core.js, dev/app.js, dev/style.css, a build script, Node.js core tests, Chromium/Playwright browser tests, and NumPy cross-checks. See the detailed validation notes and Spanish installation guide for the verification scope. Browser tests used isolated HTML evaluation because this testing environment blocks direct navigation to local HTTP servers.

License

MIT License. See LICENSE. Copyright (c) 2026 Hugdrigo.