Sankey Motion Protocol · Hari Raj Singh

01 · Input

CSV contract

Use a header row and preserve meaningful scientific column names. The Studio proposes possible roles, but it never treats those proposals as confirmed assignments.

Fundamental row meaning: one row is one observed flow or path record at one observed ordered coordinate.

ordered_value,group,pathway,state,outcome,flow_weight,outcome_score
0,Group 1,Pathway 1,State 1,Outcome 1,18,0
0,Group 1,Pathway 2,State 2,Outcome 2,10,1
20,Group 2,Pathway 2,State 3,Outcome 3,14,2
20,Group 3,Pathway 3,State 4,Outcome 4,11,3

Role	Requirement	Scientific meaning
Stages	At least two explicitly selected columns	Ordered path categories such as group → pathway → state → outcome
Ordered coordinate	Explicitly selected ordering variable	Time, dose, position, regime, developmental stage or another ordered scientific coordinate
Width / support	Numeric, finite and non-negative	Support, amount, mass or another quantitative flow measure
Colour semantic	Independent ordered variable	A separate property used for colour; it must not silently reuse the width variable

Hard input rules

File row order is not scientific order; the chosen ordered-coordinate column controls sequence.
The system does not silently take absolute values, clip negatives, replace missing values or repair invalid scientific measurements.
Width and colour must remain scientifically distinct unless an explicit future method states otherwise.
Use UTF-8 CSV where possible and avoid merged cells, decorative headings or spreadsheet-only formatting.

02 · Mapping

Scientific mapping

Inspection preserves the exact uploaded headers and may propose stage, order, width and colour candidates. All role controls initially remain unassigned. You must review and confirm the interpretation.

Select at least two stage columns in the intended path order.
Select the ordered coordinate that defines the observed sequence.
Select the non-negative quantitative width or support measure.
Select an independent ordered colour semantic when required.
Run scientific preflight and review Blocking, Warning and Information findings.

Any mapping change invalidates the previous preflight. Run preflight again before Estimate or future Render.

03 · Interpretation

Read the motion scientifically

Flow versus Distribution

Flow allows total system mass to rise or fall. Distribution normalizes each observed state to 100%, so the visual represents composition or share rather than absolute mass.

Observation versus interpolation

Aggregate observations before interpolation. Dense movie frames are visual transition states, not new measurements, samples or evidence.

Width versus colour

Ribbon width encodes quantitative support. Colour encodes an independent ordered semantic. Interpret them separately.

04 · Trust

How your data is handled

The public Studio does not claim fully local processing. When you choose a CSV or use the sample, the browser sends the file through the website’s same-origin scientific API boundary.

Inspect: the file is sent to /api/inspect to read exact headers, structure and proposal-only role hints.
Preflight: the file and your explicit mapping are sent to /api/preflight for scientific validation.
Estimate: the file and confirmed mapping are sent to /api/estimate to estimate duration, frames and observed coordinates.
Public Render: queued rendering is closed, so the public interface does not create a render job or downloadable artifact.
Email: notifications are not enabled and no email address is required for the live Phase-1 workflow.

Do not upload patient-identifiable, confidential, regulated, security-sensitive or otherwise restricted data. Use only material appropriate for transmission to the public scientific service.

Uploaded scientific values are not sent to payment providers. No payment control is part of the upload, mapping, preflight or estimate path.

05 · Output

Estimate now; render later

Estimate reports expected processing duration, visual frame count and observed-coordinate count. It does not create the final movie or image bundle.

Queued rendering will be enabled only after durable queueing, temporary object storage, rate limits, retention rules, secure artifact delivery and deletion behavior are configured and tested together.

Current public capability: Upload or Sample → Inspect → Explicit mapping → READY → Estimate.

06 · Citation

Cite the software and the data

Software citation: Hari Raj Singh. Sankey Motion, version 1.0.0. 2026.

Suggested methods sentence: “The ordered flow visualization was prepared with Sankey Motion v1.0.0 using explicitly assigned stage, ordered-coordinate, width and colour roles; interpolated frames were treated as visual transitions rather than observations.”

Cite the originating dataset, experiment or publication separately. A software citation does not replace source-data attribution.

Open citation page Back to Studio

07 · Source

Repository and functions

Inspect the source repository, the Learn environment and the Python companion before relying on a function or output in a reproducible workflow.

Source repository Learn concepts Python companion

08 · Limits

Interpretive limits

Sankey Motion visualizes supplied structure; it does not establish causality.
Interpolation improves continuity but does not add observations.
Aggregation and filtering can alter visible topology and must be reported.
Normalization changes the question from absolute support to composition.
The scientist remains responsible for input validity, mapping, units, context and conclusions.