Sankey Motion · scientific use protocol

Sankey Motion Protocol

Explore the public demos, prepare defensible input for the source library, assign scientific roles explicitly, interpret motion without creating false observations, and cite the software and source data correctly.

01 · Input

CSV contract

The following input guidance is for working with your own data in the source library, not an upload form on this website. Use a header row and preserve meaningful scientific column names.

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

When preparing data for the source library, preserve the exact headers and explicitly confirm the scientific interpretation of every role. These steps describe dataset preparation, not controls in the public Studio.

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.
Validate the input and review blocking findings, warnings and assumptions before producing a visualization.

Revalidate your data whenever its scientific mapping changes.

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 Sankey experience loads fixed examples and their supporting assets. It has no CSV file picker and sends no user datasets to the retired inspection, preflight or estimation endpoints.

The website still serves the example data, media and shared site scripts. Working with your own datasets through the source library is a separate workflow governed by your chosen environment.

The public experience does not create render jobs, downloadable artifacts or email notifications.

05 · Output

Available outputs

Use Playground to experiment with built-in examples, Learn to examine flow semantics, and the Python companion to understand the source library.

Public server estimation and queued rendering have been retired. The website makes no delivery promise for a generated movie or image bundle.

Explore Playground or start the learning journey.

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.

Return to Studio Sankey Motion overview