crantpy.utils.ordering module

crantpy.utils.ordering module#

Private axis-ordering engine for NestedMatrix.

The public surface is NestedMatrix.order / NestedMatrix.by (and the same names on DirectedNestedMatrix). This module is not a user-facing toolkit.

class crantpy.utils.ordering.AxisOrdering(ordered_neurons, type_boundaries, neuron_to_type)[source]#

Bases: object

Ordered neurons and type metadata for one matrix axis.

Parameters:
neuron_to_type: dict[str, Any]#
ordered_neurons: tuple[str, ...]#
type_boundaries: dict[str, tuple[int, int]]#
class crantpy.utils.ordering.By(columns, rank=None, extract=None, key=None, na='last')[source]#

Bases: object

The rule by() returns. Construct it through by().

Parameters:
columns: tuple[str, ...]#
extract: Pattern[str] | None = None#
key: Callable[[Any], Any] | None = None#
na: Literal['last', 'first', 'raise'] = 'last'#
rank: tuple[str, ...] | None = None#
class crantpy.utils.ordering.MatrixOrder(type_rule='label', default_rule=None, within_rules=None)[source]#

Bases: object

How one matrix axis is ordered, at both of its levels.

Construct through order() (NestedMatrix.order). types orders the cell type blocks; default orders neurons inside a block that within does not name; within is a per-type override. Neither can move a neuron across a block boundary.

Parameters:

  • type_rule (Any)

  • default_rule (Any)

  • within_rules (Any)

default(rule)[source]#

Return a copy whose unnamed types use rule.

Parameters:

rule (Any)

Return type:

MatrixOrder

default_rule: Any = None#
type_rule: Any = 'label'#
types(rule)[source]#

Return a copy with a new block-order rule.

Parameters:

rule (Any)

Return type:

MatrixOrder

within(cell_type, rule=None)[source]#

Return a copy with a per-type override.

.within("EPG/PEG", NestedMatrix.by(...)) sets one type. .within({"EPG/PEG": ..., "delta7": ...}) merges a mapping.

Parameters:

  • cell_type (Any)

  • rule (Any | None)

Return type:

MatrixOrder

within_rules: Any = None#
class crantpy.utils.ordering.ResolvedAnnotations(relevant, typed, id_map, untyped_ids, missing_ids)[source]#

Bases: NamedTuple

Result of resolving neuron annotations against one axis’ neuron IDs.

Parameters:
id_map: dict[str, Any]#

Alias for field number 2

missing_ids: list[str]#

Alias for field number 4

relevant: pandas.DataFrame#

Alias for field number 0

typed: pandas.DataFrame#

Alias for field number 1

untyped_ids: list[str]#

Alias for field number 3

crantpy.utils.ordering.as_matrix_order(spec)[source]#

Coerce an order= argument into a MatrixOrder.

Parameters:

spec (MatrixOrder | Iterable[Any] | None)

Return type:

MatrixOrder

crantpy.utils.ordering.build_axis_ordering(axis_ids, annotations, id_col, type_col, order=None)[source]#

Resolve annotations and lay out one matrix axis end to end.

Parameters:
Return type:

AxisOrdering

crantpy.utils.ordering.build_ordered_neurons(typed_annotations, type_col, sorted_types, neuron_id_column, within=None, default=None)[source]#

Lay the typed neurons out block by block, returning order and boundaries.

Parameters:
Return type:

tuple[list[str], dict[str, tuple[int, int]]]

crantpy.utils.ordering.by(*columns, rank=None, extract=None, key=None, na='last')[source]#

Sort a cell type’s neurons by annotation column(s).

A string at the order layer is only a named rule ("id", "annotation", "label", "size"). Column names live here.

Parameters:

  • columns (str) – Annotation columns to read, in priority order. The first column that yields a usable value wins.

  • rank (sequence of str, optional) – Explicit label order. Without extract, the leftmost rank label that appears in the cell is used, so "EPG/PEG_R1" and "Δ7_L8R1R9" both rank without a regex.

  • extract (str or compiled pattern, optional) – Regex whose first group is the label. A plain string is compiled.

  • key (callable, optional) – value -> sort key when rank is omitted. Defaults to a natural sort, so "ER_g2" precedes "ER_g10".

  • na ({"last", "first", "raise"}, default "last") – What an unrankable or null value costs. "raise" errors; the others put those neurons after or before the ranked ones, keeping annotation row order inside that group.

Return type:

By

Examples

>>> NestedMatrix.by("cell_instance")
>>> NestedMatrix.by("cell_instance", "cell_subtype", rank=EB_RING)
>>> NestedMatrix.by("cell_instance", extract=r"([LR]\d+)", rank=PB)
crantpy.utils.ordering.order(types='label', default=None, within=None)[source]#

Build a reusable neuron order for a nested matrix axis.

Nested call:

NestedMatrix.order(
    types=["ER2", "EPG/PEG", "delta7"],
    default="id",
    within={"EPG/PEG": NestedMatrix.by("cell_instance", rank=EB_RING)},
)

Builder:

NestedMatrix.order().types(["ER2", "EPG/PEG"]).default("id").within(
    "EPG/PEG", NestedMatrix.by("cell_instance", rank=EB_RING)
)

A bare sequence passed as order= to a matrix constructor is still types-only shorthand for NestedMatrix.order(types=...).

Parameters:

  • types (Any)

  • default (Any | None)

  • within (Any | None)

Return type:

MatrixOrder

crantpy.utils.ordering.resolve_relevant_annotations(matrix_ids, annotations, id_col, type_col)[source]#

Narrow annotations to matrix_ids, de-duplicating by neuron.

Parameters:
Return type:

ResolvedAnnotations

crantpy.utils.ordering.resolve_type_order(typed_annotations, type_col, types_rule='label')[source]#

Order the cell types present in typed_annotations.

Parameters:
Return type:

list[str]

Contents