schema

The flow-frame schema. Everything on this page is re-exported from the top-level package (nv.FLOW_COLUMNS, nv.FlowFrame, nv.to_flowframe, nv.validate_flows); import it from there rather than from the private netviz_tools._schema module.

A flow frame is a pandas.DataFrame with one row per directed flow and at least these columns:

Column	Meaning
source	origin node (for trade data, the exporting country)
target	destination node (for trade data, the importing country)
time	integer period label, for example a year
category	what flows (a commodity, a product code, a migrant type)
weight	non-negative amount
unit	unit of weight, for example "t", "persons" or "1000 USD"

Extra columns are allowed and preserved. Display names for these terms (for example "Exporter" for source) can be stored as a dict in flows.attrs["labels"]; the FAOSTAT loaders set it from faostat.LABELS, build_graph copies it into G.graph["labels"], and the plots use it.

netviz_tools._schema.FLOW_COLUMNS module-attribute

FLOW_COLUMNS: Final = (
    "source",
    "target",
    "time",
    "category",
    "weight",
    "unit",
)

Required columns of a flow frame, in canonical order.

netviz_tools._schema.FlowFrame module-attribute

FlowFrame: TypeAlias = pd.DataFrame

A pandas.DataFrame that satisfies validate_flows.

netviz_tools._schema.validate_flows

validate_flows(flows: DataFrame) -> FlowFrame

Check that a DataFrame follows the flow schema.

The check is light: required columns exist, key columns have no missing values, time is an integer column, and weight is numeric, finite and non-negative. All problems are collected and reported together.

Parameters:

Name	Type	Description	Default
flows	DataFrame	The DataFrame to check.	required

Returns:

Type	Description
FlowFrame	The same object, unchanged, so the call can be chained.

Raises:

Type	Description
SchemaError	If any check fails.

Examples:

>>> import pandas as pd
>>> df = pd.DataFrame({"source": ["A"], "target": ["B"], "time": [2020],
...                    "category": ["Wheat"], "weight": [1.0], "unit": ["t"]})
>>> validate_flows(df) is df
True

netviz_tools._schema.to_flowframe

to_flowframe(
    df: DataFrame,
    columns: Mapping[str, str] | None = None,
    **constants: str | float,
) -> FlowFrame

Convert any edge list into a flow frame.

Use this to bring your own flow data (trade, migration, shipping, payments) into the schema that the rest of the library expects.

Parameters:

Name	Type	Description	Default
df	DataFrame	Source table. It is not modified.	required
columns	Mapping[str, str] | None	Mapping from column names in df to flow-frame column names, for example {"origin": "source", "dest": "target", "n": "weight"}.	None
**constants	str | float	Values for required columns that df does not have, for example category="migrants", unit="people", time=2020.	{}

Returns:

Type	Description
FlowFrame	A new DataFrame with the six schema columns first, followed by any other columns of df. A whole-number time column is cast to int64. df.attrs (for example "labels") is carried over.

Raises:

Type	Description
SchemaError	If the result does not satisfy validate_flows, or if a constant is given for a column that already exists.

Examples:

>>> import pandas as pd
>>> raw = pd.DataFrame({"src": ["A", "B"], "dst": ["B", "C"], "n": [5, 7]})
>>> ff = to_flowframe(raw, {"src": "source", "dst": "target", "n": "weight"},
...                   time=2020, category="people", unit="persons")
>>> list(ff.columns)
['source', 'target', 'time', 'category', 'weight', 'unit']