geff_spec.utils

add_or_update_props_metadata

add_or_update_props_metadata(
    metadata: GeffMetadata,
    props_md: Sequence[PropMetadata],
    c_type: Literal["node", "edge"],
) -> GeffMetadata

Create new props metadata or update existing metadata with new props metadata.

Parameters:

Name	Type	Description	Default
metadata	GeffMetadata	Existing metadata object	required
props_md	Sequence[PropMetadata]	The props metadata to add to the metadata.	required
c_type	Literal['node', 'edge']	The type of the props metadata.	required

Returns:

Type	Description
GeffMetadata	GeffMetadata object with updated props metadata.

Warning

If a key in props_md already exists in the properties metadata, it will be overwritten.

axes_from_lists

axes_from_lists(
    axis_names: Sequence[str] | None = None,
    axis_units: Sequence[str | None] | None = None,
    axis_types: Sequence[Literal[AxisType] | None]
    | None = None,
    axis_scales: Sequence[float | None] | None = None,
    scaled_units: Sequence[str | None] | None = None,
    axis_offset: Sequence[float | None] | None = None,
    roi_min: Sequence[float | None] | None = None,
    roi_max: Sequence[float | None] | None = None,
) -> list[Axis]

Create a list of Axes objects from lists of axis names, units, types, mins, and maxes. If axis_names is None, there are no spatial axes and the list will be empty. Nones for all other arguments will omit them from the axes.

All provided arguments must have the same length. If an argument should not be specified for a single property, use None.

Parameters:

Name	Type	Description	Default
axis_names	Sequence[str] | None	Names of properties for spatiotemporal axes. Defaults to None.	None
axis_units	Sequence[str | None] | None	Units corresponding to named properties. Defaults to None.	None
axis_types	Sequence[Literal[AxisType] | None] | None	Axis type for each property. Choose from "space", "time", "channel". Defaults to None.	None
axis_scales	(Sequence[float | None] | None, optional)	The scale to apply to the spatial dims. Defaults to None.	None
scaled_units	Sequence[str | None] | None	The units of the spatial dims after scaling. Defaults to None.	None
axis_offset	list[float | None] | None	Amount to offset an axis after applying scaling factor. Defaults to None.	None
roi_min	Sequence[float | None] | None	Minimum value for each property. Defaults to None.	None
roi_max	Sequence[float | None] | None	Maximum value for each property. Defaults to None.	None

Returns:

Type	Description
list[Axis]	list[Axis]: A list of axes objects, one per entry in axis_names

compute_and_add_axis_min_max

compute_and_add_axis_min_max(
    metadata: GeffMetadata,
    node_props: dict[str, PropDictNpArray],
) -> GeffMetadata

Create a new metadata object with the min and max values for each axis added.

Parameters:

Name	Type	Description	Default
metadata	GeffMetadata	The metadata to update with the min and max axis values.	required
node_props	dict[str, PropDictNpArray]	The node props to compute the min and max from	required

Returns:

Name	Type	Description
GeffMetadata	GeffMetadata	A new metadata object with the min and max updated.

create_or_update_metadata

create_or_update_metadata(
    metadata: GeffMetadata | None,
    is_directed: bool,
    axes: Any = None,
) -> GeffMetadata

Create new metadata or update existing metadata with axes, version, and directedness.

Parameters:

Name	Type	Description	Default
metadata	GeffMetadata | None	Existing metadata object or None	required
is_directed	bool	Whether the graph is directed	required
axes	Any	The axes object to set	None

Returns:

Type	Description
GeffMetadata	Updated or new GeffMetadata object

create_props_metadata

create_props_metadata(
    identifier: str,
    prop_data: PropDictNpArray,
    unit: str | None = None,
    name: str | None = None,
    description: str | None = None,
) -> PropMetadata

Create PropMetadata from property data.

Automatically detects dtype and varlength from the provided data. If dtype is float16, upcasts to float32 with warning.

Parameters:

Name	Type	Description	Default
identifier	str	The property identifier/name	required
prop_data	PropDictNpArray	The property to generate metadata for	required
unit	str	Optional unit for the property	None
name	str	Optional human-friendly name for the property	None
description	str	Optional description for the property	None

Returns:

Type	Description
PropMetadata	PropMetadata object with inferred dtype and varlength settings

Raises:

Type	Description
ValueError	If var length array has mixed dtype

update_metadata_axes

update_metadata_axes(
    metadata: GeffMetadata,
    axis_names: list[str],
    axis_units: list[str | None] | None = None,
    axis_types: list[Literal[AxisType] | None]
    | None = None,
    axis_scales: list[float | None] | None = None,
    scaled_units: list[str | None] | None = None,
    axis_offset: list[float | None] | None = None,
) -> GeffMetadata

Update the axis names, units, and types in a geff metadata object. Overrides any existing axes.

If axis lists are provided, they will override the graph properties and metadata. If metadata is provided, it will override the graph properties. If neither are provided, the graph properties will be used.

Parameters:

Name	Type	Description	Default
metadata	GeffMetadata	The metadata of the graph.	required
axis_names	list[str]	The names of the spatial dims.	required
axis_units	list[str | None] | None	The units of the spatial dims. Defaults to None.	None
axis_types	list[Literal[AxisType] | None] | None	The types of the spatial dims. Defaults to None.	None
axis_scales	list[float | None] | None	The scale to apply to the spatial dims. Defaults to None.	None
scaled_units	list[str | None] | None	The units of the spatial dims after scaling. Defaults to None.	None
axis_offset	list[float | None] | None	Amount to offset an axis after applying scaling factor. Defaults to None.	None

Returns:

Name	Type	Description
GeffMetadata	GeffMetadata	A new metadata object with updated axes.