neuroseq 0.30.0__py3-none-any.whl

neuroseq/__init__.py

@@ -0,0 +1,5 @@
+__all__ = [
+    "__version__",
+]
+
+__version__ = "0.30.0"

neuroseq/__main__.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import logging
+import pathlib
+import signal
+import sys
+from collections.abc import Callable
+from types import FrameType
+from typing import Any
+
+import click
+
+from neuroseq.cellpose_test_data import save_cellpose_test_data
+
+
+def _install_interrupt_handlers(
+    app: Any,
+    *,
+    timer_factory: Callable[[Any], Any] | None = None,
+    signal_module: Any = signal,
+) -> Any | None:
+    """Keep Ctrl-C responsive while the Qt event loop is running."""
+    if sys.platform == "win32":
+        return None
+
+    if timer_factory is None:
+        from qtpy import QtCore
+
+        timer = QtCore.QTimer(app)
+    else:
+        timer = timer_factory(app)
+
+    def _quit_on_signal(signum: int, _frame: FrameType | None) -> None:
+        logging.getLogger(__name__).info(
+            "Received signal %s, quitting GUI event loop", signum
+        )
+        app.quit()
+
+    signal_module.signal(signal_module.SIGINT, _quit_on_signal)
+    signal_module.signal(signal_module.SIGTERM, _quit_on_signal)
+    timer.setInterval(200)
+    timer.timeout.connect(lambda: None)
+    timer.start()
+    return timer
+
+
+@click.command()
+@click.option(
+    "--log-level",
+    default="INFO",
+    type=click.Choice(
+        ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], case_sensitive=False
+    ),
+    help="Log level",
+    show_default=True,
+    show_choices=True,
+)
+@click.option(
+    "--log-file",
+    default=None,
+    type=click.Path(path_type=pathlib.Path, dir_okay=False, writable=True),
+    help="Log to this file instead of the console",
+    show_default=True,
+)
+@click.option(
+    "--generate-cellpose-test-data",
+    "test_cellpose_image_path",
+    default=None,
+    type=click.Path(path_type=pathlib.Path, dir_okay=False, writable=True),
+    help=(
+        "Generate a synthetic Cellpose test TIFF at this path and matching "
+        "segmentation .npy, then exit."
+    ),
+)
+@click.option(
+    "--cellpose-segmentation-output",
+    "test_cellpose_segmentation_path",
+    default=None,
+    type=click.Path(path_type=pathlib.Path, dir_okay=False, writable=True),
+    help=(
+        "Optional output path for generated Cellpose segmentation .npy "
+        "(requires --generate-cellpose-test-data)."
+    ),
+)
+@click.option(
+    "--cellpose-grid-rows",
+    default=10,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Number of target rows in generated Cellpose test data.",
+)
+@click.option(
+    "--cellpose-grid-cols",
+    default=10,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Number of target columns in generated Cellpose test data.",
+)
+@click.option(
+    "--cellpose-radius",
+    default=10,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Circle radius in pixels for generated Cellpose test data.",
+)
+@click.option(
+    "--cellpose-gap",
+    default=10,
+    type=click.IntRange(min=0),
+    show_default=True,
+    help="Gap in pixels between adjacent circles in generated Cellpose test data.",
+)
+@click.option(
+    "--cellpose-square-size",
+    default=None,
+    type=click.IntRange(min=1),
+    help=(
+        "Optional square output size in pixels for generated Cellpose test data. "
+        "When set, radius and gap are auto-fitted while preserving rows/cols."
+    ),
+)
+@click.option(
+    "--cellpose-preserve-radius-gap/--cellpose-auto-fit-radius-gap",
+    default=False,
+    show_default=True,
+    help=(
+        "When --cellpose-square-size is set, preserve the provided "
+        "--cellpose-radius and --cellpose-gap instead of auto-fitting them."
+    ),
+)
+@click.option(
+    "--cellpose-preserve-radius-auto-gap",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help=(
+        "When --cellpose-square-size is set, preserve --cellpose-radius and "
+        "auto-fit only --cellpose-gap."
+    ),
+)
+@click.argument("filename", required=False)
+def main(
+    log_level: str,
+    log_file: pathlib.Path | None,
+    test_cellpose_image_path: pathlib.Path | None,
+    test_cellpose_segmentation_path: pathlib.Path | None,
+    cellpose_grid_rows: int,
+    cellpose_grid_cols: int,
+    cellpose_radius: int,
+    cellpose_gap: int,
+    cellpose_square_size: int | None,
+    cellpose_preserve_radius_gap: bool,
+    cellpose_preserve_radius_auto_gap: bool,
+    filename: str | None,
+) -> None:
+    if test_cellpose_segmentation_path is not None and test_cellpose_image_path is None:
+        raise click.UsageError(
+            "--cellpose-segmentation-output requires --generate-cellpose-test-data"
+        )
+    if cellpose_preserve_radius_gap and cellpose_square_size is None:
+        raise click.UsageError(
+            "--cellpose-preserve-radius-gap requires --cellpose-square-size"
+        )
+    if cellpose_preserve_radius_auto_gap and cellpose_square_size is None:
+        raise click.UsageError(
+            "--cellpose-preserve-radius-auto-gap requires --cellpose-square-size"
+        )
+    if cellpose_preserve_radius_gap and cellpose_preserve_radius_auto_gap:
+        raise click.UsageError(
+            "--cellpose-preserve-radius-gap and --cellpose-preserve-radius-auto-gap "
+            "cannot be used together"
+        )
+
+    if test_cellpose_image_path is not None:
+        image_path, segmentation_path = save_cellpose_test_data(
+            test_cellpose_image_path,
+            segmentation_path=test_cellpose_segmentation_path,
+            rows=cellpose_grid_rows,
+            cols=cellpose_grid_cols,
+            radius=cellpose_radius,
+            gap=cellpose_gap,
+            square_size=cellpose_square_size,
+            preserve_radius_gap=cellpose_preserve_radius_gap,
+            preserve_radius_auto_gap=cellpose_preserve_radius_auto_gap,
+        )
+        click.echo(
+            "Generated Cellpose test data:\n"
+            f"- image: {image_path}\n"
+            f"- segmentation: {segmentation_path}"
+        )
+        return
+
+    from neuroseq.utils import init_brian2_logging
+
+    init_brian2_logging()
+    logging.basicConfig(
+        level=log_level,
+        format="%(asctime)s :: %(levelname)s :: %(name)s :: %(funcName)s :: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        filename=log_file,
+    )
+    from qtpy import API_NAME
+    from qtpy import QtCore
+    from qtpy import QtGui
+    from qtpy import QtWidgets
+
+    from neuroseq.gui import Gui
+    from neuroseq.gui_settings import GuiSettings
+    from neuroseq.project import Project
+    from neuroseq.startup_dialog import StartupDialog
+    from neuroseq.theme import apply_app_theme
+
+    msg = f"Launching {API_NAME} GUI with {log_level} logging to {log_file if log_file else 'console'}"
+    click.echo(msg)
+    logging.getLogger(__name__).info(msg)
+
+    # Keep icon raster sizes on integer scale steps to reduce blur on HiDPI displays.
+    if hasattr(QtGui.QGuiApplication, "setHighDpiScaleFactorRoundingPolicy"):
+        QtGui.QGuiApplication.setHighDpiScaleFactorRoundingPolicy(
+            QtCore.Qt.HighDpiScaleFactorRoundingPolicy.RoundPreferFloor
+        )
+    if hasattr(QtCore.Qt.ApplicationAttribute, "AA_UseHighDpiPixmaps"):
+        QtWidgets.QApplication.setAttribute(
+            QtCore.Qt.ApplicationAttribute.AA_UseHighDpiPixmaps,
+            True,
+        )
+
+    app = QtWidgets.QApplication(sys.argv)
+    app._interrupt_timer = _install_interrupt_handlers(app)
+
+    initial_project: str | pathlib.Path | Project | None = filename
+    if initial_project is None:
+        settings = GuiSettings()
+        # Applied to the whole application (not just the eventual main
+        # window) so the startup dialog itself already matches the user's
+        # persisted theme, instead of appearing unthemed until a project
+        # is chosen.
+        apply_app_theme(app, settings.theme)
+        startup_dialog = StartupDialog(settings)
+        if not startup_dialog.exec():
+            logging.getLogger(__name__).info(
+                "Startup dialog dismissed without a choice, exiting"
+            )
+            return
+        initial_project = (
+            startup_dialog.chosen_filename or startup_dialog.chosen_project
+        )
+
+    gui = Gui(filename=initial_project)
+    gui.show()
+    logging.getLogger(__name__).info("GUI initialized, entering Qt event loop")
+    app.exec()
+
+
+if __name__ == "__main__":
+    main()

neuroseq/add_experiment_data_dialog.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from qtpy import QtWidgets
+
+from neuroseq.data import Data
+from neuroseq.data import Experiment
+from neuroseq.data import SpikeData
+from neuroseq.data import SynapseData
+from neuroseq.data import TraceData
+from neuroseq.project import Project
+
+
+def describe_data(data: Data) -> str:
+    if isinstance(data, TraceData):
+        return f"Trace data '{data.name}': {data.traces.shape[0]} neurons, {data.traces.shape[1]} timestamps"
+    elif isinstance(data, SpikeData):
+        return f"Spike data '{data.name}': {len(data.spike_indices)} spikes"
+    elif isinstance(data, SynapseData):
+        return f"Synapse data '{data.name}': {data.values.shape[0]}x{data.values.shape[1]} synapses, {data.values.shape[2]} timestamps"
+    return ""
+
+
+def describe_experiment(experiment: Experiment) -> str:
+    description = f"Importing {experiment.duration}s of experimental data:\n\n"
+    for datum in experiment.data:
+        description += f"  - {describe_data(datum)}\n"
+    return description
+
+
+class AddExperimentDataDialog(QtWidgets.QDialog):
+    """A dialog that allows the user to import data, either as a new Experiment or appended to an existing one."""
+
+    def __init__(
+        self,
+        experiment: Experiment,
+        project: Project,
+        parent: QtWidgets.QWidget | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.project = project
+        self.existing_experiments = list(project.experiments.values())
+
+        self.experiment = experiment
+        self.append_to_experiment = False
+        self.append_experiment_name: str = ""
+        self.offset: float = 0.0
+
+        self.setWindowTitle("Import data")
+        self.setModal(True)
+
+        self.layout = QtWidgets.QVBoxLayout()
+        self.setLayout(self.layout)
+
+        self.lbl_description = QtWidgets.QLabel(describe_experiment(self.experiment))
+        self.layout.addWidget(self.lbl_description)
+
+        self.rad_new = QtWidgets.QRadioButton("Create new experiment")
+        self.layout.addWidget(self.rad_new)
+        self.rad_append = QtWidgets.QRadioButton("Apply to existing experiment")
+        self.layout.addWidget(self.rad_append)
+        self.rad_new.setChecked(True)
+
+        self.new_box = QtWidgets.QWidget()
+        layout_new_box = QtWidgets.QVBoxLayout(self.new_box)
+        layout_new_box.addWidget(QtWidgets.QLabel("Experiment name:"))
+        self.txt_new_name = QtWidgets.QLineEdit()
+        layout_new_box.addWidget(self.txt_new_name)
+        self.layout.addWidget(self.new_box)
+        self.txt_new_name.setText(self.experiment.name)
+
+        self.append_box = QtWidgets.QWidget()
+        layout_append_box = QtWidgets.QVBoxLayout(self.append_box)
+        layout_append_box.addWidget(QtWidgets.QLabel("Existing experiment:"))
+        self.cmb_experiments = QtWidgets.QComboBox()
+        self.cmb_experiments.addItems(
+            [experiment.name for experiment in self.existing_experiments]
+        )
+        layout_append_box.addWidget(self.cmb_experiments)
+        layout_append_box.addWidget(QtWidgets.QLabel("Timepoint to insert data:"))
+        self.cmb_offset = QtWidgets.QComboBox()
+        layout_append_box.addWidget(self.cmb_offset)
+        self.layout.addWidget(self.append_box)
+        self.append_box.setVisible(False)
+
+        self.lbl_error = QtWidgets.QLabel("")
+        self.lbl_error.setStyleSheet("color: red")
+        self.layout.addWidget(self.lbl_error)
+
+        self.layout.addStretch()
+
+        button_layout = QtWidgets.QHBoxLayout()
+        self.save_button = QtWidgets.QPushButton("Import")
+        self.cancel_button = QtWidgets.QPushButton("Cancel")
+        button_layout.addWidget(self.save_button)
+        button_layout.addWidget(self.cancel_button)
+        self.layout.addLayout(button_layout)
+
+        if not self.existing_experiments:
+            self.rad_append.setEnabled(False)
+
+        self.rad_new.toggled.connect(self.rad_new_append_toggled)
+        self.txt_new_name.textEdited.connect(self.new_name_text_edited)
+        self.cmb_experiments.currentIndexChanged.connect(
+            self.cmb_experiments_index_changed
+        )
+        self.cmb_offset.currentIndexChanged.connect(self.cmb_offset_index_changed)
+        self.save_button.clicked.connect(self.accept)
+        self.cancel_button.clicked.connect(self.reject)
+        self._apply_default_selection()
+        self.resize(800, 600)
+
+    def _apply_default_selection(self) -> None:
+        if not self.existing_experiments:
+            self.rad_new.setChecked(True)
+            self.cmb_experiments_index_changed(0)
+            self.new_name_text_edited(self.txt_new_name.text())
+            return
+
+        matching_index = next(
+            (
+                i
+                for i, experiment in enumerate(self.existing_experiments)
+                if experiment.name == self.experiment.name
+            ),
+            -1,
+        )
+        if matching_index >= 0:
+            self.rad_append.setChecked(True)
+            self.cmb_experiments.setCurrentIndex(matching_index)
+            self.cmb_experiments_index_changed(matching_index)
+        else:
+            self.rad_new.setChecked(True)
+            self.cmb_experiments_index_changed(0)
+        self.new_name_text_edited(self.txt_new_name.text())
+
+    def rad_new_append_toggled(self):
+        self.append_to_experiment = self.rad_append.isChecked()
+        self.new_box.setVisible(not self.append_to_experiment)
+        self.txt_new_name.setEnabled(not self.append_to_experiment)
+        self.append_box.setVisible(self.append_to_experiment)
+        self.cmb_experiments.setEnabled(self.append_to_experiment)
+        self.cmb_offset.setEnabled(self.append_to_experiment)
+        if self.append_to_experiment:
+            self.cmb_experiments_index_changed(self.cmb_experiments.currentIndex())
+            self._refresh_append_error()
+        else:
+            self.new_name_text_edited(self.txt_new_name.text())
+
+    def cmb_offset_index_changed(self, index: int) -> None:
+        if index < 0:
+            self.offset = 0.0
+            return
+        experiment_index = self.cmb_experiments.currentIndex()
+        if experiment_index < 0 or experiment_index >= len(self.existing_experiments):
+            self.offset = 0.0
+            return
+        self.offset = self.existing_experiments[experiment_index].timepoints[index]
+        self._refresh_append_error()
+
+    def cmb_experiments_index_changed(self, index: int) -> None:
+        self.cmb_offset.clear()
+        if index < 0 or index >= len(self.existing_experiments):
+            return
+        self.append_experiment_name = self.existing_experiments[index].name
+        timepoints = list(self.existing_experiments[index].timepoints)
+        option_labels = []
+        for i, timepoint in enumerate(timepoints):
+            label = f"{timepoint * 1000:.5g} ms"
+            if i == len(timepoints) - 1:
+                label = f"{label} (Append)"
+            else:
+                label = f"{label} ({self._insert_mode_label(index, timepoint)})"
+            option_labels.append(label)
+        self.cmb_offset.addItems(option_labels)
+        # if there is only start/end, default to start; otherwise default to append
+        if self.cmb_offset.count() > 0:
+            default_offset_index = 0 if len(timepoints) <= 2 else len(timepoints) - 1
+            self.cmb_offset.setCurrentIndex(default_offset_index)
+        # check if appending this data to the selected experiment is valid
+        self._refresh_append_error()
+
+    def new_name_text_edited(self, text: str) -> None:
+        self.experiment.name = text
+        self.lbl_error.clear()
+        self.save_button.setEnabled(True)
+
+    def _insert_mode_label(self, experiment_index: int, offset: float) -> str:
+        if experiment_index < 0 or experiment_index >= len(self.existing_experiments):
+            return "partially replace + insert"
+        existing_experiment = self.existing_experiments[experiment_index]
+        if offset >= existing_experiment.duration:
+            return "Append"
+
+        has_overlap = False
+        has_new_only = False
+
+        for new_datum in self.experiment.data:
+            existing_datum = next(
+                (
+                    datum
+                    for datum in existing_experiment.data
+                    if datum.name == new_datum.name and type(datum) is type(new_datum)
+                ),
+                None,
+            )
+            if existing_datum is None:
+                continue
+            if isinstance(existing_datum, TraceData) and isinstance(
+                new_datum, TraceData
+            ):
+                existing_ids = set(map(int, existing_datum.indices))
+                new_ids = set(map(int, new_datum.indices))
+            elif isinstance(existing_datum, SpikeData) and isinstance(
+                new_datum, SpikeData
+            ):
+                existing_ids = set(map(int, existing_datum.spike_indices))
+                new_ids = set(map(int, new_datum.spike_indices))
+            elif isinstance(existing_datum, SynapseData) and isinstance(
+                new_datum, SynapseData
+            ):
+                return "overwrite"
+            else:
+                continue
+            if existing_ids & new_ids:
+                has_overlap = True
+            if new_ids - existing_ids:
+                has_new_only = True
+
+        if has_overlap and has_new_only:
+            return "partially replace + insert"
+        if has_overlap:
+            return "overwrite"
+        return "insert alongside existing data"
+
+    def _refresh_append_error(self) -> None:
+        error = self.project.issues_with_appending_experimental_data(
+            self.append_experiment_name,
+            self.experiment.data,
+        )
+        self.lbl_error.setText(error)
+        self.save_button.setEnabled(error == "")

neuroseq/analysis_plugins.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+
+from qtpy import QtCore
+
+from neuroseq.data import SpikeData
+from neuroseq.data import SynapseData
+from neuroseq.data import TraceData
+
+
+@dataclass(frozen=True)
+class AnalysisPlugin:
+    id: str
+    label: str
+    icon: str
+    render: Callable[
+        [object, TraceData | SpikeData | SynapseData, slice | None, slice | None], None
+    ]
+    open_dialog: (
+        Callable[
+            [
+                object,
+                object,
+                TraceData | SpikeData | SynapseData,
+                slice | None,
+                slice | None,
+            ],
+            None,
+        ]
+        | None
+    ) = None
+
+    def __str__(self) -> str:
+        return self.label
+
+
+#: Environment variable overriding the per-user plugin folder (used by tests).
+USER_PLUGIN_DIR_ENV = "NEUROSEQ_USER_PLUGIN_DIR"
+
+
+def _plugins_directory() -> Path:
+    """Built-in plugins shipped inside the package."""
+    return Path(__file__).resolve().parent / "resources" / "analysis_plugins"
+
+
+def user_plugins_directory(create: bool = False) -> Path:
+    """Per-user plugin folder (outside the package), e.g. for chat-authored plugins.
+
+    ``NEUROSEQ_USER_PLUGIN_DIR`` overrides the location. Otherwise the folder
+    lives under the platform's user data location (``.../neuroseq/analysis_plugins``).
+    """
+    override = os.environ.get(USER_PLUGIN_DIR_ENV)
+    if override:
+        directory = Path(override).expanduser()
+    else:
+        base = QtCore.QStandardPaths.writableLocation(
+            QtCore.QStandardPaths.StandardLocation.GenericDataLocation
+        )
+        root = Path(base) / "neuroseq" if base else Path.home() / ".neuroseq"
+        directory = root / "analysis_plugins"
+    if create:
+        directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def builtin_plugin_names() -> set[str]:
+    """Module stems in the built-in plugin folder, including helper modules."""
+    plugins_dir = _plugins_directory()
+    if not plugins_dir.is_dir():
+        return set()
+    return {path.stem for path in plugins_dir.glob("*.py")}
+
+
+def _load_plugin_module(
+    plugin_file: Path, namespace: str = "neuroseq.analysis_plugin"
+) -> ModuleType | None:
+    logger = logging.getLogger(__name__)
+    spec = importlib.util.spec_from_file_location(
+        f"{namespace}.{plugin_file.stem}",
+        plugin_file,
+    )
+    if spec is None or spec.loader is None:
+        logger.warning(
+            f"Could not create module spec for analysis plugin: {plugin_file}"
+        )
+        return None
+    module = importlib.util.module_from_spec(spec)
+    # Match normal import semantics. Decorators such as ``@dataclass`` resolve
+    # annotations through ``sys.modules`` while the module is executing.
+    sys.modules[spec.name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        sys.modules.pop(spec.name, None)
+        logger.exception(f"Failed to load analysis plugin {plugin_file}: {exc}")
+        return None
+    return module
+
+
+def _plugin_files() -> list[tuple[Path, str]]:
+    """Built-in plugin files followed by non-shadowing user plugin files."""
+    logger = logging.getLogger(__name__)
+    files: list[tuple[Path, str]] = []
+    plugins_dir = _plugins_directory()
+    if plugins_dir.is_dir():
+        files.extend(
+            (path, "neuroseq.analysis_plugin")
+            for path in sorted(plugins_dir.glob("*.py"))
+            if not path.stem.startswith("_")
+        )
+    builtin_names = builtin_plugin_names()
+    user_dir = user_plugins_directory()
+    if user_dir.is_dir() and user_dir.resolve() != plugins_dir.resolve():
+        for path in sorted(user_dir.glob("*.py")):
+            if path.stem.startswith("_"):
+                continue
+            if path.stem in builtin_names:
+                logger.warning(
+                    f"Skipping user analysis plugin {path}: name collides with a "
+                    f"built-in plugin"
+                )
+                continue
+            files.append((path, "neuroseq.user_analysis_plugin"))
+    return files
+
+
+def discover_analysis_plugins() -> list[AnalysisPlugin]:
+    logger = logging.getLogger(__name__)
+    plugins: list[AnalysisPlugin] = []
+    builtin_ids: set[str] = set()
+
+    for plugin_file, namespace in _plugin_files():
+        is_user = namespace != "neuroseq.analysis_plugin"
+        module = _load_plugin_module(plugin_file, namespace)
+        if module is None:
+            continue
+
+        render = getattr(module, "render_analysis", None)
+        if not callable(render):
+            logger.warning(
+                f"Skipping analysis plugin {plugin_file}: missing callable render_analysis"
+            )
+            continue
+
+        plugin_id = str(getattr(module, "PLUGIN_ID", plugin_file.stem))
+        if is_user and plugin_id in builtin_ids:
+            logger.warning(
+                f"Skipping user analysis plugin {plugin_file}: PLUGIN_ID "
+                f"{plugin_id!r} collides with a built-in plugin"
+            )
+            continue
+        if not is_user:
+            builtin_ids.add(plugin_id)
+        plugin_label = getattr(module, "PLUGIN_NAME", plugin_file.stem)
+        plugin_icon = getattr(module, "PLUGIN_ICON", "mdi6.puzzle")
+        open_dialog = getattr(module, "open_analysis_dialog", None)
+        if open_dialog is not None and not callable(open_dialog):
+            logger.warning(
+                f"Ignoring non-callable open_analysis_dialog in analysis plugin "
+                f"{plugin_file}"
+            )
+            open_dialog = None
+
+        plugins.append(
+            AnalysisPlugin(
+                id=plugin_id,
+                label=str(plugin_label),
+                icon=str(plugin_icon),
+                render=render,
+                open_dialog=open_dialog,
+            )
+        )
+
+    return plugins