Population Recurrence

driada.recurrence.population.population_recurrence_graph(recurrence_graphs, method='joint', threshold=1.0, binarize_threshold=None, trim='adaptive', **trim_kwargs)[source]

Combine per-neuron recurrence graphs into a population graph.

Parameters:

  • recurrence_graphs (list of RecurrenceGraph) – Individual recurrence graphs.

  • method ({'joint', 'mean'}) –

    Combination strategy:

    • 'joint': Thresholded element-wise AND (JRP). A point (i,j) is kept if at least threshold fraction of neurons recur there. threshold=1.0 is strict AND, threshold=0.5 is majority voting.

    • 'mean': Average recurrence matrices. Values in [0, 1]. Optionally binarize with binarize_threshold.

  • threshold (float, default=1.0) – For method=’joint’: fraction of neurons that must recur.

  • binarize_threshold (float, optional) – For method=’mean’: if given, binarize the averaged matrix.

  • trim ({None, 'min', 'adaptive'}, default='adaptive') – How to handle graphs of different sizes. See _reconcile_graph_sizes() for details.

  • **trim_kwargs – Extra parameters passed to _reconcile_graph_sizes() (e.g., tail_sigma=3.0 for adaptive mode).

Returns:

Population-level recurrence graph (via from_adjacency).

Return type:

RecurrenceGraph

Raises:

ValueError – If graphs have different sizes and trim is None, or method is unknown.

driada.recurrence.population.pairwise_jaccard_sparse(matrices, trim='adaptive', trim_to_min=None, **trim_kwargs)[source]

Compute pairwise Jaccard similarity for sparse binary matrices.

Uses sparse matrix multiplication to compute all pairwise intersection counts in a single operation, avoiding O(N^2) Python loops.

Parameters:

  • matrices (list of scipy.sparse matrices or RecurrenceGraph objects) – Square binary adjacency matrices. RecurrenceGraph objects are accepted (uses .adj).

  • trim ({None, 'min', 'adaptive'}, default='adaptive') – How to handle matrices of different sizes. See _reconcile_graph_sizes() for details.

  • trim_to_min (bool, optional) – Deprecated in 1.2, will be removed in 2.0. Use trim='min' instead. If passed, overrides trim.

  • **trim_kwargs – Extra parameters passed to _reconcile_graph_sizes() (e.g., tail_sigma=3.0 for adaptive mode).

Returns:

  • jaccard (ndarray of shape (N, N)) – Symmetric matrix of Jaccard indices. Diagonal is 1.0 for non-empty matrices, 0.0 for empty ones. When trim='adaptive' removes items, N < len(input).

  • kept_mask (ndarray of bool) – Boolean mask of length len(input). True for items that were kept after reconciliation.

Raises:

ValueError – If list is empty, or if matrices have different shapes and trim is None.