sortingview 0.15.0__py3-none-any.whl

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 (119) hide show
  1. examples/example_autocorrelograms.py +33 -0
  2. examples/example_average_waveforms.py +82 -0
  3. examples/example_box_layout.py +70 -0
  4. examples/example_confusion_matrix.py +97 -0
  5. examples/example_cross_correlograms.py +36 -0
  6. examples/example_image.py +19 -0
  7. examples/example_markdown.py +41 -0
  8. examples/example_mountain_layout.py +54 -0
  9. examples/example_plotly.py +21 -0
  10. examples/example_position_plot.py +29 -0
  11. examples/example_raster_plot.py +34 -0
  12. examples/example_sorting_curation.py +33 -0
  13. examples/example_spike_amplitudes.py +47 -0
  14. examples/example_spike_locations.py +77 -0
  15. examples/example_splitter_layout.py +64 -0
  16. examples/example_tab_layout.py +44 -0
  17. examples/example_tiled_image.py +70 -0
  18. examples/example_timeseries_graph.py +49 -0
  19. examples/example_track_position_animation.py +76 -0
  20. examples/example_unit_locations.py +53 -0
  21. examples/example_unit_metrics_graph.py +44 -0
  22. examples/example_unit_similarity_matrix.py +35 -0
  23. examples/example_units_table.py +49 -0
  24. examples/helpers/compute_correlogram_data.py +66 -0
  25. examples/helpers/create_units_table.py +12 -0
  26. sortingview/SpikeSortingView/Figure.py +46 -0
  27. sortingview/SpikeSortingView/MultiTimeseries.py +29 -0
  28. sortingview/SpikeSortingView/SpikeSortingView.py +172 -0
  29. sortingview/SpikeSortingView/__init__.py +10 -0
  30. sortingview/SpikeSortingView/_autocorrelograms_view.py +22 -0
  31. sortingview/SpikeSortingView/_average_waveforms_view.py +32 -0
  32. sortingview/SpikeSortingView/_create_autocorrelograms.py +23 -0
  33. sortingview/SpikeSortingView/_create_average_waveforms.py +40 -0
  34. sortingview/SpikeSortingView/_create_electrode_geometry.py +19 -0
  35. sortingview/SpikeSortingView/_create_live_cross_correlograms.py +15 -0
  36. sortingview/SpikeSortingView/_create_mountain_layout.py +26 -0
  37. sortingview/SpikeSortingView/_create_raster_plot.py +32 -0
  38. sortingview/SpikeSortingView/_create_spike_amplitudes.py +35 -0
  39. sortingview/SpikeSortingView/_create_summary.py +34 -0
  40. sortingview/SpikeSortingView/_create_units_table.py +46 -0
  41. sortingview/SpikeSortingView/_cross_correlograms_view.py +24 -0
  42. sortingview/SpikeSortingView/_electrode_geometry_view.py +14 -0
  43. sortingview/SpikeSortingView/_raster_plot_view.py +31 -0
  44. sortingview/SpikeSortingView/_sorting_summary_view.py +32 -0
  45. sortingview/SpikeSortingView/_spike_amplitudes_view.py +31 -0
  46. sortingview/SpikeSortingView/_units_table_view.py +45 -0
  47. sortingview/SpikeSortingView/create_console_view.py +8 -0
  48. sortingview/SpikeSortingView/create_epochs.py +8 -0
  49. sortingview/SpikeSortingView/create_position_pdf_plot.py +54 -0
  50. sortingview/SpikeSortingView/create_position_plot.py +38 -0
  51. sortingview/SpikeSortingView/create_raw_traces_plot.py +8 -0
  52. sortingview/SpikeSortingView/create_spike_raster_plot.py +15 -0
  53. sortingview/SpikeSortingView/helpers/__init__.py +0 -0
  54. sortingview/SpikeSortingView/helpers/compute_correlogram_data.py +63 -0
  55. sortingview/SpikeSortingView/prepare_spikesortingview_data.py +258 -0
  56. sortingview/__init__.py +1 -0
  57. sortingview/figpack_backend.py +730 -0
  58. sortingview/sortingview_view_url.py +3 -0
  59. sortingview/version.py +2 -0
  60. sortingview/views/Autocorrelograms.py +34 -0
  61. sortingview/views/AverageWaveforms.py +77 -0
  62. sortingview/views/Box.py +32 -0
  63. sortingview/views/ConfusionMatrix.py +55 -0
  64. sortingview/views/CrossCorrelograms.py +36 -0
  65. sortingview/views/ElectrodeGeometry.py +19 -0
  66. sortingview/views/EphysTraces.py +23 -0
  67. sortingview/views/Image.py +39 -0
  68. sortingview/views/LayoutItem.py +39 -0
  69. sortingview/views/Markdown.py +19 -0
  70. sortingview/views/MountainLayout.py +37 -0
  71. sortingview/views/PlotlyFigure.py +20 -0
  72. sortingview/views/PositionPlot.py +58 -0
  73. sortingview/views/RasterPlot.py +36 -0
  74. sortingview/views/SortingCuration.py +18 -0
  75. sortingview/views/SortingCuration2.py +24 -0
  76. sortingview/views/SortingSelection.py +21 -0
  77. sortingview/views/SortingSummary.py +52 -0
  78. sortingview/views/SpikeAmplitudes.py +44 -0
  79. sortingview/views/SpikeLocations.py +59 -0
  80. sortingview/views/Splitter.py +26 -0
  81. sortingview/views/TabLayout.py +32 -0
  82. sortingview/views/TiledImage.py +116 -0
  83. sortingview/views/TimeseriesGraph.py +158 -0
  84. sortingview/views/UnitImages.py +41 -0
  85. sortingview/views/UnitLocations.py +36 -0
  86. sortingview/views/UnitMetricsGraph.py +47 -0
  87. sortingview/views/UnitSimilarityMatrix.py +34 -0
  88. sortingview/views/UnitsTable.py +51 -0
  89. sortingview/views/View.py +176 -0
  90. sortingview/views/__init__.py +31 -0
  91. sortingview/views/franklab/DecodedLinearPositionV1.py +43 -0
  92. sortingview/views/franklab/TrackPositionAnimationV1.py +187 -0
  93. sortingview/views/franklab/__init__.py +2 -0
  94. sortingview-0.15.0.dist-info/METADATA +25 -0
  95. sortingview-0.15.0.dist-info/RECORD +119 -0
  96. sortingview-0.15.0.dist-info/WHEEL +5 -0
  97. sortingview-0.15.0.dist-info/licenses/LICENSE +201 -0
  98. sortingview-0.15.0.dist-info/top_level.txt +3 -0
  99. tests/helpers/compute_correlogram_data.py +66 -0
  100. tests/test_autocorrelograms.py +32 -0
  101. tests/test_average_waveforms.py +71 -0
  102. tests/test_confusion_matrix.py +95 -0
  103. tests/test_cross_correlograms.py +35 -0
  104. tests/test_large_timeseries_graph.py +46 -0
  105. tests/test_layout.py +65 -0
  106. tests/test_markdown.py +38 -0
  107. tests/test_position_plot.py +27 -0
  108. tests/test_raster_plot.py +32 -0
  109. tests/test_sorting_curation_2.py +37 -0
  110. tests/test_sorting_selection.py +68 -0
  111. tests/test_spike_amplitudes.py +37 -0
  112. tests/test_spike_locations.py +74 -0
  113. tests/test_tab_layout.py +45 -0
  114. tests/test_tiled_image.py +68 -0
  115. tests/test_track_position_animation.py +73 -0
  116. tests/test_unit_locations.py +59 -0
  117. tests/test_unit_metrics_graph.py +41 -0
  118. tests/test_unit_similarity_matrix.py +33 -0
  119. tests/test_units_table.py +40 -0
@@ -0,0 +1,730 @@
1
+ """
2
+ Optional figpack backend for sortingview.
3
+
4
+ When the environment variable SORTINGVIEW_BACKEND=figpack is set, View.url()
5
+ converts the sortingview view tree into the equivalent figpack views, uploads
6
+ the figure to figpack, and returns the figpack figure URL instead of a figurl
7
+ URL. Code that calls .url() (for example spyglass) does not need to change.
8
+
9
+ Environment variables
10
+ ---------------------
11
+ SORTINGVIEW_BACKEND
12
+ "figurl" (default) or "figpack".
13
+ SORTINGVIEW_FIGPACK_MODE
14
+ "upload" (default): upload to figpack; requires FIGPACK_API_KEY.
15
+ "ephemeral": upload as a temporary figure; no API key needed.
16
+ "local": write the bundle to SORTINGVIEW_FIGPACK_LOCAL_DIR (or a temp dir)
17
+ and return the local directory path. For testing.
18
+ SORTINGVIEW_FIGPACK_STRICT
19
+ "1": raise if any view in the tree has no figpack equivalent.
20
+ Otherwise (default) warn and fall back to figurl for that figure.
21
+ FIGPACK_API_KEY, FIGPACK_BUCKET, FIGPACK_API_BASE_URL
22
+ Passed through to figpack. Use a bucket whose figures do not expire if the
23
+ URL will be stored in a database.
24
+
25
+ Requires: pip install figpack figpack_spike_sorting
26
+ (figpack_franklab for the Frank Lab track animation view, and
27
+ figpack_experimental for the 1D decoded position view).
28
+
29
+ Legacy SpikeSortingView.Figure objects (create_raw_traces_plot, and the
30
+ MountainLayout figures spyglass v0 builds from them) are converted too.
31
+ """
32
+
33
+ import base64
34
+ import json
35
+ import os
36
+ import tempfile
37
+ import time
38
+ import urllib.error
39
+ import urllib.request
40
+ import warnings
41
+ from typing import Any, Dict, Optional, Union
42
+
43
+ import numpy as np
44
+
45
+
46
+ class UnsupportedViewError(Exception):
47
+ """Raised when a sortingview view has no figpack equivalent."""
48
+
49
+
50
+ def backend() -> str:
51
+ return os.environ.get("SORTINGVIEW_BACKEND", "figurl").strip().lower()
52
+
53
+
54
+ def use_figpack() -> bool:
55
+ return backend() == "figpack"
56
+
57
+
58
+ def _strict() -> bool:
59
+ return os.environ.get("SORTINGVIEW_FIGPACK_STRICT", "0") == "1"
60
+
61
+
62
+ def _j(x):
63
+ """Convert numpy scalars/arrays (recursively) to plain Python for JSON-bound fields.
64
+
65
+ figurl's serializer accepted numpy types; figpack json.dumps some fields directly.
66
+ """
67
+ if isinstance(x, np.generic):
68
+ return x.item()
69
+ if isinstance(x, np.ndarray):
70
+ return x.tolist()
71
+ if isinstance(x, dict):
72
+ return {_j(k): _j(v) for k, v in x.items()}
73
+ if isinstance(x, (list, tuple)):
74
+ return [_j(v) for v in x]
75
+ return x
76
+
77
+
78
+ # ---------------------------------------------------------------------------
79
+ # Conversion
80
+ # ---------------------------------------------------------------------------
81
+
82
+
83
+ def to_figpack(view):
84
+ """Convert a sortingview View (and its children) into a figpack view.
85
+
86
+ Raises UnsupportedViewError if any view in the tree has no equivalent.
87
+ """
88
+ import figpack.views as fpv
89
+
90
+ from .views import (
91
+ Autocorrelograms,
92
+ AverageWaveforms,
93
+ Box,
94
+ CrossCorrelograms,
95
+ ElectrodeGeometry,
96
+ Image,
97
+ Markdown,
98
+ MountainLayout,
99
+ PlotlyFigure,
100
+ RasterPlot,
101
+ SortingCuration2,
102
+ SortingSummary,
103
+ SpikeAmplitudes,
104
+ SpikeLocations,
105
+ Splitter,
106
+ TabLayout,
107
+ TiledImage,
108
+ TimeseriesGraph,
109
+ UnitLocations,
110
+ UnitMetricsGraph,
111
+ UnitSimilarityMatrix,
112
+ UnitsTable,
113
+ )
114
+
115
+ # ---- layouts (figpack core) ----
116
+ if isinstance(view, Box):
117
+ return fpv.Box(
118
+ direction=view._direction,
119
+ show_titles=bool(view._show_titles),
120
+ items=[_layout_item(it) for it in view._items],
121
+ )
122
+ if isinstance(view, Splitter):
123
+ return fpv.Splitter(
124
+ direction=view._direction,
125
+ item1=_layout_item(view._items[0]),
126
+ item2=_layout_item(view._items[1]),
127
+ )
128
+ if isinstance(view, MountainLayout):
129
+ return fpv.MountainLayout(
130
+ items=[
131
+ fpv.MountainLayoutItem(
132
+ label=it.label,
133
+ view=to_figpack(it.view),
134
+ is_control=bool(it.is_control),
135
+ control_height=it.control_height,
136
+ )
137
+ for it in view._items
138
+ ]
139
+ )
140
+ if isinstance(view, TabLayout):
141
+ return fpv.TabLayout(items=[fpv.TabLayoutItem(label=it.label, view=to_figpack(it.view)) for it in view._items])
142
+
143
+ # ---- simple views (figpack core) ----
144
+ if isinstance(view, Markdown):
145
+ return fpv.Markdown(view._source)
146
+ if isinstance(view, PlotlyFigure):
147
+ return fpv.PlotlyFigure(view._fig)
148
+ if isinstance(view, Image):
149
+ return _convert_image(view)
150
+ if isinstance(view, TimeseriesGraph):
151
+ return _convert_timeseries_graph(view)
152
+ from .views import PositionPlot
153
+
154
+ if isinstance(view, PositionPlot):
155
+ return _convert_position_plot(view)
156
+
157
+ # ---- spike sorting views (figpack_spike_sorting) ----
158
+ if isinstance(
159
+ view,
160
+ (
161
+ Autocorrelograms,
162
+ AverageWaveforms,
163
+ CrossCorrelograms,
164
+ ElectrodeGeometry,
165
+ RasterPlot,
166
+ SortingCuration2,
167
+ SortingSummary,
168
+ SpikeAmplitudes,
169
+ SpikeLocations,
170
+ TiledImage,
171
+ UnitLocations,
172
+ UnitMetricsGraph,
173
+ UnitSimilarityMatrix,
174
+ UnitsTable,
175
+ ),
176
+ ):
177
+ return _convert_spike_sorting_view(view)
178
+
179
+ # ---- Frank Lab views (figpack_franklab) ----
180
+ from .views.franklab import DecodedLinearPositionData, TrackPositionAnimationV1
181
+
182
+ if isinstance(view, TrackPositionAnimationV1):
183
+ return _convert_track_animation(view)
184
+ if isinstance(view, DecodedLinearPositionData):
185
+ return _convert_decoded_linear_position(view)
186
+
187
+ raise UnsupportedViewError(f"No figpack equivalent for sortingview view type {type(view).__name__}")
188
+
189
+
190
+ _COLOR_CYCLE = ["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd", "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf"]
191
+
192
+
193
+ def _convert_position_plot(view):
194
+ """PositionPlot (position vs. time, one trace per dimension) -> TimeseriesGraph."""
195
+ import figpack.views as fpv
196
+
197
+ from .views.PositionPlot import _get_subsample_inds
198
+
199
+ timestamps = np.asarray(view.timestamps, dtype=np.float64)
200
+ positions = np.asarray(view.positions)
201
+ if positions.ndim == 1:
202
+ positions = positions.reshape(-1, 1)
203
+ if view.subsampling_frequency is not None:
204
+ inds = _get_subsample_inds(timestamps, view.subsampling_frequency)
205
+ timestamps = timestamps[inds]
206
+ positions = positions[inds, :]
207
+ G = fpv.TimeseriesGraph(y_label="Position")
208
+ for i, label in enumerate(view.dimension_labels):
209
+ color = _COLOR_CYCLE[i % len(_COLOR_CYCLE)]
210
+ y = positions[:, i].astype(np.float32)
211
+ if view.discontinuous:
212
+ G.add_marker_series(name=str(label), t=timestamps, y=y, color=color, radius=2)
213
+ else:
214
+ G.add_line_series(name=str(label), t=timestamps, y=y, color=color)
215
+ return G
216
+
217
+
218
+ def _convert_decoded_linear_position(view):
219
+ """DecodedLinearPositionData -> figpack_experimental LinearDecode.
220
+
221
+ sortingview stores the posterior sparsely (per-frame lists of bin index and
222
+ 0-255 value) over bins that need not be evenly spaced: a linearized track
223
+ has gaps between segments. LinearDecode takes a dense time x position
224
+ array on a uniform grid, so the bins are placed on a uniform grid with the
225
+ median bin spacing, leaving the gaps empty.
226
+ """
227
+ try:
228
+ from figpack_experimental.views import LinearDecode
229
+ except Exception as e: # ImportError, or FileNotFoundError when its JS bundle is missing
230
+ raise UnsupportedViewError(f"DecodedLinearPositionData requires the figpack_experimental extension ({e})") from e
231
+
232
+ sampling_frequency = view.sampling_frequency
233
+ if sampling_frequency is None:
234
+ sampling_frequency = 1000.0 # sortingview's frontend default
235
+ key = np.asarray(view.positions_key, dtype=np.float64)
236
+ frame_bounds = np.asarray(view.frame_bounds).astype(np.int64)
237
+ n_frames = len(frame_bounds)
238
+
239
+ cols, grid = _uniform_position_grid(key)
240
+ dense = np.zeros((n_frames, len(grid)), dtype=np.float32)
241
+ frame_of_entry = np.repeat(np.arange(n_frames), frame_bounds)
242
+ dense[frame_of_entry, cols[np.asarray(view.positions).astype(np.int64)]] = np.asarray(view.values, dtype=np.float32) / 255.0
243
+
244
+ observed = getattr(view, "observed_positions", None)
245
+ if observed is None:
246
+ observed = np.full(n_frames, np.nan, dtype=np.float32) # LinearDecode needs an array; NaN draws nothing
247
+ return LinearDecode(
248
+ start_time_sec=float(view.start_time_sec),
249
+ sampling_frequency_hz=float(sampling_frequency),
250
+ data=dense,
251
+ observed_positions=np.asarray(observed, dtype=np.float32).reshape(-1),
252
+ position_grid=grid.astype(np.float32),
253
+ )
254
+
255
+
256
+ def _uniform_position_grid(key: np.ndarray):
257
+ """Column of each bin on a uniform grid spanning the bins, and that grid."""
258
+ if len(key) < 2:
259
+ return np.zeros(len(key), dtype=np.int64), key.copy()
260
+ step = float(np.median(np.diff(key)))
261
+ if step <= 0:
262
+ raise UnsupportedViewError("positions_key must be increasing")
263
+ cols = np.round((key - key[0]) / step).astype(np.int64)
264
+ n_grid = int(cols[-1]) + 1
265
+ if n_grid > 10 * len(key) or len(np.unique(cols)) != len(cols):
266
+ # Too irregular for a uniform grid: show the bins evenly spaced instead
267
+ warnings.warn("sortingview: decoded position bins are irregular; showing them evenly spaced")
268
+ return np.arange(len(key), dtype=np.int64), np.linspace(key[0], key[-1], len(key))
269
+ return cols, key[0] + step * np.arange(n_grid)
270
+
271
+
272
+ # ---------------------------------------------------------------------------
273
+ # Legacy sortingview.SpikeSortingView.Figure (data dicts, no View classes)
274
+ # ---------------------------------------------------------------------------
275
+
276
+
277
+ def legacy_figure_to_figpack(figure):
278
+ """Convert a legacy SpikeSortingView.Figure (e.g. from create_raw_traces_plot)."""
279
+ return _convert_legacy_data(figure.data, label=figure.label)
280
+
281
+
282
+ def _convert_legacy_data(data: dict, *, label: str):
283
+ import figpack.views as fpv
284
+
285
+ t = data.get("type")
286
+ if t == "RawTracesPlot":
287
+ traces = np.asarray(data["traces"], dtype=np.float32)
288
+ if traces.ndim == 1:
289
+ traces = traces.reshape(-1, 1)
290
+ # MultiChannelTimeseries stacks the channels, like sortingview's raw traces plot
291
+ return fpv.MultiChannelTimeseries(
292
+ start_time_sec=float(data["startTimeSec"]),
293
+ sampling_frequency_hz=float(data["samplingFrequency"]),
294
+ data=traces,
295
+ channel_ids=[f"ch {i}" for i in range(traces.shape[1])],
296
+ y_label="Voltage",
297
+ )
298
+ if t == "ElectrodeGeometry":
299
+ return fpv.MatplotlibFigure(_electrode_geometry_figure(_j(data["channelLocations"])))
300
+ if t == "MountainLayout":
301
+ items = []
302
+ for v in data.get("views", []):
303
+ child = _resolve_legacy_child(v)
304
+ items.append(fpv.MountainLayoutItem(label=v.get("label", child[1]), view=_convert_legacy_data(child[0], label=child[1])))
305
+ return fpv.MountainLayout(items=items)
306
+ raise UnsupportedViewError(f"No figpack equivalent for legacy figure type {t!r}")
307
+
308
+
309
+ def _resolve_legacy_child(v: dict):
310
+ """Find a legacy MountainLayout child's data.
311
+
312
+ The layout only holds a kachery reference to each child's serialized data.
313
+ Prefer the live Figure object created in this process (matched by type and
314
+ label); otherwise load and deserialize the stored data.
315
+ """
316
+ from .SpikeSortingView.Figure import find_live_figure
317
+
318
+ fig = find_live_figure(type=v.get("type"), label=v.get("label"))
319
+ if fig is not None:
320
+ return fig.data, fig.label
321
+ uri = v.get("figureDataUri") or (f"sha1://{v['figureDataSha1']}" if v.get("figureDataSha1") else None)
322
+ if uri is None:
323
+ raise UnsupportedViewError("Legacy MountainLayout child has no data reference")
324
+ from figurl.core.serialize_wrapper import _deserialize
325
+
326
+ try:
327
+ import kachery_cloud as kcl # spyglass stores children with kachery_cloud
328
+
329
+ stored = kcl.load_json(uri)
330
+ except ImportError:
331
+ import kachery as ka
332
+
333
+ stored = ka.load_json(uri)
334
+ if stored is None:
335
+ raise UnsupportedViewError(f"Could not load legacy figure data {uri}")
336
+ return _deserialize(stored), v.get("label", "")
337
+
338
+
339
+ def _layout_item(it):
340
+ import figpack.views as fpv
341
+
342
+ return fpv.LayoutItem(
343
+ to_figpack(it.view),
344
+ stretch=it.stretch,
345
+ min_size=it.min_size,
346
+ max_size=it.max_size,
347
+ title=it.title,
348
+ collapsible=bool(it.collapsible),
349
+ )
350
+
351
+
352
+ def _convert_image(view):
353
+ import figpack.views as fpv
354
+
355
+ url = view._url
356
+ prefix = "base64,"
357
+ if url.startswith("data:") and prefix in url:
358
+ return fpv.Image(base64.b64decode(url[url.index(prefix) + len(prefix) :]))
359
+ raise UnsupportedViewError("Image views that reference a remote URL are not supported by the figpack backend")
360
+
361
+
362
+ def _convert_timeseries_graph(view):
363
+ import figpack.views as fpv
364
+
365
+ kwargs: Dict[str, Any] = {}
366
+ if view._legend_opts is not None:
367
+ kwargs["legend_opts"] = view._legend_opts
368
+ if view._y_range is not None:
369
+ kwargs["y_range"] = list(view._y_range)
370
+ if view._hide_x_gridlines is not None:
371
+ kwargs["hide_x_gridlines"] = bool(view._hide_x_gridlines)
372
+ if view._hide_y_gridlines is not None:
373
+ kwargs["hide_y_gridlines"] = bool(view._hide_y_gridlines)
374
+ G = fpv.TimeseriesGraph(**kwargs)
375
+
376
+ datasets = {ds._name: ds._data for ds in view._datasets}
377
+ offset = view._time_offset
378
+
379
+ def _t(arr):
380
+ arr = np.asarray(arr)
381
+ if offset is not None:
382
+ # sortingview subtracts an offset to fit float32; restore absolute time
383
+ arr = arr.astype(np.float64) + float(offset)
384
+ return arr
385
+
386
+ for s in view._series:
387
+ data = datasets[s._dataset]
388
+ t = _t(data[s._encoding["t"]])
389
+ y = np.asarray(data[s._encoding["y"]])
390
+ attrs = s._attributes or {}
391
+ name = s._title or s._dataset
392
+ color = attrs.get("color", "blue")
393
+ if s._type == "line":
394
+ kw = {}
395
+ if "width" in attrs:
396
+ kw["width"] = attrs["width"]
397
+ if "dash" in attrs:
398
+ kw["dash"] = attrs["dash"]
399
+ G.add_line_series(name=name, t=t, y=y, color=color, **kw)
400
+ elif s._type == "marker":
401
+ kw = {}
402
+ if "radius" in attrs:
403
+ kw["radius"] = attrs["radius"]
404
+ if "shape" in attrs:
405
+ kw["shape"] = attrs["shape"]
406
+ G.add_marker_series(name=name, t=t, y=y, color=color, **kw)
407
+ elif s._type == "interval":
408
+ # sortingview stores intervals interleaved: t = [s0, e0, s1, e1, ...]
409
+ G.add_interval_series(name=name, t_start=t[0::2], t_end=t[1::2], color=color)
410
+ else:
411
+ raise UnsupportedViewError(f"TimeseriesGraph series type {s._type!r} is not supported")
412
+ return G
413
+
414
+
415
+ def _convert_spike_sorting_view(view):
416
+ import figpack.views as fpv
417
+ import figpack_spike_sorting.views as ssv
418
+
419
+ from . import views as vv
420
+
421
+ if isinstance(view, vv.Autocorrelograms):
422
+ return ssv.Autocorrelograms(
423
+ autocorrelograms=[ssv.AutocorrelogramItem(unit_id=_j(a.unit_id), bin_edges_sec=a.bin_edges_sec, bin_counts=a.bin_counts) for a in view._autocorrelograms]
424
+ )
425
+ if isinstance(view, vv.CrossCorrelograms):
426
+ return ssv.CrossCorrelograms(
427
+ cross_correlograms=[
428
+ ssv.CrossCorrelogramItem(unit_id1=_j(c.unit_id1), unit_id2=_j(c.unit_id2), bin_edges_sec=c.bin_edges_sec, bin_counts=c.bin_counts) for c in view._cross_correlograms
429
+ ],
430
+ hide_unit_selector=bool(view._hide_unit_selector),
431
+ )
432
+ if isinstance(view, vv.AverageWaveforms):
433
+ return ssv.AverageWaveforms(
434
+ average_waveforms=[
435
+ ssv.AverageWaveformItem(
436
+ unit_id=_j(a.unit_id),
437
+ channel_ids=_j(a.channel_ids),
438
+ waveform=a.waveform,
439
+ waveform_std_dev=a.waveform_std_dev,
440
+ waveform_percentiles=a.waveform_percentiles,
441
+ )
442
+ for a in view._average_waveforms
443
+ ],
444
+ channel_locations=_j(view._channel_locations),
445
+ )
446
+ if isinstance(view, vv.RasterPlot):
447
+ return ssv.RasterPlot(
448
+ start_time_sec=view._start_time_sec,
449
+ end_time_sec=view._end_time_sec,
450
+ plots=[ssv.RasterPlotItem(unit_id=_j(p.unit_id), spike_times_sec=p.spike_times_sec) for p in view._plots],
451
+ )
452
+ if isinstance(view, vv.SpikeAmplitudes):
453
+ return ssv.SpikeAmplitudes(
454
+ start_time_sec=view._start_time_sec,
455
+ end_time_sec=view._end_time_sec,
456
+ plots=[ssv.SpikeAmplitudesItem(unit_id=_j(p.unit_id), spike_times_sec=p.spike_times_sec, spike_amplitudes=p.spike_amplitudes) for p in view._plots],
457
+ )
458
+ if isinstance(view, vv.SpikeLocations):
459
+ return ssv.SpikeLocations(
460
+ units=[ssv.SpikeLocationsItem(unit_id=_j(u.unit_id), spike_times_sec=u.spike_times_sec, x_locations=u.x_locations, y_locations=u.y_locations) for u in view._units],
461
+ x_range=view._x_range,
462
+ y_range=view._y_range,
463
+ channel_locations=_j(view._channel_locations),
464
+ hide_unit_selector=bool(view._hide_unit_selector),
465
+ disable_auto_rotate=bool(view._disable_auto_rotate),
466
+ )
467
+ if isinstance(view, vv.UnitLocations):
468
+ return ssv.UnitLocations(
469
+ units=[ssv.UnitLocationsItem(unit_id=_j(u.unit_id), x=_j(u.x), y=_j(u.y)) for u in view._units],
470
+ channel_locations=_j(view._channel_locations),
471
+ disable_auto_rotate=bool(view._disable_auto_rotate),
472
+ )
473
+ if isinstance(view, vv.UnitsTable):
474
+ return ssv.UnitsTable(
475
+ columns=[ssv.UnitsTableColumn(key=c.key, label=c.label, dtype=c.dtype) for c in view._columns],
476
+ rows=[ssv.UnitsTableRow(unit_id=_j(r.unit_id), values=_j(r.values)) for r in view._rows],
477
+ similarity_scores=_similarity_scores(view._similarity_scores),
478
+ )
479
+ if isinstance(view, vv.UnitSimilarityMatrix):
480
+ return ssv.UnitSimilarityMatrix(unit_ids=_j(view._unit_ids), similarity_scores=_similarity_scores(view._similarity_scores))
481
+ if isinstance(view, vv.UnitMetricsGraph):
482
+ return ssv.UnitMetricsGraph(
483
+ units=[ssv.UnitMetricsGraphUnit(unit_id=_j(u.unit_id), values=_j(u.values)) for u in view._units],
484
+ metrics=[ssv.UnitMetricsGraphMetric(key=m.key, label=m.label, dtype=m.dtype) for m in view._metrics],
485
+ )
486
+ if isinstance(view, vv.TiledImage):
487
+ return ssv.TiledImage(
488
+ tile_size=view._tile_size,
489
+ layers=[ssv.TiledImageLayer(label=layer.label, data=layer.data) for layer in view._layers],
490
+ verbose=view._verbose,
491
+ )
492
+ if isinstance(view, vv.SortingCuration2):
493
+ kwargs = {}
494
+ if view._label_choices is not None:
495
+ kwargs["default_label_options"] = list(view._label_choices)
496
+ return ssv.SortingCuration(**kwargs)
497
+
498
+ # ---- stand-ins until figpack_spike_sorting has these views ----
499
+ if isinstance(view, vv.SortingSummary):
500
+ return fpv.Markdown(_sorting_summary_markdown(view))
501
+ if isinstance(view, vv.ElectrodeGeometry):
502
+ # figpack's UnitLocations viewer rejects an empty unit list, so draw the layout with matplotlib
503
+ return fpv.MatplotlibFigure(_electrode_geometry_figure(_j(view.channel_locations)))
504
+
505
+ raise UnsupportedViewError(f"No figpack equivalent for {type(view).__name__}")
506
+
507
+
508
+ def _similarity_scores(scores):
509
+ if scores is None:
510
+ return None
511
+ import figpack_spike_sorting.views as ssv
512
+
513
+ return [ssv.UnitSimilarityScore(unit_id1=_j(s.unit_id1), unit_id2=_j(s.unit_id2), similarity=_j(s.similarity)) for s in scores]
514
+
515
+
516
+ def _electrode_geometry_figure(channel_locations: dict):
517
+ import matplotlib
518
+
519
+ matplotlib.use("Agg")
520
+ import matplotlib.pyplot as plt
521
+
522
+ fig, ax = plt.subplots(figsize=(4, 6))
523
+ ids = list(channel_locations.keys())
524
+ xy = np.array([channel_locations[k][:2] for k in ids], dtype=float).reshape(-1, 2)
525
+ ax.scatter(xy[:, 0], xy[:, 1], s=60, marker="s", color="#888")
526
+ for k, (x, y) in zip(ids, xy):
527
+ ax.annotate(str(k), (x, y), textcoords="offset points", xytext=(6, 0), va="center", fontsize=8)
528
+ ax.set_aspect("equal", adjustable="datalim")
529
+ ax.set_xlabel("x (µm)")
530
+ ax.set_ylabel("y (µm)")
531
+ ax.set_title("Electrode geometry")
532
+ fig.tight_layout()
533
+ plt.close(fig)
534
+ return fig
535
+
536
+
537
+ def _sorting_summary_markdown(view) -> str:
538
+ duration_sec = view.num_frames / view.sampling_frequency if view.sampling_frequency else float("nan")
539
+ lines = [
540
+ "## Sorting summary",
541
+ "",
542
+ "| | |",
543
+ "|---|---|",
544
+ ]
545
+ if view.recording_description:
546
+ lines.append(f"| Recording | {view.recording_description} |")
547
+ if view.sorting_description:
548
+ lines.append(f"| Sorting | {view.sorting_description} |")
549
+ lines += [
550
+ f"| Units | {len(view.unit_ids)} |",
551
+ f"| Channels | {len(view.channel_ids)} |",
552
+ f"| Sampling frequency | {view.sampling_frequency:g} Hz |",
553
+ f"| Duration | {duration_sec:.1f} s ({view.num_frames} frames, {view.num_segments} segment(s)) |",
554
+ f"| Noise level | {view.noise_level:.3g} |",
555
+ ]
556
+ return "\n".join(lines)
557
+
558
+
559
+ def _convert_track_animation(view):
560
+ try:
561
+ from figpack_franklab.views import TrackAnimation
562
+ except Exception as e: # ImportError, or FileNotFoundError when its JS bundle is missing
563
+ raise UnsupportedViewError(f"TrackPositionAnimationV1 requires a working figpack_franklab install ({e})") from e
564
+
565
+ timestamps = np.asarray(view.timestamps)
566
+ n = len(timestamps)
567
+ head_direction = np.asarray(view.head_direction) if view.head_direction is not None else np.zeros(n, dtype=np.float32)
568
+ d = view.decoded_data
569
+ if d is not None:
570
+ decoded = dict(
571
+ bin_width=d.bin_width,
572
+ bin_height=d.bin_height,
573
+ xcount=int(d.x_count),
574
+ ycount=int(d.y_count),
575
+ xmin=d.x_min,
576
+ ymin=d.y_min,
577
+ values=np.asarray(d.values),
578
+ locations=np.asarray(d.locations),
579
+ frame_bounds=np.asarray(d.frame_bounds),
580
+ )
581
+ else:
582
+ decoded = dict(
583
+ bin_width=view.track_bin_width,
584
+ bin_height=view.track_bin_height,
585
+ xcount=0,
586
+ ycount=0,
587
+ xmin=view.x_min,
588
+ ymin=view.y_min,
589
+ values=np.zeros(0, dtype=np.uint8),
590
+ locations=np.zeros(0, dtype=np.int32),
591
+ frame_bounds=np.zeros(n, dtype=np.int32),
592
+ )
593
+ return TrackAnimation(
594
+ **decoded,
595
+ head_direction=head_direction,
596
+ positions=np.asarray(view.positions),
597
+ timestamps=timestamps,
598
+ track_bin_corners=np.asarray(view.track_bin_ul_corners),
599
+ sampling_frequency_hz=float(view.sampling_frequency_hz) if view.sampling_frequency_hz is not None else 60.0,
600
+ timestamp_start=float(view.timestamp_start) if view.timestamp_start is not None else 0.0,
601
+ total_recording_frame_length=int(view.total_recording_frame_length),
602
+ track_bin_height=view.track_bin_height,
603
+ track_bin_width=view.track_bin_width,
604
+ xmax=view.x_max,
605
+ ymax=view.y_max,
606
+ )
607
+
608
+
609
+ # ---------------------------------------------------------------------------
610
+ # Curation
611
+ # ---------------------------------------------------------------------------
612
+
613
+
614
+ def _initial_curation_from_state(state: Optional[dict]) -> Optional[dict]:
615
+ """figurl passes the starting curation as a URI in the URL state."""
616
+ if not state:
617
+ return None
618
+ uri = state.get("sortingCuration") or state.get("initialSortingCuration")
619
+ if not uri:
620
+ return None
621
+ return load_curation(uri)
622
+
623
+
624
+ def load_curation(uri_or_url: str) -> dict:
625
+ """Load a sorting curation ({labelsByUnit, mergeGroups, ...}).
626
+
627
+ Accepts a kachery URI (sha1://...), a GitHub URI (gh://...), or a figpack
628
+ figure URL, in which case the curation saved in the figure is returned.
629
+ """
630
+ if uri_or_url.startswith("http://") or uri_or_url.startswith("https://"):
631
+ base = uri_or_url.split("?")[0]
632
+ if base.endswith("/index.html"):
633
+ base = base[: -len("/index.html")]
634
+ base = base.rstrip("/")
635
+ # A cache-buster so a just-saved curation is not served stale from the
636
+ # CDN (the figpack viewer does the same), and a User-Agent because the
637
+ # figpack servers reject Python's default one
638
+ from .version import __version__
639
+
640
+ req = urllib.request.Request(
641
+ f"{base}/annotations.json?cb={int(time.time() * 1000)}",
642
+ headers={"User-Agent": f"sortingview/{__version__}"},
643
+ )
644
+ try:
645
+ with urllib.request.urlopen(req) as resp:
646
+ saved = json.loads(resp.read().decode("utf-8"))
647
+ except urllib.error.HTTPError as e:
648
+ if e.code == 404:
649
+ return {} # nothing saved yet
650
+ # Never turn an error into an empty curation: that would be
651
+ # recorded downstream as "no labels, no merges"
652
+ raise RuntimeError(f"Could not load curation from {base}/annotations.json (HTTP {e.code})") from e
653
+ text = saved.get("annotations", {}).get("/", {}).get("sorting_curation")
654
+ return json.loads(text) if text else {}
655
+ import kachery as ka
656
+
657
+ return ka.load_json(uri_or_url)
658
+
659
+
660
+ def _annotations_json(curation: dict) -> dict:
661
+ return {"annotations": {"/": {"sorting_curation": json.dumps(curation)}}}
662
+
663
+
664
+ # ---------------------------------------------------------------------------
665
+ # Publishing
666
+ # ---------------------------------------------------------------------------
667
+
668
+
669
+ def figpack_url(view, *, label: str, state: Union[dict, None] = None) -> str:
670
+ """Convert a sortingview view to figpack, publish it, and return its URL."""
671
+ fp_view = to_figpack(view)
672
+ curation = _initial_curation_from_state(state)
673
+ return publish(fp_view, title=label, initial_curation=curation)
674
+
675
+
676
+ def publish(fp_view, *, title: str, initial_curation: Optional[dict] = None) -> str:
677
+ from figpack.core._bundle_utils import prepare_figure_bundle
678
+
679
+ mode = os.environ.get("SORTINGVIEW_FIGPACK_MODE", "upload").strip().lower()
680
+ if mode not in ("upload", "ephemeral", "local"):
681
+ raise ValueError(f"Invalid SORTINGVIEW_FIGPACK_MODE: {mode!r}")
682
+
683
+ if mode == "local":
684
+ parent = os.environ.get("SORTINGVIEW_FIGPACK_LOCAL_DIR") or tempfile.gettempdir()
685
+ os.makedirs(parent, exist_ok=True)
686
+ out_dir = tempfile.mkdtemp(prefix="sortingview_figpack_", dir=parent)
687
+ _write_bundle(prepare_figure_bundle, fp_view, out_dir, title, initial_curation)
688
+ return out_dir
689
+
690
+ from figpack.core._upload_bundle import _upload_bundle
691
+
692
+ api_key = os.environ.get("FIGPACK_API_KEY")
693
+ ephemeral = mode == "ephemeral"
694
+ if not ephemeral and not api_key:
695
+ raise EnvironmentError("SORTINGVIEW_BACKEND=figpack requires FIGPACK_API_KEY (or SORTINGVIEW_FIGPACK_MODE=ephemeral)")
696
+ with tempfile.TemporaryDirectory(prefix="sortingview_figpack_") as tmpdir:
697
+ _write_bundle(prepare_figure_bundle, fp_view, tmpdir, title, initial_curation)
698
+ return _upload_bundle(tmpdir, api_key, title=title, ephemeral=ephemeral, use_consolidated_metadata_only=True)
699
+
700
+
701
+ def _write_bundle(prepare_figure_bundle, fp_view, out_dir: str, title: str, initial_curation: Optional[dict]):
702
+ prepare_figure_bundle(fp_view, out_dir, title=title, description=f"Generated by sortingview ({title})")
703
+ if initial_curation:
704
+ # The figpack viewer loads <figure>/annotations.json on open; seeding it
705
+ # here gives the figure its starting curation.
706
+ with open(os.path.join(out_dir, "annotations.json"), "w") as f:
707
+ json.dump(_annotations_json(initial_curation), f)
708
+
709
+
710
+ def try_figpack_url_legacy(figure) -> Optional[str]:
711
+ """Like try_figpack_url, for a legacy SpikeSortingView.Figure."""
712
+ try:
713
+ fp_view = legacy_figure_to_figpack(figure)
714
+ except UnsupportedViewError as e:
715
+ if _strict():
716
+ raise
717
+ warnings.warn(f"sortingview: falling back to figurl ({e})")
718
+ return None
719
+ return publish(fp_view, title=figure.label)
720
+
721
+
722
+ def try_figpack_url(view, *, label: str, state: Union[dict, None] = None) -> Optional[str]:
723
+ """Return a figpack URL, or None if the view tree can't be converted (non-strict mode)."""
724
+ try:
725
+ return figpack_url(view, label=label, state=state)
726
+ except UnsupportedViewError as e:
727
+ if _strict():
728
+ raise
729
+ warnings.warn(f"sortingview: falling back to figurl ({e})")
730
+ return None