bmtool 0.8.7__tar.gz → 0.8.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. {bmtool-0.8.7 → bmtool-0.8.8}/PKG-INFO +2 -1
  2. bmtool-0.8.8/bmtool/analysis/ensembles.py +111 -0
  3. bmtool-0.8.8/bmtool/analysis/events.py +552 -0
  4. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/netcon_reports.py +119 -1
  5. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/spikes.py +45 -0
  6. bmtool-0.8.8/bmtool/bmplot/events.py +187 -0
  7. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/spikes.py +50 -9
  8. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/util/util.py +5 -1
  9. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/PKG-INFO +2 -1
  10. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/SOURCES.txt +8 -0
  11. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/requires.txt +1 -0
  12. {bmtool-0.8.7 → bmtool-0.8.8}/setup.py +2 -1
  13. bmtool-0.8.8/tests/test_analysis_ensembles.py +86 -0
  14. bmtool-0.8.8/tests/test_analysis_events.py +198 -0
  15. bmtool-0.8.8/tests/test_analysis_netcon_reports.py +35 -0
  16. bmtool-0.8.8/tests/test_bmplot_events.py +32 -0
  17. bmtool-0.8.8/tests/test_util_load_nodes.py +37 -0
  18. {bmtool-0.8.7 → bmtool-0.8.8}/LICENSE +0 -0
  19. {bmtool-0.8.7 → bmtool-0.8.8}/README.md +0 -0
  20. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/SLURM.py +0 -0
  21. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/__init__.py +0 -0
  22. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/__main__.py +0 -0
  23. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/__init__.py +0 -0
  24. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/entrainment.py +0 -0
  25. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/lfp.py +0 -0
  26. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/analysis/voltage_report.py +0 -0
  27. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/__init__.py +0 -0
  28. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/connections.py +0 -0
  29. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/entrainment.py +0 -0
  30. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/lfp.py +0 -0
  31. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/netcon_reports.py +0 -0
  32. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/bmplot/voltage_report.py +0 -0
  33. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/connectors.py +0 -0
  34. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/debug/__init__.py +0 -0
  35. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/debug/commands.py +0 -0
  36. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/debug/debug.py +0 -0
  37. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/graphs.py +0 -0
  38. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/manage.py +0 -0
  39. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/plot_commands.py +0 -0
  40. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/singlecell.py +0 -0
  41. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/stimulus/__init__.py +0 -0
  42. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/stimulus/assemblies.py +0 -0
  43. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/stimulus/core.py +0 -0
  44. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/stimulus/generators.py +0 -0
  45. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/synapses.py +0 -0
  46. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/util/__init__.py +0 -0
  47. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/util/commands.py +0 -0
  48. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/util/neuron/__init__.py +0 -0
  49. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool/util/neuron/celltuner.py +0 -0
  50. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/dependency_links.txt +0 -0
  51. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/entry_points.txt +0 -0
  52. {bmtool-0.8.7 → bmtool-0.8.8}/bmtool.egg-info/top_level.txt +0 -0
  53. {bmtool-0.8.7 → bmtool-0.8.8}/pyproject.toml +0 -0
  54. {bmtool-0.8.7 → bmtool-0.8.8}/setup.cfg +0 -0
  55. {bmtool-0.8.7 → bmtool-0.8.8}/tests/test_connectors.py +0 -0
  56. {bmtool-0.8.7 → bmtool-0.8.8}/tests/test_package.py +0 -0
  57. {bmtool-0.8.7 → bmtool-0.8.8}/tests/test_stimulus_generators.py +0 -0
  58. {bmtool-0.8.7 → bmtool-0.8.8}/tests/test_util_math.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: bmtool
3
- Version: 0.8.7
3
+ Version: 0.8.8
4
4
  Summary: BMTool
5
5
  Home-page: https://github.com/cyneuro/bmtool
6
6
  Download-URL:
@@ -27,6 +27,7 @@ Requires-Dist: h5py
27
27
  Requires-Dist: matplotlib
28
28
  Requires-Dist: networkx
29
29
  Requires-Dist: numpy
30
+ Requires-Dist: scipy>=1.7
30
31
  Requires-Dist: pandas
31
32
  Requires-Dist: questionary
32
33
  Requires-Dist: pynmodlt
@@ -0,0 +1,111 @@
1
+ """
2
+ Population (ensemble) structure of neural responses: pairwise similarity of response vectors, per-node similarity
3
+ summaries with bootstrap confidence intervals, and PCA trajectories across conditions.
4
+ """
5
+
6
+ from typing import Callable, Dict, Optional, Sequence, Tuple
7
+
8
+ import numpy as np
9
+ from scipy import stats
10
+
11
+ __all__ = ["pairwise_cosine_similarity", "per_node_similarity", "bootstrap_ci", "trajectory_pca"]
12
+
13
+
14
+ def pairwise_cosine_similarity(x: np.ndarray) -> np.ndarray:
15
+ """
16
+ Cosine similarity between every pair of rows of ``x`` (nodes x features), s_ij = x_i.x_j / (|x_i| |x_j|).
17
+
18
+ Uses ``sklearn.metrics.pairwise.cosine_similarity`` when scikit-learn is installed, otherwise numpy. Rows with
19
+ zero norm should be removed first (their similarity is undefined).
20
+ """
21
+ x = np.asarray(x)
22
+ try:
23
+ from sklearn.metrics.pairwise import cosine_similarity
24
+ except ImportError: # optional dependency
25
+ xn = x / np.linalg.norm(x, axis=1, keepdims=True)
26
+ return xn @ xn.T
27
+ return cosine_similarity(x)
28
+
29
+
30
+ def per_node_similarity(s: np.ndarray, stat: str = "mean") -> np.ndarray:
31
+ """
32
+ Each node's mean or median similarity to all *other* nodes (diagonal excluded) from a square matrix ``s``.
33
+ """
34
+ s = np.asarray(s)
35
+ n = s.shape[0]
36
+ off = s[~np.eye(n, dtype=bool)].reshape(n, n - 1)
37
+ if stat == "mean":
38
+ return off.mean(1)
39
+ if stat == "median":
40
+ return np.median(off, axis=1)
41
+ raise ValueError(f"stat must be 'mean' or 'median', not {stat!r}")
42
+
43
+
44
+ def bootstrap_ci(
45
+ x: Sequence[float],
46
+ statistic: Callable = np.median,
47
+ n_resamples: int = 1000,
48
+ confidence: float = 0.95,
49
+ method: str = "percentile",
50
+ seed: Optional[int] = 0,
51
+ ) -> Tuple[float, float, float]:
52
+ """
53
+ Statistic of ``x`` and its bootstrap confidence interval (``scipy.stats.bootstrap``, resampling the elements of
54
+ ``x``). Returns (statistic, low, high).
55
+ """
56
+ x = np.asarray(x, dtype=float)
57
+ res = stats.bootstrap(
58
+ (x,),
59
+ lambda a, axis: statistic(a, axis=axis),
60
+ n_resamples=n_resamples,
61
+ confidence_level=confidence,
62
+ method=method,
63
+ random_state=seed,
64
+ vectorized=True,
65
+ )
66
+ return (
67
+ float(statistic(x)),
68
+ float(res.confidence_interval.low),
69
+ float(res.confidence_interval.high),
70
+ )
71
+
72
+
73
+ def trajectory_pca(
74
+ traces: Dict[str, np.ndarray],
75
+ n_components: int = 3,
76
+ fit_on: Optional[Sequence[str]] = None,
77
+ sign_reference: Optional[Tuple[str, slice]] = None,
78
+ ):
79
+ """
80
+ PCA of trial-averaged population activity pooled across conditions, with each condition projected on the
81
+ common components (population trajectories).
82
+
83
+ Parameters
84
+ ----------
85
+ traces : dict
86
+ {condition: array (nodes x time)}; all with the same nodes.
87
+ fit_on : list of str, optional
88
+ Conditions concatenated along time for the fit (default: all, in dict order). Only these are projected.
89
+ sign_reference : (condition, slice), optional
90
+ Flip each component so its mean projection of ``condition`` over the time ``slice`` is >= 0.
91
+
92
+ Returns
93
+ -------
94
+ explained : np.ndarray
95
+ Explained-variance ratio of the first ``n_components``.
96
+ proj : dict
97
+ {condition: array (time x n_components)}.
98
+ """
99
+ from sklearn.decomposition import PCA
100
+
101
+ keys = list(traces) if fit_on is None else list(fit_on)
102
+ x = np.concatenate([np.asarray(traces[k]).T for k in keys])
103
+ pca = PCA(n_components=n_components, svd_solver="full").fit(x)
104
+ proj = {k: pca.transform(np.asarray(traces[k]).T) for k in keys}
105
+ if sign_reference is not None:
106
+ ref, sl = sign_reference
107
+ for c in range(n_components):
108
+ if proj[ref][sl, c].mean() < 0:
109
+ for k in keys:
110
+ proj[k][:, c] *= -1
111
+ return pca.explained_variance_ratio_[:n_components], proj
@@ -0,0 +1,552 @@
1
+ """
2
+ Event-aligned spike analysis: counts in windows around events, binned rates, PETHs, baseline z-scores,
3
+ per-cell response classification and Repa et al. (2001) plasticity measures.
4
+
5
+ Conventions
6
+ -----------
7
+ - Times are in milliseconds (as in BMTK spike files and ``load_spikes_to_df``).
8
+ - Every window is half-open, ``[start, stop)``.
9
+ - ``spike_df`` is a DataFrame with ``node_ids`` and ``timestamps`` columns (``load_spikes_to_df``).
10
+ - Cell-by-event and cell-by-time results are ``xarray.DataArray`` objects with a ``node_id`` dimension.
11
+ """
12
+
13
+ from typing import Optional, Sequence, Tuple
14
+
15
+ import numpy as np
16
+ import pandas as pd
17
+ import xarray as xr
18
+ from scipy import stats
19
+
20
+ __all__ = [
21
+ "spike_arrays",
22
+ "count_spikes_in_windows",
23
+ "bin_spikes",
24
+ "event_aligned",
25
+ "peth",
26
+ "baseline_zscore",
27
+ "classify_response",
28
+ "population_response_z",
29
+ "population_percent_change",
30
+ "population_rate_change",
31
+ "response_auc",
32
+ "repa_zscores",
33
+ "repa_max_block_difference",
34
+ "repa_plastic_cells",
35
+ ]
36
+
37
+
38
+ # ----------------------------------------------------------------------------- basics
39
+ def spike_arrays(
40
+ spike_df: pd.DataFrame, node_col: str = "node_ids", time_col: str = "timestamps"
41
+ ) -> Tuple[np.ndarray, np.ndarray]:
42
+ """Return (node_ids, timestamps) as numpy arrays sorted by time (stable)."""
43
+ ids = np.asarray(spike_df[node_col]).astype(np.int64)
44
+ ts = np.asarray(spike_df[time_col], dtype=float)
45
+ order = np.argsort(ts, kind="stable")
46
+ return ids[order], ts[order]
47
+
48
+
49
+ def _row_index(ids: np.ndarray, node_ids: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
50
+ """Row of each spike in ``node_ids`` (sorted lookup) and a mask of spikes whose node is in ``node_ids``."""
51
+ order = np.argsort(node_ids, kind="stable")
52
+ sorted_ids = node_ids[order]
53
+ pos = np.searchsorted(sorted_ids, ids)
54
+ pos_c = np.clip(pos, 0, len(sorted_ids) - 1)
55
+ ok = (
56
+ (pos < len(sorted_ids)) & (sorted_ids[pos_c] == ids)
57
+ if len(sorted_ids)
58
+ else np.zeros(len(ids), bool)
59
+ )
60
+ return order[pos_c], ok
61
+
62
+
63
+ def _node_ids(ids: np.ndarray, node_ids: Optional[Sequence[int]]) -> np.ndarray:
64
+ return np.unique(ids) if node_ids is None else np.asarray(node_ids, dtype=np.int64)
65
+
66
+
67
+ def count_spikes_in_windows(
68
+ spike_df: pd.DataFrame,
69
+ onsets: Sequence[float],
70
+ window: Tuple[float, float],
71
+ node_ids: Optional[Sequence[int]] = None,
72
+ ) -> xr.DataArray:
73
+ """
74
+ Spike counts of each node in ``[onset + window[0], onset + window[1])`` for every onset.
75
+
76
+ Parameters
77
+ ----------
78
+ spike_df : pd.DataFrame
79
+ Spikes with ``node_ids`` and ``timestamps`` (ms).
80
+ onsets : sequence of float
81
+ Event onsets (ms).
82
+ window : (float, float)
83
+ Window start and stop relative to each onset (ms).
84
+ node_ids : sequence of int, optional
85
+ Rows of the result, in this order. Default: nodes that spiked, sorted. Nodes without spikes get zeros.
86
+
87
+ Returns
88
+ -------
89
+ xr.DataArray
90
+ Counts with dims (node_id, event); coords ``onset`` on the event dimension.
91
+ """
92
+ ids, ts = spike_arrays(spike_df)
93
+ nodes = _node_ids(ids, node_ids)
94
+ row, ok = _row_index(ids, nodes)
95
+ onsets = np.asarray(onsets, dtype=float)
96
+ out = np.zeros((len(nodes), len(onsets)))
97
+ for j, t0 in enumerate(onsets):
98
+ lo, hi = np.searchsorted(ts, [t0 + window[0], t0 + window[1]])
99
+ sel = ok[lo:hi]
100
+ np.add.at(out[:, j], row[lo:hi][sel], 1)
101
+ return xr.DataArray(
102
+ out,
103
+ dims=("node_id", "event"),
104
+ coords={"node_id": nodes, "event": np.arange(len(onsets)), "onset": ("event", onsets)},
105
+ attrs={"window": tuple(window), "units": "spikes"},
106
+ )
107
+
108
+
109
+ def bin_spikes(
110
+ spike_df: pd.DataFrame,
111
+ bin_size: float,
112
+ t_start: float = 0.0,
113
+ t_stop: Optional[float] = None,
114
+ node_ids: Optional[Sequence[int]] = None,
115
+ rate: bool = False,
116
+ dtype=np.float64,
117
+ ) -> xr.DataArray:
118
+ """
119
+ Spike counts (or rates in Hz) per node in consecutive bins from ``t_start``.
120
+
121
+ Bin edges are ``t_start + k * bin_size`` up to the first edge >= ``t_stop``; spikes outside the edges are
122
+ dropped (numpy histogram semantics: half-open bins, last bin closed).
123
+
124
+ Returns
125
+ -------
126
+ xr.DataArray
127
+ dims (node_id, time); ``time`` = bin centres (ms); ``attrs['edges']`` = bin edges.
128
+ """
129
+ ids, ts = spike_arrays(spike_df)
130
+ if t_stop is None:
131
+ t_stop = ts.max() if len(ts) else t_start + bin_size
132
+ edges = np.arange(t_start, t_stop + bin_size, bin_size)
133
+ nodes = _node_ids(ids, node_ids)
134
+ row, ok = _row_index(ids, nodes)
135
+ counts, _, _ = np.histogram2d(row[ok], ts[ok], bins=(np.arange(len(nodes) + 1) - 0.5, edges))
136
+ counts = counts.astype(dtype)
137
+ if rate:
138
+ counts /= bin_size / 1000.0
139
+ return xr.DataArray(
140
+ counts,
141
+ dims=("node_id", "time"),
142
+ coords={"node_id": nodes, "time": edges[:-1] + bin_size / 2},
143
+ attrs={"edges": edges, "bin_size": bin_size, "units": "Hz" if rate else "spikes"},
144
+ )
145
+
146
+
147
+ def event_aligned(
148
+ binned: xr.DataArray, onsets: Sequence[float], window: Tuple[float, float]
149
+ ) -> xr.DataArray:
150
+ """
151
+ Cut a binned (node_id, time) array into event-aligned segments.
152
+
153
+ The segment of each onset starts at the bin whose left edge is closest to ``onset + window[0]`` and has
154
+ ``round((window[1] - window[0]) / bin_size)`` bins.
155
+
156
+ Returns
157
+ -------
158
+ xr.DataArray
159
+ dims (node_id, event, lag); ``lag`` = bin left edge relative to the onset (ms).
160
+ """
161
+ bs = float(binned.attrs["bin_size"])
162
+ edges = np.asarray(binned.attrs["edges"])
163
+ n = int(round((window[1] - window[0]) / bs))
164
+ segs = []
165
+ for t0 in onsets:
166
+ k = int(round((t0 + window[0] - edges[0]) / bs))
167
+ if k < 0 or k + n > binned.sizes["time"]:
168
+ raise ValueError(f"event at {t0} ms: window {window} runs past the binned range")
169
+ segs.append(binned.values[:, k : k + n])
170
+ lag = window[0] + bs * np.arange(n)
171
+ return xr.DataArray(
172
+ np.stack(segs, axis=1),
173
+ dims=("node_id", "event", "lag"),
174
+ coords={
175
+ "node_id": binned["node_id"].values,
176
+ "event": np.arange(len(onsets)),
177
+ "onset": ("event", np.asarray(onsets, float)),
178
+ "lag": lag,
179
+ },
180
+ attrs=dict(binned.attrs),
181
+ )
182
+
183
+
184
+ def peth(
185
+ spike_df: pd.DataFrame,
186
+ onsets: Sequence[float],
187
+ window: Tuple[float, float],
188
+ bin_size: float,
189
+ node_ids: Optional[Sequence[int]] = None,
190
+ per_node: bool = False,
191
+ ) -> xr.DataArray:
192
+ """
193
+ Peri-event time histogram in Hz, averaged over events (and over nodes unless ``per_node``).
194
+
195
+ Bins are half-open ``[lag, lag + bin_size)`` with ``lag`` from ``window[0]`` to the last edge <= ``window[1]``.
196
+ The population PETH divides by ``len(node_ids)`` (nodes without spikes count as zeros).
197
+
198
+ Returns
199
+ -------
200
+ xr.DataArray
201
+ dims (lag,) or (node_id, lag); ``lag`` = bin centres relative to the onset (ms).
202
+ """
203
+ lefts = np.arange(window[0], window[1] - bin_size + 1e-9 * abs(bin_size), bin_size)
204
+ counts = np.stack(
205
+ [
206
+ count_spikes_in_windows(spike_df, onsets, (lo, lo + bin_size), node_ids)
207
+ .sum("event")
208
+ .values
209
+ for lo in lefts
210
+ ],
211
+ axis=1,
212
+ )
213
+ nodes = _node_ids(np.asarray(spike_df["node_ids"]).astype(np.int64), node_ids)
214
+ hz = counts / (len(onsets) * bin_size / 1000.0)
215
+ lag = lefts + bin_size / 2
216
+ if per_node:
217
+ return xr.DataArray(
218
+ hz,
219
+ dims=("node_id", "lag"),
220
+ coords={"node_id": nodes, "lag": lag},
221
+ attrs={"units": "Hz"},
222
+ )
223
+ return xr.DataArray(
224
+ hz.sum(0) / len(nodes), dims=("lag",), coords={"lag": lag}, attrs={"units": "Hz per node"}
225
+ )
226
+
227
+
228
+ def baseline_zscore(
229
+ x: xr.DataArray,
230
+ baseline,
231
+ dim: str = "time",
232
+ sd_floor: Optional[float] = None,
233
+ sd_offset: Optional[float] = None,
234
+ ) -> xr.DataArray:
235
+ """
236
+ z-score each node against its own baseline samples along ``dim``.
237
+
238
+ Parameters
239
+ ----------
240
+ x : xr.DataArray
241
+ Data with a ``node_id`` dimension and ``dim``.
242
+ baseline : array-like of bool or int
243
+ Boolean mask or integer positions along ``dim`` that form the baseline.
244
+ sd_floor : float, optional
245
+ Lower bound for the baseline SD (e.g. the Poisson SD of a 1 Hz cell for one bin). Without a floor, nodes
246
+ with zero baseline SD get NaN.
247
+ sd_offset : float, optional
248
+ Added to the baseline SD instead (``(x - mean) / (sd + sd_offset)``, e.g. 1 Hz so silent cells stay finite).
249
+ Cannot be combined with ``sd_floor``.
250
+ """
251
+ if sd_floor is not None and sd_offset is not None:
252
+ raise ValueError("give sd_floor or sd_offset, not both")
253
+ axis = x.get_axis_num(dim)
254
+ vals = x.values
255
+ base = np.take(
256
+ vals,
257
+ np.where(np.asarray(baseline))[0]
258
+ if np.asarray(baseline).dtype == bool
259
+ else np.asarray(baseline),
260
+ axis=axis,
261
+ )
262
+ mu = base.mean(axis, keepdims=True) # plain numpy (no NaN skipping), same dtype as the input
263
+ sd = base.std(axis, keepdims=True)
264
+ if sd_offset is not None:
265
+ sd = sd + sd_offset
266
+ elif sd_floor is not None:
267
+ sd = np.maximum(sd, sd_floor)
268
+ else:
269
+ sd = np.where(sd == 0, np.nan, sd)
270
+ return x.copy(data=(vals - mu) / sd).assign_attrs({**x.attrs, "units": "z"})
271
+
272
+
273
+ # ----------------------------------------------------------------------------- per-cell classification
274
+ def classify_response(
275
+ resp,
276
+ base,
277
+ alpha: float = 0.05,
278
+ test: str = "poisson",
279
+ resp_duration: Optional[float] = None,
280
+ base_duration: Optional[float] = None,
281
+ ) -> Tuple[np.ndarray, np.ndarray]:
282
+ """
283
+ Per-node Up / Down / None classification of a response against a baseline.
284
+
285
+ Parameters
286
+ ----------
287
+ resp, base : array-like
288
+ 1-D total counts per node (``test='poisson'``), or 2-D (node, sample) counts per bin or trial.
289
+ test : {'poisson', 'ranksum'}
290
+ ``poisson``: exact conditional test of two Poisson rates on the summed counts,
291
+ ``n_resp ~ Binomial(n_resp + n_base, T_resp / (T_resp + T_base))`` under H0 (``scipy.stats.binomtest``);
292
+ keeps its power for sparse counts. ``ranksum``: two-sided Mann-Whitney U on the per-sample counts (2-D input).
293
+ resp_duration, base_duration : float, optional
294
+ Durations of the summed windows (any unit). Default: the number of samples (2-D input).
295
+
296
+ Returns
297
+ -------
298
+ classes : np.ndarray of str ('Up', 'Down', 'None')
299
+ pvalues : np.ndarray of float (NaN where a node has no spikes)
300
+ """
301
+ resp, base = np.asarray(resp, dtype=float), np.asarray(base, dtype=float)
302
+ two_d = resp.ndim == 2
303
+ if resp_duration is None or base_duration is None:
304
+ if not two_d:
305
+ raise ValueError("durations are required for 1-D (summed) counts")
306
+ resp_duration, base_duration = resp.shape[1], base.shape[1]
307
+ r_tot = resp.sum(1) if two_d else resp
308
+ b_tot = base.sum(1) if two_d else base
309
+ frac = resp_duration / (resp_duration + base_duration)
310
+ classes = np.full(len(r_tot), "None", dtype=object)
311
+ pvals = np.full(len(r_tot), np.nan)
312
+ for i, (r, b) in enumerate(zip(r_tot, b_tot)):
313
+ if r + b == 0:
314
+ continue
315
+ if test == "poisson":
316
+ p = stats.binomtest(int(r), int(r + b), frac).pvalue
317
+ up = r / resp_duration > b / base_duration
318
+ elif test == "ranksum":
319
+ if not two_d:
320
+ raise ValueError("test='ranksum' needs per-sample (2-D) counts")
321
+ p = stats.mannwhitneyu(resp[i], base[i], alternative="two-sided").pvalue
322
+ up = resp[i].mean() > base[i].mean()
323
+ else:
324
+ raise ValueError(f"unknown test {test!r}")
325
+ pvals[i] = p
326
+ if p < alpha:
327
+ classes[i] = "Up" if up else "Down"
328
+ return classes.astype(str), pvals
329
+
330
+
331
+ # ----------------------------------------------------------------------------- population responses
332
+ def population_response_z(
333
+ spike_df: pd.DataFrame,
334
+ onsets: Sequence[float],
335
+ window: Tuple[float, float],
336
+ baseline_window: Tuple[float, float],
337
+ bin_size: float,
338
+ node_ids: Sequence[int],
339
+ baseline_onsets: Optional[Sequence[float]] = None,
340
+ ) -> float:
341
+ """
342
+ Population z of the summed response of ``node_ids`` in ``window`` (expressed per ``bin_size`` bin) against the
343
+ distribution of summed population counts in the ``bin_size`` bins of ``baseline_window`` before each
344
+ ``baseline_onsets`` (default ``onsets``). Returns NaN for empty inputs or zero baseline SD.
345
+ """
346
+ if len(node_ids) == 0 or len(onsets) == 0:
347
+ return np.nan
348
+ bon = onsets if baseline_onsets is None else baseline_onsets
349
+ nb = int(round((baseline_window[1] - baseline_window[0]) / bin_size))
350
+ base_bins = np.concatenate(
351
+ [
352
+ count_spikes_in_windows(
353
+ spike_df,
354
+ bon,
355
+ (baseline_window[0] + k * bin_size, baseline_window[0] + (k + 1) * bin_size),
356
+ node_ids,
357
+ ).values.sum(0)
358
+ for k in range(nb)
359
+ ]
360
+ )
361
+ resp = count_spikes_in_windows(spike_df, onsets, window, node_ids).values.sum(0) * (
362
+ bin_size / (window[1] - window[0])
363
+ )
364
+ sd = base_bins.std()
365
+ return float((resp.mean() - base_bins.mean()) / sd) if sd > 0 else np.nan
366
+
367
+
368
+ def _pop_rates(spike_df, onsets, window, baseline_window, node_ids, baseline_onsets):
369
+ bon = onsets if baseline_onsets is None else baseline_onsets
370
+ r = count_spikes_in_windows(spike_df, onsets, window, node_ids).values
371
+ r0 = count_spikes_in_windows(spike_df, bon, baseline_window, node_ids).values
372
+ return r, r0, bon
373
+
374
+
375
+ def population_percent_change(
376
+ spike_df: pd.DataFrame,
377
+ onsets: Sequence[float],
378
+ window: Tuple[float, float],
379
+ baseline_window: Tuple[float, float],
380
+ node_ids: Sequence[int],
381
+ baseline_onsets: Optional[Sequence[float]] = None,
382
+ ) -> float:
383
+ """Percent change of the population rate in ``window`` vs ``baseline_window`` (per-event mean rates)."""
384
+ if len(node_ids) == 0 or len(onsets) == 0:
385
+ return np.nan
386
+ r, r0, bon = _pop_rates(spike_df, onsets, window, baseline_window, node_ids, baseline_onsets)
387
+ rate = r.sum() / (window[1] - window[0]) / len(onsets)
388
+ rate0 = r0.sum() / (baseline_window[1] - baseline_window[0]) / len(bon)
389
+ return float(100.0 * (rate / rate0 - 1.0)) if rate0 > 0 else np.nan
390
+
391
+
392
+ def population_rate_change(
393
+ spike_df: pd.DataFrame,
394
+ onsets: Sequence[float],
395
+ window: Tuple[float, float],
396
+ baseline_window: Tuple[float, float],
397
+ node_ids: Sequence[int],
398
+ baseline_onsets: Optional[Sequence[float]] = None,
399
+ ) -> float:
400
+ """Mean per-node rate increase (Hz) in ``window`` over ``baseline_window`` (windows in ms)."""
401
+ r, r0, _ = _pop_rates(spike_df, onsets, window, baseline_window, node_ids, baseline_onsets)
402
+ return float(
403
+ r.mean() / ((window[1] - window[0]) / 1000.0)
404
+ - r0.mean() / ((baseline_window[1] - baseline_window[0]) / 1000.0)
405
+ )
406
+
407
+
408
+ def response_auc(x: xr.DataArray, window: Tuple[float, float], dim: str = "lag") -> xr.DataArray:
409
+ """Mean of ``x`` over ``window`` (half-open, on the ``dim`` coordinate) times the window length (ms)."""
410
+ c = x[dim].values
411
+ sel = (c >= window[0]) & (c < window[1])
412
+ return x.isel({dim: np.where(sel)[0]}).mean(dim) * (window[1] - window[0])
413
+
414
+
415
+ # ----------------------------------------------------------------------------- Repa et al. (2001)
416
+ def repa_zscores(
417
+ spike_df: pd.DataFrame,
418
+ onsets: Sequence[float],
419
+ baseline_events: Sequence[int],
420
+ response_window: Tuple[float, float] = (0.0, 200.0),
421
+ bin_size: float = 10.0,
422
+ baseline_duration: float = 200.0,
423
+ node_ids: Optional[Sequence[int]] = None,
424
+ ) -> xr.DataArray:
425
+ """
426
+ Per-trial average z-scores (Repa et al. 2001).
427
+
428
+ Baseline mean and SD (population SD, ddof=0) of each node's counts in ``bin_size`` bins of the
429
+ ``baseline_duration`` before every onset in ``baseline_events`` (indices into ``onsets``); per trial, the
430
+ response-window bins are z-scored and averaged. Nodes with zero baseline SD get z = 0.
431
+
432
+ Returns
433
+ -------
434
+ xr.DataArray
435
+ dims (node_id, event); attrs ``mu`` / ``sigma`` as coordinates on node_id.
436
+ """
437
+ onsets = np.asarray(onsets, float)
438
+ base_on = onsets[np.asarray(baseline_events, dtype=int)]
439
+ base = np.concatenate(
440
+ [
441
+ count_spikes_in_windows(spike_df, base_on, (lo, lo + bin_size), node_ids).values
442
+ for lo in np.arange(-baseline_duration, 0.0, bin_size)
443
+ ],
444
+ axis=1,
445
+ )
446
+ mu, sigma = base.mean(1), base.std(1)
447
+ lefts = np.arange(response_window[0], response_window[1], bin_size)
448
+ resp = np.stack(
449
+ [
450
+ count_spikes_in_windows(spike_df, onsets, (lo, lo + bin_size), node_ids).values
451
+ for lo in lefts
452
+ ],
453
+ axis=2,
454
+ ) # node, event, bin
455
+ with np.errstate(invalid="ignore", divide="ignore"):
456
+ z = np.where(
457
+ sigma[:, None, None] > 0, (resp - mu[:, None, None]) / sigma[:, None, None], 0.0
458
+ ).mean(2)
459
+ nodes = count_spikes_in_windows(spike_df, onsets[:1], (0, 1), node_ids)["node_id"].values
460
+ return xr.DataArray(
461
+ z,
462
+ dims=("node_id", "event"),
463
+ coords={
464
+ "node_id": nodes,
465
+ "event": np.arange(len(onsets)),
466
+ "onset": ("event", onsets),
467
+ "mu": ("node_id", mu),
468
+ "sigma": ("node_id", sigma),
469
+ },
470
+ )
471
+
472
+
473
+ def _blocks(values, block_size, partial=True):
474
+ n = len(values) // block_size
475
+ out = [values[k * block_size : (k + 1) * block_size] for k in range(n)]
476
+ if partial and len(values) > n * block_size:
477
+ out.append(values[n * block_size :])
478
+ return out
479
+
480
+
481
+ def repa_max_block_difference(
482
+ z: xr.DataArray,
483
+ baseline_events: Sequence[int],
484
+ conditioning_events: Sequence[int],
485
+ block_size: int = 4,
486
+ ) -> pd.DataFrame:
487
+ """
488
+ Repa Fig. 4: per node, mean z of each conditioning block (``block_size`` trials; a remainder forms a last
489
+ partial block) minus the mean baseline z; the maximum over blocks is ``max_z_difference``.
490
+ """
491
+ zb = z.values[:, np.asarray(baseline_events, int)]
492
+ zc = z.values[:, np.asarray(conditioning_events, int)]
493
+ rows = []
494
+ for i, node in enumerate(z["node_id"].values):
495
+ zb_mean = np.mean(zb[i])
496
+ diffs = [np.mean(b) - zb_mean for b in _blocks(list(zc[i]), block_size)]
497
+ rows.append(
498
+ {
499
+ "node_id": node,
500
+ "z_avg_baseline": zb_mean,
501
+ "max_z_difference": max(diffs) if diffs else np.nan,
502
+ "z_diff_per_block": diffs,
503
+ "n_blocks": len(diffs),
504
+ }
505
+ )
506
+ return pd.DataFrame(rows)
507
+
508
+
509
+ def repa_plastic_cells(
510
+ z: xr.DataArray,
511
+ baseline_events: Sequence[int],
512
+ conditioning_events: Sequence[int],
513
+ block_size: int = 4,
514
+ alpha: float = 0.05,
515
+ min_sig_blocks: int = 1,
516
+ persistence_threshold: float = 0.75,
517
+ ) -> pd.DataFrame:
518
+ """
519
+ Repa et al. (2001) plastic cells: a node is plastic if at least ``min_sig_blocks`` full conditioning blocks
520
+ exceed the baseline z (one-tailed Welch-free t-test, ``scipy.stats.ttest_ind(..., alternative='greater')``).
521
+ For plastic nodes with >= 16 conditioning trials, persistence = (late 8 - baseline) / (early 8 - baseline);
522
+ ``long_lasting`` if >= ``persistence_threshold``, else ``transient``.
523
+ """
524
+ zb = z.values[:, np.asarray(baseline_events, int)]
525
+ zc = z.values[:, np.asarray(conditioning_events, int)]
526
+ rows = []
527
+ for i, node in enumerate(z["node_id"].values):
528
+ n_sig = 0
529
+ for blk in _blocks(list(zc[i]), block_size, partial=False):
530
+ if len(blk) < 2:
531
+ continue
532
+ p = stats.ttest_ind(blk, zb[i], alternative="greater").pvalue
533
+ if np.isfinite(p) and p < alpha:
534
+ n_sig += 1
535
+ plastic = n_sig >= min_sig_blocks
536
+ persistence, cell_type = np.nan, np.nan
537
+ if plastic and zc.shape[1] >= 16:
538
+ zb_mean = np.mean(zb[i])
539
+ early, late = np.mean(zc[i, :8]) - zb_mean, np.mean(zc[i, 8:16]) - zb_mean
540
+ if early != 0:
541
+ persistence = late / early
542
+ cell_type = "long_lasting" if persistence >= persistence_threshold else "transient"
543
+ rows.append(
544
+ {
545
+ "node_id": node,
546
+ "is_plastic": plastic,
547
+ "n_sig_blocks": n_sig,
548
+ "persistence": persistence,
549
+ "cell_type": cell_type,
550
+ }
551
+ )
552
+ return pd.DataFrame(rows)