Skip to content

API Docs

Networkx Backend

geff.read_nx 

read_nx(
    store: StoreLike,
    validate: bool = True,
    node_props: list[str] | None = None,
    edge_props: list[str] | None = None,
) -> tuple[nx.Graph, GeffMetadata]

Read a geff file into a networkx graph. Metadata properties will be stored in the graph properties, accessed via G.graph[key] where G is a networkx graph.

Parameters:

Name Type Description Default
store str | Path | zarr store

The path/str to the geff zarr, or the store itself. Opens in append mode, so will only overwrite geff-controlled groups.

 required
validate bool

Flag indicating whether to perform validation on the geff file before loading into memory. If set to False and there are format issues, will likely fail with a cryptic error. Defaults to True.

 True
node_props list of str

The names of the node properties to load, if None all properties will be loaded, defaults to None.

 None
edge_props list of str

The names of the edge properties to load, if None all properties will be loaded, defaults to None.

 None

Returns:

Type Description
tuple[Graph, GeffMetadata]

A networkx graph containing the graph that was stored in the geff file format

geff.write_nx 

write_nx(
    graph: Graph,
    store: StoreLike,
    metadata: GeffMetadata | None = None,
    axis_names: list[str] | None = None,
    axis_units: list[str | None] | None = None,
    axis_types: list[str | None] | None = None,
    zarr_format: Literal[2, 3] = 2,
)

Write a networkx graph to the geff file format

Parameters:

Name Type Description Default
graph Graph

A networkx graph

 required
store str | Path | zarr store

The path/str to the output zarr, or the store itself. Opens in append mode, so will only overwrite geff-controlled groups.

 required
metadata GeffMetadata

The original metadata of the graph. Defaults to None. If provided, will override the graph properties.

 None
axis_names Optional[list[str]]

The names of the spatial dims represented in position property. Defaults to None. Will override both value in graph properties and metadata if provided.

 None
axis_units Optional[list[str]]

The units of the spatial dims represented in position property. Defaults to None. Will override value both value in graph properties and metadata if provided.

 None
axis_types Optional[list[str]]

The types of the spatial dims represented in position property. Usually one of "time", "space", or "channel". Defaults to None. Will override both value in graph properties and metadata if provided.

 None
zarr_format Literal[2, 3]

The version of zarr to write. Defaults to 2.

 2

Utilities

geff.validate 

validate(store: StoreLike)

Check that the structure of the zarr conforms to geff specification

Parameters:

Name Type Description Default
store str | Path | zarr store

Check the geff zarr, either str/Path/store

 required

Raises:

Type Description
AssertionError

If geff specs are violated
ValueError

If store is not a valid zarr store or path doesn't exist

Metadata

geff.GeffMetadata

Bases: BaseModel

Geff metadata schema to validate the attributes json file in a geff zarr

read classmethod 

read(store: StoreLike) -> GeffMetadata

Helper function to read GeffMetadata from a zarr geff group.

Parameters:

Name Type Description Default
store zarr store | Path | str

The geff store to read the metadata from

 required

Returns:

Name Type Description
GeffMetadata GeffMetadata

The GeffMetadata object

write 

write(store: StoreLike)

Helper function to write GeffMetadata into the group of a zarr geff store. Maintains consistency by preserving ignored attributes with their original values.

Parameters:

Name Type Description Default
store zarr store | Path | str

The geff store to write the metadata to

 required

geff.metadata_schema.Axis

Bases: BaseModel

geff.metadata_schema.axes_from_lists 

axes_from_lists(
    axis_names: Sequence[str] | None = None,
    axis_units: Sequence[str | None] | None = None,
    axis_types: Sequence[str | 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 list[str] | None

Names of properties for spatiotemporal axes. Defaults to None.

 None
axis_units list[str | None] | None

Units corresponding to named properties. Defaults to None.

 None
axis_types list[str | None] | None

Axis type for each property. Choose from "space", "time", "channel". Defaults to None.

 None
roi_min list[float | None] | None

Minimum value for each property. Defaults to None.

 None
roi_max list[float | None] | None

Maximum value for each property. Defaults to None.

 None

Returns:

Type Description
list[Axis]

list[Axis]:

Units

geff.units.validate_axis_type 

validate_axis_type(axis_type: str) -> bool

Validate axis type against standard list

Parameters:

Name Type Description Default
axis_type str

Axis type to check

 required

Returns:

Name Type Description
bool bool

False if the axis is not in valid types

geff.units.VALID_AXIS_TYPES module-attribute 

VALID_AXIS_TYPES = ['space', 'time', 'channel']

geff.units.validate_space_unit 

validate_space_unit(unit_name: str) -> bool

Checks space unit against ome-zarr supported units

Parameters:

Name Type Description Default
unit_name str

Unit name to check

 required

Returns:

Name Type Description
bool bool

True if a space unit is a KNOWN valid unit.
bool

False if the unit is not known. The unit may be valid.

geff.units.VALID_SPACE_UNITS module-attribute 

VALID_SPACE_UNITS = [
    None,
    "angstrom",
    "attometer",
    "centimeter",
    "decimeter",
    "exameter",
    "femtometer",
    "foot",
    "gigameter",
    "hectometer",
    "inch",
    "kilometer",
    "megameter",
    "meter",
    "micrometer",
    "mile",
    "millimeter",
    "nanometer",
    "parsec",
    "petameter",
    "picometer",
    "terameter",
    "yard",
    "yoctometer",
    "yottameter",
    "zeptometer",
    "zettameter",
]

geff.units.validate_time_unit 

validate_time_unit(unit_name: str) -> bool

Check time unit against ome-zarr supported units

Parameters:

Name Type Description Default
unit_name str

Unit name to check

 required

Returns:

Name Type Description
bool bool

True if a time unit is a KNOWN valid unit.
bool

False if the unit is not known. The unit may be valid.

geff.units.VALID_TIME_UNITS module-attribute 

VALID_TIME_UNITS = [
    None,
    "attosecond",
    "centisecond",
    "day",
    "decisecond",
    "exasecond",
    "femtosecond",
    "gigasecond",
    "hectosecond",
    "hour",
    "kilosecond",
    "megasecond",
    "microsecond",
    "millisecond",
    "minute",
    "nanosecond",
    "petasecond",
    "picosecond",
    "second",
    "terasecond",
    "yoctosecond",
    "yottasecond",
    "zeptosecond",
    "zettasecond",
]

Writing Helpers

geff.write_arrays.write_arrays 

write_arrays(
    geff_store: StoreLike,
    node_ids: ndarray,
    node_props: dict[str, tuple[ndarray, ndarray | None]]
    | None,
    edge_ids: ndarray,
    edge_props: dict[str, tuple[ndarray, ndarray | None]]
    | None,
    metadata: GeffMetadata,
    node_props_unsquish: dict[str, list[str]] | None = None,
    edge_props_unsquish: dict[str, list[str]] | None = None,
    zarr_format: Literal[2, 3] = 2,
)

Write a geff file from already constructed arrays of node and edge ids and props

Currently does not do any validation that the arrays are valid, but could be added as an optional flag.

Parameters:

Name Type Description Default
geff_store str | Path | zarr store

The path/str to the geff zarr, or the store itself. Opens in append mode, so will only overwrite geff-controlled groups.

 required
node_ids ndarray

An array containing the node ids. Must have same dtype as edge_ids.

 required
node_props dict[str, tuple[ndarray, ndarray | None]] | None

A dictionary from node property names to (values, missing) arrays, which should have same length as node_ids.

 required
edge_ids ndarray

An array containing the edge ids. Must have same dtype as node_ids.

 required
edge_props dict[str, tuple[ndarray, ndarray | None]] | None

A dictionary from edge property names to (values, missing) arrays, which should have same length as edge_ids.

 required
metadata GeffMetadata

The metadata of the graph.

 required
zarr_format Literal[2, 3]

The zarr specification to use when writing the zarr. Defaults to 2.

 2
node_props_unsquish dict[str, list[str]] | None

a dictionary indicication how to "unsquish" a property into individual scalars (e.g.: {"pos": ["z", "y", "x"]} will store the position property as three individual properties called "z", "y", and "x".

 None
edge_props_unsquish dict[str, list[str]] | None

a dictionary indicication how to "unsquish" a property into individual scalars (e.g.: {"pos": ["z", "y", "x"]} will store the position property as three individual properties called "z", "y", and "x".

 None