geff_spec

Axis

Bases: BaseModel

The axes list is modeled after the OME-zarr specifications and is used to identify spatio-temporal properties on the graph nodes.

The name must be an existing attribute on the nodes. The optional type key must be one of space, time or channel, though readers may not use this information. An optional unit key should match the valid OME-Zarr units and min and max keys define the range of the axis

The optional scale field can be used to store a scaling factor such as converting the data from pixel space into real world units. The associated, optional scaled_unit field specifies the output unit after applying scale to the data.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the corresponding node property	required
`type`	`Literal['space', 'time', 'channel'] \| None`	The type of data encoded in this axis, one of ('space', 'time', 'channel') or None	`None`
`unit`	str \| Literal['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', 'pixel'] \| Literal['attosecond', 'centisecond', 'day', 'decisecond', 'exasecond', 'femtosecond', 'gigasecond', 'hectosecond', 'hour', 'kilosecond', 'megasecond', 'microsecond', 'millisecond', 'minute', 'nanosecond', 'petasecond', 'picosecond', 'second', 'terasecond', 'yoctosecond', 'yottasecond', 'zeptosecond', 'zettasecond', 'frame'] \| None	Optional, the unit for this axis. If the type is 'space' or 'time', we recommend utilizing the OME-NGFF spatial or temporal units respectively.	`None`
`min`	`float \| None`	Optional, the minimum value for this axis.	`None`
`max`	`float \| None`	Optional, the minimum value for this axis.	`None`
`scale`	`float \| None`	Optional, a scaling factor that can be applied to the data	`None`
`scaled_unit`	str \| Literal['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', 'pixel'] \| Literal['attosecond', 'centisecond', 'day', 'decisecond', 'exasecond', 'femtosecond', 'gigasecond', 'hectosecond', 'hour', 'kilosecond', 'megasecond', 'microsecond', 'millisecond', 'minute', 'nanosecond', 'petasecond', 'picosecond', 'second', 'terasecond', 'yoctosecond', 'yottasecond', 'zeptosecond', 'zettasecond', 'frame'] \| None	Optional, the unit after applying the `scale` value to the data. If `scaled_unit` is set, a `scale` value must also be provided.	`None`
`offset`	`float \| None`	Optional, the amount by which to offset this axis after applying the `scale` if specified.	`None`

DisplayHint

Bases: BaseModel

Metadata indicating how spatiotemporal axes are displayed by a viewer

Parameters:

Name	Type	Description	Default
`display_horizontal`	`str`	Which spatial axis to use for horizontal display	required
`display_vertical`	`str`	Which spatial axis to use for vertical display	required
`display_depth`	`str \| None`	Optional, which spatial axis to use for depth display	`None`
`display_time`	`str \| None`	Optional, which temporal axis to use for time	`None`

GeffMetadata

Bases: BaseModel

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

Parameters:

Name	Type	Description	Default
`geff_version`	`str`	Geff version string following semantic versioning (MAJOR.MINOR.PATCH), optionally with .devN and/or +local parts (e.g., 0.3.1.dev6+g61d5f18). If not provided, the version will be set to the current geff package version.	`'1.1'`
`directed`	`bool`	True if the graph is directed, otherwise False.	required
`axes`	`list[Axis] \| None`	Optional list of `Axis` objects defining the axes of each node in the graph. The axes list is modeled after the OME-zarr specifications and is used to identify spatio-temporal properties on the graph nodes. If the same names are used in the axes metadata of the related image or segmentation data, applications can use this information to align graph node locations with image data. The order of the axes in the list is meaningful. For one, any downstream properties that are an array of values with one value per (spatial) axis will be in the order of the axis list (filtering to only the spatial axes by the `type` field if needed). Secondly, if associated image or segmentation data does not have axes metadata, the order of the spatiotemporal axes is a good default guess for aligning the graph and the image data, although there is no way to denote the channel dimension in the graph spec. If you are writing out a geff with an associated segmentation and/or image dataset, we highly recommend providing the axis names for your segmentation/image using the OME-zarr spec, including channel dimensions if needed.	`None`
`node_props_metadata`	`dict[str, PropMetadata]`	Metadata for node properties. The keys are the property identifiers, and the values are PropMetadata objects describing the properties.There must be one entry for each node property.	required
`edge_props_metadata`	`dict[str, PropMetadata]`	Metadata for edge properties. The keys are the property identifiers, and the values are PropMetadata objects describing the properties.There must be one entry for each edge property.	required
`sphere`	`str \| None`	Name of the optional `sphere` property. A sphere is defined by a center point, already given by the `space` type properties a radius scalar, stored in this property	`None`
`ellipsoid`	`str \| None`	Name of the `ellipsoid` property. An ellipsoid is assumed to be in the same coordinate system as the `space` type properties. It is defined by a center point \(c\), already given by the `space` type properties a covariance matrix \(\Sigma\), symmetric and positive-definite, stored in this property as a `2x2`/`3x3` array. To plot the ellipsoid: Compute the eigendecomposition of the covariance matrix \(\Sigma = Q \Lambda Q^{\top}\) Sample points \(z\) on the unit sphere Transform the points to the ellipsoid by \(x = c + Q \Lambda^{(1/2)} z\).	`None`
`track_node_props`	`dict[Literal['lineage', 'tracklet'], str] \| None`	Node properties denoting tracklet and/or lineage IDs. A tracklet is defined as a simple path of connected nodes where the initiating node has any incoming degree and outgoing degree at most 1, and the terminating node has incoming degree at most 1 and any outgoing degree, and other nodes along the path have in/out degree of 1. Each tracklet must contain the maximal set of connected nodes that match this definition - no sub-tracklets. A lineage is defined as a weakly connected component on the graph. The dictionary can store one or both of 'tracklet' or 'lineage' keys.	`None`
`related_objects`	`list[RelatedObject] \| None`	A list of dictionaries of related objects such as labels or images. Each dictionary must contain 'type', 'path', and optionally 'label_prop' properties. The 'type' represents the data type. 'labels' and 'image' should be used for label and image objects, respectively. Other types are also allowed, The 'path' should be relative to the geff zarr-attributes file. It is strongly recommended all related objects are stored as siblings of the geff group within the top-level zarr group. The 'label_prop' is only valid for type 'labels' and specifies the node property that will be used to identify the labels in the related object.	`None`
`display_hints`	`DisplayHint \| None`	Metadata indicating how spatiotemporal axes are displayed by a viewer	`None`
`extra`	`dict[str, Any]`	The optional `extra` object is a free-form dictionary that can hold any additional, application-specific metadata that is not covered by the core geff schema. Users may place arbitrary keys and values inside `extra` without fear of clashing with future reserved fields. Although the core `geff` reader makes these attributes available, their meaning and use are left entirely to downstream applications.	`<class 'dict'>`

read

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) -> None

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

GeffSchema

Bases: BaseModel

Parameters:

Name	Type	Description	Default
`geff`	`GeffMetadata`	geff_metadata	required

PropMetadata

Bases: BaseModel

Each property must have a string identifier (the group name for the property) and a dtype. The dtype can be any string that can be coerced into a numpy dtype, or the special varlength dtype indicating this is a variable length property (coming soon). String properties should have dtype str, not varlength, even though they are stored using the same variable length mechanism.

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Identifier of the property. Must be unique within its own component subgroup (nodes or edges). Must be a non-empty string.	required
`dtype`	`str`	Data type of the property. Must be one of the allowed string dtypes.	required
`varlength`	`bool`	True if the property contains variable length arrays. Variable length arrays cannot be of dtype string (e.g. you cannot have a property where each node has an array of strings)	`False`
`unit`	`str \| None`	Optional unit of the property.	`None`
`name`	`str \| None`	Optional human friendly name of the property	`None`
`description`	`str \| None`	Optional description of the property.	`None`

RelatedObject

Bases: BaseModel

A set of metadata for data that is associated with the graph. The types 'labels' and 'image' should be used for label and image objects, respectively. Other types are also allowed.

Parameters:

Name	Type	Description	Default
`type`	`str`	Type of the related object. 'labels' for label objects, 'image' for image objects. Other types are also allowed, but may not be recognized by reader applications.	required
`path`	`str`	Path of the related object within the zarr group, relative to the geff zarr-attributes file. It is strongly recommended all related objects are stored as siblings of the geff group within the top-level zarr group.	required
`label_prop`	`str \| None`	Property name for label objects. This is the node property that will be used to identify the labels in the related object. This is only valid for type 'labels'.	`None`

validate_axis_type

validate_axis_type(axis_type: Any) -> TypeGuard[AxisType]

Validate axis type against standard list

Parameters:

Name	Type	Description	Default
`axis_type`	`str`	Axis type to check	required

Returns:

Name	Type	Description
`bool`	`TypeGuard[AxisType]`	False if the axis is not in valid types

validate_space_unit

validate_space_unit(
    unit_name: Any,
) -> TypeGuard[SpaceUnits]

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`	`TypeGuard[SpaceUnits]`	True if a space unit is a KNOWN valid unit.
	`TypeGuard[SpaceUnits]`	False if the unit is not known. The unit may be valid.

validate_time_unit

validate_time_unit(unit_name: Any) -> TypeGuard[TimeUnits]

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`	`TypeGuard[TimeUnits]`	True if a time unit is a KNOWN valid unit.
	`TypeGuard[TimeUnits]`	False if the unit is not known. The unit may be valid.