dirconn 0.1.0__py3-none-any.whl

dirconn/__init__.py

@@ -0,0 +1,130 @@
+"""dirconn: directed functional connectivity for neurophysiology signals.
+
+The core package depends on numpy, scipy, pandas, xarray, netcdf4, mne and mne-bids. MNE is
+imported lazily by the modules that need it; tigramite, statsmodels, mne-connectivity and
+plotting libraries are optional extras.
+"""
+
+from importlib import metadata
+
+from dirconn import datasets, viz
+from dirconn.analytic import (
+    AnalyticTestResult,
+    AsymptoticTestResult,
+    analytic_gc_test,
+    analytic_pdc_test,
+    analytic_rpdc_test,
+)
+from dirconn.bands import BANDS
+from dirconn.baseline import baseline_normalise
+from dirconn.bids import (
+    SimulationRecord,
+    read_bids,
+    read_simulation_bids,
+    write_roi_bids,
+    write_simulation_bids,
+)
+from dirconn.bootstrap import BootstrapResult, bootstrap
+from dirconn.channels import ChannelMeta
+from dirconn.coherency import PSI, ImCoh, imcoh, psi
+from dirconn.contrast import ContrastResult, contrast_test
+from dirconn.correction import adjust_pvalues
+from dirconn.estimator import Estimator, MethodInfo
+from dirconn.exceptions import DirconnWarning
+from dirconn.granger import GC, gc
+from dirconn.multitaper_granger import MTGC, mtgc
+from dirconn.mvar import OrderSelection, VarFit, fit_var, select_order
+from dirconn.network import Edge, Network, direct_node, dk_node
+from dirconn.pcmci import PCMCI, PCMCITestResult, pcmci, pcmci_test
+from dirconn.provenance import AssumptionCheck, AssumptionChecklist, Provenance
+from dirconn.result import Connectivity
+from dirconn.significance import significance_test
+from dirconn.simulation import NodeDynamics, SimulatedData, coupled_nonlinear, simulate
+from dirconn.spectral_estimators import DTF, GPDC, PDC, RPDC, dtf, gpdc, pdc, rpdc
+from dirconn.surrogate_test import SurrogateTestResult, surrogate_test
+from dirconn.time_reversal import TRGC, TimeReversalAsymmetry, time_reversal_asymmetry, trgc
+from dirconn.timeseries import TimeSeries
+from dirconn.timevarying import ADTF, TPDC, adtf, tpdc
+from dirconn.transfer_entropy import TE, te
+from dirconn.windowed import WDTF, wdtf
+
+__version__: str = metadata.version("dirconn")
+
+__all__ = [
+    "ADTF",
+    "BANDS",
+    "DTF",
+    "GPDC",
+    "MTGC",
+    "PCMCI",
+    "PCMCITestResult",
+    "PDC",
+    "PSI",
+    "RPDC",
+    "TPDC",
+    "TRGC",
+    "WDTF",
+    "AnalyticTestResult",
+    "AsymptoticTestResult",
+    "AssumptionCheck",
+    "AssumptionChecklist",
+    "BootstrapResult",
+    "ChannelMeta",
+    "ContrastResult",
+    "Connectivity",
+    "DirconnWarning",
+    "Edge",
+    "Estimator",
+    "GC",
+    "ImCoh",
+    "MethodInfo",
+    "Network",
+    "NodeDynamics",
+    "OrderSelection",
+    "Provenance",
+    "SimulatedData",
+    "SimulationRecord",
+    "SurrogateTestResult",
+    "TE",
+    "TimeReversalAsymmetry",
+    "TimeSeries",
+    "VarFit",
+    "__version__",
+    "datasets",
+    "adjust_pvalues",
+    "adtf",
+    "analytic_gc_test",
+    "analytic_pdc_test",
+    "analytic_rpdc_test",
+    "baseline_normalise",
+    "bootstrap",
+    "contrast_test",
+    "coupled_nonlinear",
+    "direct_node",
+    "dk_node",
+    "dtf",
+    "fit_var",
+    "gc",
+    "gpdc",
+    "imcoh",
+    "mtgc",
+    "pcmci",
+    "pcmci_test",
+    "pdc",
+    "psi",
+    "read_bids",
+    "read_simulation_bids",
+    "rpdc",
+    "select_order",
+    "significance_test",
+    "simulate",
+    "surrogate_test",
+    "te",
+    "time_reversal_asymmetry",
+    "tpdc",
+    "trgc",
+    "viz",
+    "wdtf",
+    "write_roi_bids",
+    "write_simulation_bids",
+]

dirconn/_csd.py

@@ -0,0 +1,244 @@
+"""Multitaper cross-spectra shared by the spectral methods (imcoh, PSI, multitaper Granger).
+
+The spectra are an own multitaper transform on non-overlapping segments of ``segment_length``
+seconds, with the tapers, weights and scaling of :func:`mne.time_frequency.csd_array_multitaper`
+(``tests/test_csd.py`` checks equality on every frequency MNE returns). MNE is not called at run
+time because it never returns 0 Hz, which the spectral factorisation of the multitaper Granger
+causality needs (:func:`two_sided_spectra`). Continuous data must give ``segment_length``;
+epoched data may (every trial is then cut on its own) or use every trial as one segment. No
+segment crosses a trial boundary, and the tail that does not fill a segment is dropped and
+recorded. The mean of every channel is removed within every segment, as MNE always does.
+:func:`cross_spectra` returns the native FFT bins of the segment length between ``fmin`` and
+``fmax`` without 0 Hz, as MNE does.
+
+Convention: ``values[i, j, f] = <X_i(f) conj(X_j(f))>``, averaged over tapers and segments. When
+channel ``j`` is channel ``i`` delayed by ``d`` samples, the phase of ``values[i, j, f]`` is
+``+2 pi f d / sfreq`` (measured in ``tests/test_csd.py``).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from dirconn.timeseries import TimeSeries
+from dirconn.tvmvar import seconds_to_samples
+
+DEFAULT_TIME_HALFBANDWIDTH = 4.0
+"""Default time-half-bandwidth product ``NW`` (MNE's default as well); about ``2 NW - 1`` tapers."""
+
+_LOW_BIAS_RATIO = 0.9
+_BACKEND = "own multitaper transform (scipy DPSS; tapers, weights and scaling as in MNE)"
+
+
+@dataclass(frozen=True)
+class CrossSpectra:
+    """Cross-spectral density matrices on a frequency grid.
+
+    Attributes
+    ----------
+    values : ndarray of complex, shape (n_channels, n_channels, n_freqs)
+        ``values[i, j, f] = <X_i(f) conj(X_j(f))>``; Hermitian in ``(i, j)`` at every frequency.
+    freqs : ndarray, shape (n_freqs,)
+        Frequencies in Hz.
+    record : dict
+        Segments, tapers and bandwidth, for the provenance of the result that uses the spectra.
+    """
+
+    values: np.ndarray
+    freqs: np.ndarray
+    record: dict[str, Any]
+
+
+def _number(value: Any, name: str) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float, np.integer, np.floating))
+        or not math.isfinite(value)
+    ):
+        raise ValueError(f"{name} must be a finite number, got {value!r}.")
+    return float(value)
+
+
+def _segments(data: TimeSeries, segment_length: Any) -> tuple[np.ndarray, int, int]:
+    """Return ``(segments, segment_samples, discarded_samples)``; segments are (n, ch, times)."""
+    if segment_length is None:
+        if data.segmentation == "epoched":
+            return np.asarray(data.data), data.n_times, 0
+        raise ValueError(
+            "segment_length is required for continuous data: it sets the frequency resolution "
+            "(1 / segment_length Hz), so it has no default."
+        )
+    seg = seconds_to_samples(
+        _number(segment_length, "segment_length"), data.sfreq, "segment_length"
+    )
+    per_trial = data.n_times // seg
+    if per_trial < 1:
+        where = "a trial" if data.segmentation == "epoched" else "the data"
+        raise ValueError(
+            f"segment_length ({segment_length!r} s, {seg} samples) is longer than {where} "
+            f"({data.n_times} samples)."
+        )
+    used = per_trial * seg
+    x = np.asarray(data.data)[:, :, :used]
+    # (trial, channel, segment, sample) -> (trial, segment, channel, sample): trials never mix
+    split = x.reshape(data.n_trials, data.n_channels, per_trial, seg).transpose(0, 2, 1, 3)
+    segments = split.reshape(data.n_trials * per_trial, data.n_channels, seg)
+    return segments, seg, data.n_trials * (data.n_times - used)
+
+
+def _tapers(n_times: int, half_nbw: float) -> tuple[np.ndarray, np.ndarray]:
+    """DPSS tapers and their eigenvalues, chosen as MNE does (``sym=False``, eigenvalue > 0.9)."""
+    from scipy.signal.windows import dpss
+
+    tapers, ratios = dpss(
+        n_times, half_nbw, Kmax=max(int(2 * half_nbw), 1), sym=False, norm=2, return_ratios=True
+    )
+    tapers, ratios = np.atleast_2d(tapers), np.atleast_1d(ratios)
+    keep = ratios > _LOW_BIAS_RATIO
+    return tapers[keep], ratios[keep]
+
+
+def _prepare(
+    data: TimeSeries, segment_length: Any, time_halfbandwidth: Any
+) -> tuple[np.ndarray, int, int, float, np.ndarray, np.ndarray]:
+    segments, seg, discarded = _segments(data, segment_length)
+    nw = _number(time_halfbandwidth, "time_halfbandwidth")
+    if nw < 1:
+        raise ValueError(f"time_halfbandwidth must be at least 1, got {time_halfbandwidth!r}.")
+    tapers, eigenvalues = _tapers(seg, nw)
+    if tapers.shape[0] < 1:
+        raise ValueError(f"time_halfbandwidth={nw:g} leaves no taper with low bias.")
+    return segments, seg, discarded, nw, tapers, eigenvalues
+
+
+def _periodogram(
+    segments: np.ndarray,
+    tapers: np.ndarray,
+    eigenvalues: np.ndarray,
+    sfreq: float,
+    n_fft: int | None = None,
+) -> np.ndarray:
+    """Two-sided multitaper cross-periodogram on every rfft bin, averaged over segments.
+
+    ``P[i, j, f] = sum_k w_k X_ik(f) conj(X_jk(f)) / sfreq`` with ``w_k`` the eigenvalues divided by
+    their sum (MNE's non-adaptive weights), after removing the mean of every segment. ``n_fft``
+    zero-pads the transform (default: the segment length).
+    """
+    x = segments - segments.mean(axis=-1, keepdims=True)
+    tapered = x[:, :, np.newaxis, :] * tapers[np.newaxis, np.newaxis]
+    spectra = np.fft.rfft(tapered, n=n_fft, axis=-1)
+    weights = eigenvalues / eigenvalues.sum()
+    total = np.einsum("k,sikf,sjkf->ijf", weights, spectra, np.conj(spectra))
+    # exactly Hermitian, as MNE's upper-triangle computation is: otherwise rounding makes
+    # |imcoh[i, j]| and |imcoh[j, i]| differ in the last bit and breaks ties when scoring
+    total = 0.5 * (total + np.conj(np.swapaxes(total, 0, 1)))
+    return total / (segments.shape[0] * sfreq)
+
+
+def _record(
+    data: TimeSeries, segments: np.ndarray, seg: int, discarded: int, nw: float, n_tapers: int
+) -> dict[str, Any]:
+    return {
+        "backend": _BACKEND,
+        "segmentation": data.segmentation,
+        "segment_length_s": seg / data.sfreq,
+        "segment_samples": seg,
+        "n_segments": int(segments.shape[0]),
+        "discarded_samples": int(discarded),
+        "time_halfbandwidth": nw,
+        "bandwidth_hz": 2 * nw * data.sfreq / seg,
+        "n_tapers": n_tapers,
+        "frequency_resolution_hz": data.sfreq / seg,
+        "mean_removed_per_segment": True,
+    }
+
+
+def cross_spectra(
+    data: TimeSeries,
+    *,
+    segment_length: float | None = None,
+    time_halfbandwidth: float = DEFAULT_TIME_HALFBANDWIDTH,
+    fmin: float = 0.0,
+    fmax: float | None = None,
+) -> CrossSpectra:
+    """Multitaper cross-spectra of all channel pairs, averaged over segments.
+
+    One-sided densities with the conventions of :func:`mne.time_frequency.csd_array_multitaper`
+    (equal to it on every frequency it returns, which ``tests/test_csd.py`` checks): 0 Hz is left
+    out and the Nyquist bin of an even segment is not doubled.
+
+    Parameters
+    ----------
+    data : TimeSeries
+        Continuous or epoched input.
+    segment_length : float, optional
+        Segment length in seconds, a multiple of the sampling interval. Required for continuous
+        data; for epoched data every trial is cut on its own, and without it every trial is one
+        segment.
+    time_halfbandwidth : float
+        Time-half-bandwidth product ``NW`` (at least 1); the full bandwidth in Hz is
+        ``2 NW / segment duration``.
+    fmin, fmax : float
+        Frequency range in Hz, inclusive; ``fmax`` defaults to the Nyquist frequency.
+
+    Returns
+    -------
+    CrossSpectra
+    """
+    segments, seg, discarded, nw, tapers, eigenvalues = _prepare(
+        data, segment_length, time_halfbandwidth
+    )
+    nyquist = data.sfreq / 2
+    lo = _number(fmin, "fmin")
+    hi = nyquist if fmax is None else _number(fmax, "fmax")
+    if lo < 0:
+        raise ValueError(f"fmin must be non-negative, got {fmin!r}.")
+    if hi > nyquist:
+        raise ValueError(f"fmax ({fmax!r} Hz) is above the Nyquist frequency ({nyquist:g} Hz).")
+    if lo >= hi:
+        raise ValueError(f"fmin ({fmin!r}) must be below fmax ({hi!r}).")
+    bins = np.fft.rfftfreq(seg, 1.0 / data.sfreq)
+    keep = (bins > 0) & (bins >= lo) & (bins <= hi)
+    if not keep.any():
+        raise ValueError(
+            f"There is no frequency bin between fmin={lo:g} and fmax={hi:g} Hz at a resolution "
+            f"of {data.sfreq / seg:g} Hz (segment of {seg} samples)."
+        )
+    one_sided = 2 * _periodogram(segments, tapers, eigenvalues, data.sfreq)
+    if seg % 2 == 0:
+        one_sided[:, :, -1] /= 2  # the Nyquist bin has no mirror image, as in MNE
+    record = _record(data, segments, seg, discarded, nw, tapers.shape[0])
+    record.update({"fmin": lo, "fmax": hi, "two_sided": False})
+    return CrossSpectra(values=one_sided[:, :, keep], freqs=bins[keep], record=record)
+
+
+def two_sided_spectra(
+    data: TimeSeries,
+    *,
+    segment_length: float | None = None,
+    time_halfbandwidth: float = DEFAULT_TIME_HALFBANDWIDTH,
+    pad_factor: int = 1,
+) -> CrossSpectra:
+    """Two-sided multitaper cross-spectra on every bin from 0 Hz to Nyquist, for factorisation.
+
+    ``values[..., f]`` is the two-sided density at ``freqs[f]`` (half the one-sided one away from
+    0 Hz and Nyquist); the negative frequencies are its complex conjugate. Same segments and
+    tapers as :func:`cross_spectra`. ``pad_factor`` zero-pads every segment to that many times its
+    length, which samples the same spectrum on a finer grid (every ``pad_factor``-th bin is a
+    native bin); the record keeps ``n_fft``.
+    """
+    if isinstance(pad_factor, bool) or not isinstance(pad_factor, int) or pad_factor < 1:
+        raise ValueError(f"pad_factor must be a positive integer, got {pad_factor!r}.")
+    segments, seg, discarded, nw, tapers, eigenvalues = _prepare(
+        data, segment_length, time_halfbandwidth
+    )
+    n_fft = seg * pad_factor
+    values = _periodogram(segments, tapers, eigenvalues, data.sfreq, n_fft)
+    record = _record(data, segments, seg, discarded, nw, tapers.shape[0])
+    record.update({"two_sided": True, "n_fft": n_fft})
+    freqs = np.fft.rfftfreq(n_fft, 1.0 / data.sfreq)
+    return CrossSpectra(values=values, freqs=freqs, record=record)

dirconn/_greedy.py

@@ -0,0 +1,290 @@
+"""Greedy selection of past variables with permutation tests, for multivariate transfer entropy.
+
+For one target ``j`` the candidates are past samples ``(channel, lag)``: the target's own past at
+``target_lags`` and every other channel at ``source_lags``. The selection follows the
+multivariate transfer entropy of IDTxl (Lizier and Rubinov 2012; Novelli et al. 2019):
+
+1. **Target past.** Add the candidate with the largest ``I(candidate; j_t | selected)`` while a
+   maximum-statistic permutation test finds it significant. When none is, the most recent target
+   sample is kept so the target's own memory is always conditioned on.
+2. **Sources.** The same greedy loop over the source candidates, conditioning on everything
+   selected so far.
+3. **Pruning.** Remove the selected source variable with the smallest
+   ``I(variable; j_t | all other selected)`` while a minimum-statistic test finds it not
+   significant.
+4. **Omnibus test.** ``I(all selected source variables; j_t | selected target past)`` against
+   permutations of the whole source set; when it fails, no source is kept.
+5. **Sequential test per source.** For every source channel, the information of its selected
+   variables given everything else selected, tested in decreasing order against the ranked
+   maxima of the permutations (step-down, so the p-values never decrease along the order).
+
+A permutation replaces the tested variables by their values at permuted rows. With enough trials
+(``n_trials! >= n_permutations``) whole trials are permuted, otherwise every trial is shifted
+circularly by an amount drawn between 10 % and 90 % of its rows. One permutation is shared by all
+candidates of a test, so a maximum (or minimum) over candidates is a maximum over one surrogate
+dataset. p-values are ``(count(null >= observed) + 1) / (n_permutations + 1)``; a test passes at
+``p <= alpha``.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from dirconn._ksg import ksg_cmi_many
+
+
+@dataclass(frozen=True)
+class GreedySettings:
+    """Everything the selection of one target needs, picklable for joblib."""
+
+    target_lags: tuple[int, ...]
+    source_lags: tuple[int, ...]
+    alpha: float
+    n_perm_max_stat: int
+    n_perm_min_stat: int
+    n_perm_omnibus: int
+    n_perm_max_seq: int
+    k: int
+    workers: int
+    device: str | None
+    dtype: str
+
+    @property
+    def start(self) -> int:
+        """First usable sample of every trial: the longest lag of any candidate."""
+        return max(max(self.target_lags), max(self.source_lags))
+
+
+Variable = tuple[int, int]
+"""A past sample: ``(channel, lag)``."""
+
+
+class _Problem:
+    """The embedded data of one target and the CMI and permutation helpers."""
+
+    def __init__(
+        self, series: np.ndarray, target: int, settings: GreedySettings, rng: np.random.Generator
+    ) -> None:
+        self.series = series
+        self.settings = settings
+        self.rng = rng
+        self.n_trials = series.shape[0]
+        self.rows = series.shape[-1] - settings.start
+        self.present = self.column((target, 0))
+        self._cache: dict[Variable, np.ndarray] = {}
+
+    def column(self, variable: Variable) -> np.ndarray:
+        channel, lag = variable
+        start, n_times = self.settings.start, self.series.shape[-1]
+        return self.series[:, channel, start - lag : n_times - lag].reshape(-1)
+
+    def values(self, variables: Sequence[Variable]) -> np.ndarray | None:
+        if not variables:
+            return None
+        out = []
+        for v in variables:
+            if v not in self._cache:
+                self._cache[v] = self.column(v)
+            out.append(self._cache[v])
+        return np.stack(out, axis=1)
+
+    def cmi(self, xs: Sequence[np.ndarray], condition: Sequence[Variable]) -> np.ndarray:
+        s = self.settings
+        return ksg_cmi_many(
+            xs,
+            self.present,
+            self.values(condition),
+            k=s.k,
+            workers=s.workers,
+            device=s.device,
+            dtype=s.dtype,
+        )
+
+    def permutations(self, n_perm: int) -> list[np.ndarray]:
+        rows, n_trials = self.rows, self.n_trials
+        offsets = np.arange(n_trials)[:, None] * rows
+        within = np.arange(rows)[None, :]
+        out = []
+        by_trial = n_trials > 1 and _factorial_at_least(n_trials, n_perm)
+        low, high = max(1, rows // 10), max(2, rows - rows // 10)
+        for _ in range(n_perm):
+            if by_trial:
+                order = self.rng.permutation(n_trials)[:, None]
+                out.append((order * rows + within).reshape(-1))
+            else:
+                shift = self.rng.integers(low, high, size=n_trials)[:, None]
+                out.append((offsets + (within + shift) % rows).reshape(-1))
+        return out
+
+    def scheme(self, n_perm: int) -> str:
+        if self.n_trials > 1 and _factorial_at_least(self.n_trials, n_perm):
+            return "trials"
+        return "circular"
+
+
+def _factorial_at_least(n: int, bound: int) -> bool:
+    value = 1
+    for i in range(2, n + 1):
+        value *= i
+        if value >= bound:
+            return True
+    return value >= bound
+
+
+def _p_value(null: np.ndarray, observed: float) -> float:
+    return float((np.count_nonzero(null >= observed) + 1) / (null.size + 1))
+
+
+def _include(
+    problem: _Problem, candidates: list[Variable], selected: list[Variable]
+) -> tuple[list[Variable], list[dict[str, Any]]]:
+    """Greedy inclusion with the maximum-statistic test; returns the added variables."""
+    s = problem.settings
+    added: list[Variable] = []
+    steps: list[dict[str, Any]] = []
+    remaining = list(candidates)
+    while remaining:
+        condition = selected + added
+        columns = problem.values(remaining)
+        assert columns is not None
+        stats = problem.cmi(list(columns.T), condition)
+        best = int(np.argmax(stats))
+        perms = problem.permutations(s.n_perm_max_stat)
+        null = np.full(len(perms), -np.inf)
+        for c in range(len(remaining)):
+            surrogate = problem.cmi([columns[p, c] for p in perms], condition)
+            null = np.maximum(null, surrogate)
+        p = _p_value(null, float(stats[best]))
+        steps.append({"variable": list(remaining[best]), "cmi": float(stats[best]), "p": p})
+        if p > s.alpha:
+            break
+        added.append(remaining.pop(best))
+    return added, steps
+
+
+def _prune(
+    problem: _Problem, target_past: list[Variable], sources: list[Variable]
+) -> tuple[list[Variable], list[dict[str, Any]]]:
+    """Remove source variables with the minimum-statistic test."""
+    s = problem.settings
+    kept = list(sources)
+    steps: list[dict[str, Any]] = []
+    while kept:
+        perms = problem.permutations(s.n_perm_min_stat)
+        stats = np.empty(len(kept))
+        null = np.full(len(perms), np.inf)
+        for i, v in enumerate(kept):
+            condition = target_past + [u for u in kept if u != v]
+            column = problem.values([v])
+            assert column is not None
+            stats[i] = problem.cmi([column], condition)[0]
+            null = np.minimum(null, problem.cmi([column[p] for p in perms], condition))
+        worst = int(np.argmin(stats))
+        p = _p_value(null, float(stats[worst]))
+        steps.append({"variable": list(kept[worst]), "cmi": float(stats[worst]), "p": p})
+        if p <= s.alpha:
+            break
+        kept.pop(worst)
+    return kept, steps
+
+
+def _omnibus(
+    problem: _Problem, target_past: list[Variable], sources: list[Variable]
+) -> dict[str, Any]:
+    if not sources:
+        return {"te": 0.0, "p": 1.0, "significant": False}
+    s = problem.settings
+    joint = problem.values(sources)
+    assert joint is not None
+    observed = float(problem.cmi([joint], target_past)[0])
+    perms = problem.permutations(s.n_perm_omnibus)
+    null = problem.cmi([joint[p] for p in perms], target_past)
+    p = _p_value(null, observed)
+    return {"te": observed, "p": p, "significant": p <= s.alpha}
+
+
+def _sequential(
+    problem: _Problem, target_past: list[Variable], sources: list[Variable]
+) -> dict[int, tuple[float, float]]:
+    """Per source channel: (TE of its selected variables, step-down p-value)."""
+    s = problem.settings
+    channels = sorted({c for c, _ in sources})
+    perms = problem.permutations(s.n_perm_max_seq)
+    stats = np.empty(len(channels))
+    table = np.empty((len(channels), len(perms)))
+    for i, channel in enumerate(channels):
+        group = [v for v in sources if v[0] == channel]
+        condition = target_past + [v for v in sources if v[0] != channel]
+        joint = problem.values(group)
+        assert joint is not None
+        stats[i] = problem.cmi([joint], condition)[0]
+        table[i] = problem.cmi([joint[p] for p in perms], condition)
+    order = np.argsort(-stats, kind="stable").tolist()
+    ranked_null = -np.sort(-table, axis=0)  # every permutation's values in decreasing order
+    out: dict[int, tuple[float, float]] = {}
+    running = 0.0
+    for rank, i in enumerate(order):
+        running = max(running, _p_value(ranked_null[rank], float(stats[i])))
+        out[channels[i]] = (float(stats[i]), running)
+    return out
+
+
+def select_target(
+    series: np.ndarray, target: int, settings: GreedySettings, seed: np.random.SeedSequence
+) -> dict[str, Any]:
+    """Run the five steps for one target; the result is JSON-able."""
+    problem = _Problem(series, target, settings, np.random.default_rng(seed))
+    n_channels = series.shape[1]
+    target_candidates = [(target, lag) for lag in settings.target_lags]
+    source_candidates = [
+        (c, lag) for c in range(n_channels) if c != target for lag in settings.source_lags
+    ]
+    target_past, target_steps = _include(problem, target_candidates, [])
+    if not target_past:
+        target_past = [(target, min(settings.target_lags))]
+    sources, source_steps = _include(problem, source_candidates, target_past)
+    sources, prune_steps = _prune(problem, target_past, sources)
+    omnibus = _omnibus(problem, target_past, sources)
+    per_source = _sequential(problem, target_past, sources) if omnibus["significant"] else {}
+    kept = [v for v in sources if v[0] in per_source and per_source[v[0]][1] <= settings.alpha]
+    return {
+        "target_past": [list(v) for v in sorted(target_past, key=lambda v: v[1])],
+        "sources_tested": [list(v) for v in sources],
+        "sources": [list(v) for v in sorted(kept)],
+        "source_te": {str(c): te for c, (te, _) in per_source.items()},
+        "source_p": {str(c): p for c, (_, p) in per_source.items()},
+        "omnibus": omnibus,
+        "steps": {"target": target_steps, "sources": source_steps, "prune": prune_steps},
+        "n_rows": int(problem.present.size),
+    }
+
+
+def select_all(
+    series: np.ndarray, settings: GreedySettings, seed: int, n_jobs: int
+) -> list[dict[str, Any]]:
+    """Run :func:`select_target` for every target, in parallel over targets when ``n_jobs != 1``.
+
+    Each target gets its own child of ``SeedSequence(seed)``, so the result does not depend on
+    ``n_jobs``.
+    """
+    n_channels = series.shape[1]
+    seeds = np.random.SeedSequence(seed).spawn(n_channels)
+    if n_jobs != 1:
+        from joblib import Parallel, delayed
+
+        return list(
+            Parallel(n_jobs=n_jobs)(
+                delayed(select_target)(series, j, settings, seeds[j]) for j in range(n_channels)
+            )
+        )
+    return [select_target(series, j, settings, seeds[j]) for j in range(n_channels)]
+
+
+def min_permutations(alpha: float) -> int:
+    """Smallest number of permutations whose smallest p-value reaches ``alpha``."""
+    return max(1, math.ceil(1.0 / alpha - 1.0 - 1e-12))