neu_mark.annsource¶

Assembling a complete precomputed annotation source from a connections table.

One LINE per distinct (T-bar, PSD) coordinate pair. Writes what the format requires: an info, a by_id index, one index per relationship, and spatial levels, all sharded through neu_vol.sharded.

Annotation ids are hashed from both endpoints, so they are stable: re-running gives the same ids, and a saved link stays valid when the body list grows.
A pair with one unknown body is still a line. Geometry is always complete; the partner’s body is unknown when it was not fetched. Such lines are kept by default (include_partial=False drops them).
The spatial index emits each annotation at exactly one level, coarse to fine, so a zoomed-out view draws a representative sample from one small cell. The sampling numbers are a starting point to check in a viewer, not fixed by the spec.

Attributes¶

`BY_ID_KEY`
`NO_ROI`
`NO_ROI_LABEL`
`REL_KEYS`
`ROI_DESCRIPTIONS`
`SPATIAL_KEY`
`logger`

Functions¶

`annotation_ids`(pre_xyz, post_xyz) → numpy.ndarray	Stable uint64 ids, hashed from both endpoints.
`build`(connections, *, lower_bound, upper_bound, ...[, ...]) → dict[str, Any]	Everything needed to write a source, from a `connections` table.
`default_properties`([rois, listed]) → list[dict[str, Any]]	The properties of a synapse line, unsorted: element confidences, body ids truncated
`format_report`(report) → list[str]
`next_level`(grid, extent) → dict[str, Any]	One level finer: halve the axis whose cells are longest, keeping cells roughly cubic.
`pd_isna`(value) → bool	`pandas.isna` without importing pandas at module scope.
`plan_spatial`(n, lower, upper, *[, per_cell, max_levels]) → list[dict[str, Any]]	Grid shapes, coarsest first — the schedule assuming annotations spread evenly.
`read_annotation`(src, annotation_id, *[, info]) → dict[str, Any] \| None	One annotation out of a written source's `by_id` index, decoded.
`read_related`(src, relationship, body, *[, info]) → dict[str, Any] \| None	One body's annotations from a relationship index, decoded — a viewer's keyed fetch.
`roi_values`(frame, ids, top_level) → tuple[dict[str, numpy.ndarray], dict[str, dict[int, str]]]	`roi` and `neuropil` per line, as ROI spec ids, from `pre_roi` / `post_roi`.
`tbar_fanout`(frame) → numpy.ndarray	How many lines share each line's presynaptic coordinate, capped at uint16.
`verify`(src, connections, *[, sample, seed]) → dict[str, Any]	Read a written source back and check it against the table it was built from.
`verify_spatial`(src, info, *[, per_level, seed]) → dict[str, Any]	Fetch spatial cells by the key a viewer computes, and check what comes back.
`write`(dst, built) → list[str]	Write the `info` and every index. Returns the keys written.

Module Contents¶

neu_mark.annsource.annotation_ids(pre_xyz: numpy.ndarray, post_xyz: numpy.ndarray) → numpy.ndarray¶

Stable uint64 ids, hashed from both endpoints.

blake2b over the six little-endian int32 coordinates, truncated to 63 bits (the top bit clear, for consumers that read it as signed). build() checks for collisions.

neu_mark.annsource.build(connections, *, lower_bound: Sequence[float], upper_bound: Sequence[float], voxel_size_xyz: Sequence[float], roi_ids: Mapping[str, int] | None = None, top_level: Mapping[str, str] | None = None, listed: Iterable[int] | None = None, include_partial: bool = True, per_cell: int = 4000, max_levels: int = 16, seed: int = 0) → dict[str, Any]¶

Everything needed to write a source, from a connections table.

roi_ids (ROI name to the ROI spec’s id) and top_level (ROI to its top-level neuropil) add the roi and neuropil properties, from the table’s pre_roi / post_roi (roi_values()). listed (body ids) adds pre_listed / post_listed, for hiding synapses on bodies the segmentation does not show.

Returns {"info", "by_id", "relationships", "spatial", "report"} where the index values are {key: [(chunk_id, payload)]} ready for neu_vol.sharded.write_all(). Nothing is written here, so the caller can inspect or test it first.

neu_mark.annsource.default_properties(rois: Mapping[str, Mapping[int, str]] | None = None, *, listed: bool = False) → list[dict[str, Any]]¶: The properties of a synapse line, unsorted: element confidences, body ids truncated to uint32 (properties cannot be uint64) and the T-bar’s fanout, plus one int16 enum per entry of rois ({property id: {value: label}}) and, with listed, whether each end’s body is one of the listed bodies.

neu_mark.annsource.format_report(report: Mapping[str, Any]) → list[str]¶

neu_mark.annsource.next_level(grid: Sequence[int], extent: Sequence[float]) → dict[str, Any]¶: One level finer: halve the axis whose cells are longest, keeping cells roughly cubic.

neu_mark.annsource.pd_isna(value: Any) → bool¶: pandas.isna without importing pandas at module scope.

neu_mark.annsource.plan_spatial(n: int, lower: Sequence[float], upper: Sequence[float], *, per_cell: int = 4000, max_levels: int = 16) → list[dict[str, Any]]¶

Grid shapes, coarsest first — the schedule assuming annotations spread evenly.

A starting guess: synapses concentrate in neuropil, so _assign_levels() extends the schedule from the real distribution.

neu_mark.annsource.read_annotation(src: str, annotation_id: int, *, info: Mapping[str, Any] | None = None) → dict[str, Any] | None¶

One annotation out of a written source’s by_id index, decoded.

None when the id is absent. Reads through the sharded index, as a viewer does.

neu_mark.annsource.read_related(src: str, relationship: str, body: int, *, info: Mapping[str, Any] | None = None) → dict[str, Any] | None¶: One body’s annotations from a relationship index, decoded — a viewer’s keyed fetch.

neu_mark.annsource.roi_values(frame, ids: Mapping[str, int], top_level: Mapping[str, str]) → tuple[dict[str, numpy.ndarray], dict[str, dict[int, str]]]¶

roi and neuropil per line, as ROI spec ids, from pre_roi / post_roi.

The ids are the ones the ROI layers paint, so a synapse coloured by id matches its neuropil’s mesh. A line takes its T-bar’s ROI, else its PSD’s (a T-bar outside the body list was not fetched). Returns (values, {property: {id: name}}).

neu_mark.annsource.tbar_fanout(frame) → numpy.ndarray¶: How many lines share each line’s presynaptic coordinate, capped at uint16.

neu_mark.annsource.verify(src: str, connections, *, sample: int = 200, seed: int = 0) → dict[str, Any]¶

Read a written source back and check it against the table it was built from.

Fetches sample rows by id and compares endpoints, confidences and relationships, checks one body’s relationship index in full, then the spatial index (verify_spatial()). Only a read-back shows the keys are right: a wrong key leaves correct bytes on the store and nothing in the viewer.

neu_mark.annsource.verify_spatial(src: str, info: Mapping[str, Any], *, per_level: int = 3, seed: int = 0) → dict[str, Any]¶

Fetch spatial cells by the key a viewer computes, and check what comes back.

Checks two things: that cells can be found by the key a reader computes from a grid position (a compressed Morton code), and that each annotation in a cell lies inside the cell’s bounds.

neu_mark.annsource.write(dst: str, built: Mapping[str, Any]) → list[str]¶: Write the info and every index. Returns the keys written.

neu_mark.annsource.BY_ID_KEY = 'by_id'¶

neu_mark.annsource.NO_ROI = 0¶

neu_mark.annsource.NO_ROI_LABEL = '<none>'¶

neu_mark.annsource.REL_KEYS¶

neu_mark.annsource.ROI_DESCRIPTIONS¶

neu_mark.annsource.SPATIAL_KEY = 'by_spatial_level_{level}'¶

neu_mark.annsource.logger¶