ethograph 0.1.3__py3-none-any.whl

ethograph/__init__.py

@@ -0,0 +1,115 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ethograph")
+except PackageNotFoundError:
+    # package is not installed
+    pass
+
+    
+from ethograph.io.trialtree import TrialTree
+from ethograph.io.dataset import (
+    add_angle_rgb_to_ds,
+    add_changepoints_to_ds,
+    downsample_trialtree,
+)
+from ethograph.utils.xr_utils import get_ds_duration, get_time_coord, sel_valid
+from ethograph.utils.paths import get_project_root
+from ethograph.io.catalog import (
+    DataCatalog,
+    DataLoader,
+    PlotData,
+    PynappleLoader,
+    XarrayLoader,
+    catalog_from_pynapple,
+    catalog_from_xarray,
+)
+from ethograph.io.pynapple import load_nap_data
+from ethograph.io.nwb_alignment import (
+    NWBAlignment,
+    align_media_per_trial,
+    align_media_from_streams,
+)
+from ethograph.datasets import sample_data
+from ethograph.io.time_model import (
+    SourceCollection,
+    TimeRange,
+    TimeSource,
+)
+
+
+def open(path: str) -> TrialTree:
+    """Load a TrialTree from a saved NetCDF file.
+
+    Shorthand for :meth:`TrialTree.open <ethograph.io.trialtree.TrialTree.open>`.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to a ``.nc`` file previously saved with ``dt.save()``.
+
+    Returns
+    -------
+    TrialTree
+
+    Examples
+    --------
+    >>> import ethograph as eto
+    >>> dt = eto.open("experiment.nc")
+    >>> dt.trials
+    [1, 2, 3]
+    >>> ds = dt.itrial(0)
+    """
+    return TrialTree.open(path)
+
+
+def from_datasets(datasets: list) -> TrialTree:
+    """Build a TrialTree from a list of per-trial xarray Datasets.
+
+    Shorthand for :meth:`TrialTree.from_datasets <ethograph.io.trialtree.TrialTree.from_datasets>`.
+
+    Each dataset must have ``attrs["trial"]`` set to a unique trial
+    identifier.
+
+    Parameters
+    ----------
+    datasets : list[xarray.Dataset]
+        One Dataset per trial.
+
+    Returns
+    -------
+    TrialTree
+
+    Examples
+    --------
+    >>> import xarray as xr, numpy as np, ethograph as eto
+    >>> trials = []
+    >>> for i in range(1, 4):
+    ...     ds = xr.Dataset({"speed": xr.DataArray(np.random.rand(300), dims=["time"])})
+    ...     ds.attrs["trial"] = i
+    ...     trials.append(ds)
+    >>> dt = eto.from_datasets(trials)
+    >>> dt.trials
+    [1, 2, 3]
+    """
+    return TrialTree.from_datasets(datasets)
+
+
+def from_continuous(ds, epochs) -> TrialTree:
+    """Build a TrialTree from a single continuous recording + trial epochs.
+
+    Shorthand for :meth:`TrialTree.from_continuous`.
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Full recording dataset.
+    epochs : pandas.DataFrame or pynapple.IntervalSet
+        Trial boundaries.  DataFrame must have columns ``trial``,
+        ``start_time``, ``stop_time``.
+
+    Returns
+    -------
+    TrialTree
+    """
+    return TrialTree.from_continuous(ds, epochs)

ethograph/__main__.py

@@ -0,0 +1,3 @@
+from ethograph.cli import main
+
+main()

ethograph/assets/menu.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
+  "menu_name": "ethograph",
+  "menu_items": [
+    {
+      "name": "ethograph",
+      "command": ["{{ PYTHON }}", "-m", "ethograph", "launch"],
+      "activate": true,
+      "terminal": true,
+      "platforms": {
+        "win": {
+          "desktop": true,
+          "icon": "{{ MENU_DIR }}/icon.ico",
+          "command": ["{{ PYTHON }}", "-m", "ethograph", "launch", "--keep-open"]
+        },
+        "linux": {
+          "Categories": ["Science", "Education"],
+          "icon": "{{ MENU_DIR }}/icon.png"
+        },
+        "osx": {
+          "icon": "{{ MENU_DIR }}/icon.png"
+        }
+      }
+    }
+  ]
+}

ethograph/cli.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+"""Command-line interface for ethograph."""
+
+import logging
+import os
+import sys
+import warnings
+
+# Suppress noisy dependency warnings before any imports trigger them
+warnings.filterwarnings("ignore", category=DeprecationWarning, module=r"logging")
+warnings.filterwarnings("ignore", category=DeprecationWarning, module=r"vispy\.")
+warnings.filterwarnings("ignore", category=DeprecationWarning, module=r"numpy\.")
+
+# PyOpenGL info message goes through logging, not warnings
+logging.getLogger("OpenGL.acceleratesupport").setLevel(logging.WARNING)
+
+def _ensure_qt_plugins():
+    """Set QT_PLUGIN_PATH for conda-forge Qt installs (needed by menuinst shortcuts)."""
+    if os.environ.get("QT_PLUGIN_PATH"):
+        return
+    candidates = [
+        os.path.join(sys.prefix, "Library", "plugins"),        # Windows conda-forge
+        os.path.join(sys.prefix, "lib", "qt5", "plugins"),     # Linux conda-forge
+        os.path.join(sys.prefix, "lib", "qt", "plugins"),      # macOS conda-forge
+    ]
+    for path in candidates:
+        if os.path.isdir(os.path.join(path, "platforms")):
+            os.environ["QT_PLUGIN_PATH"] = path
+            return
+
+
+def launch():
+    """Launch the ethograph GUI."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(name)s - %(levelname)s - %(message)s",
+    )
+    logging.getLogger("napari").setLevel(logging.WARNING)
+    _ensure_qt_plugins()
+    import napari
+    from ethograph.gui.widgets_meta import MetaWidget
+
+    viewer = napari.Viewer()
+    viewer.window.add_dock_widget(MetaWidget(viewer), name="ethograph GUI")
+    napari.run()
+
+
+def main():
+    """Main CLI entry point."""
+    if len(sys.argv) < 2:
+        print("Usage: ethograph <command>")
+        print("Commands:")
+        print("  launch    Launch the ethograph GUI")
+        print("  shortcut  Install desktop/Start Menu shortcut")
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "launch":
+        launch()
+    elif command == "shortcut":
+        from ethograph.shortcuts import install_shortcut
+        sys.exit(install_shortcut())
+    else:
+        print(f"Unknown command: {command}")
+        print("Available commands: launch, shortcut")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ethograph/crowlab/io_matlab.py

@@ -0,0 +1,264 @@
+"""Custom code for importing data from lab-internal matlab codes to python"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import xarray as xr
+from scipy.io import loadmat
+
+import ethograph as eto
+
+
+def get_all_trials_path_info(all_trials_path):
+    """
+    Extract subject_id, session_date, session_number, and dataset_name from a path string.
+    Args:
+        all_trials_path (str): Path string to parse.
+    Returns:
+        subject_id (str), session_date (str), session_number (str), dataset_name (str)
+    """
+    path = all_trials_path.replace('\\', '/')
+
+    id_match = re.search(r'id-([^/\\]+)', path)
+    subject_id = id_match.group(1) if id_match else ''
+
+    date_sess_match = re.search(r'date-(\d{8})_(\d{2})', path)
+    if date_sess_match:
+        session_date = date_sess_match.group(1)
+        session_number = date_sess_match.group(2)
+    else:
+        session_date = ''
+        session_number = ''
+
+    dataset_name = f'{session_date}-{session_number}_{subject_id}'
+
+    return subject_id, session_date, session_number, dataset_name
+
+
+
+def update_dt_with_matlab_pulse_onsets(
+    dt: xr.DataTree,
+    matlab_path: str | Path,
+) -> xr.DataTree:
+    """
+    Update NetCDF trial data with information from MATLAB AllTrials structure.
+    
+    Parameters
+    ----------
+    nc_path : str | Path
+        Path to the NetCDF file containing trial data
+    matlab_path : str | Path
+        Path to the MATLAB file containing AllTrials structure
+
+    Returns
+    -------
+    xr.DataTree
+        Updated DataTree with MATLAB trial information
+        
+    Raises
+    ------
+    FileNotFoundError
+        If input files don't exist
+    ValueError
+        If required data structures are missing
+    """
+
+    matlab_path = Path(matlab_path)
+
+    if not matlab_path.exists():
+        raise FileNotFoundError(f"MATLAB file not found: {matlab_path}")
+    
+
+    
+        
+    # Load MATLAB data
+    mat_data = loadmat(
+        matlab_path, 
+        squeeze_me=True, 
+        struct_as_record=False
+    )
+    
+    if 'AllTrials' not in mat_data:
+        raise ValueError(f"'AllTrials' structure not found in {matlab_path}")
+    
+    all_trials = mat_data['AllTrials']
+    
+    # Create lookup for efficient trial matching
+    matlab_trials_dict = {
+        trial.trial_num: trial 
+        for trial in all_trials
+    }
+    
+    # Update each dataset in the tree
+    for node_name, node in dt.children.items():
+        if node.ds is None or 'trial' not in node.ds.attrs:
+            continue
+            
+        trial_num = node.ds.attrs['trial']
+
+
+        if trial_num not in matlab_trials_dict:
+            continue
+            
+        trial = matlab_trials_dict[trial_num]
+        
+        # Create mutable copy of the dataset
+        ds = node.to_dataset().copy()
+        
+        pulse_onsets = trial.pulse_info.pulse_onsets
+
+        
+        assert len(pulse_onsets) == len(ds.time)
+        
+        ds['pulse_onsets'] = ('time', pulse_onsets)
+
+        # Assign back to the DataTree node
+        dt[node_name] = ds
+
+    
+    return dt
+
+
+def update_nc_with_matlab_trials(
+    dt: xr.DataTree,
+    matlab_path: str | Path,
+) -> xr.DataTree:
+    """
+    Update NetCDF trial data with information from MATLAB AllTrials structure.
+    
+    Parameters
+    ----------
+    dt : xr.DataTree
+        The DataTree containing trial data
+    matlab_path : str | Path
+        Path to the MATLAB file containing AllTrials structure
+    output_path : Optional[str | Path]
+        Path to save updated NetCDF. If None, overwrites input file
+        
+    matlab_path : str | Path
+        Path to the MATLAB file containing AllTrials structure
+
+    Returns
+    -------
+    xr.DataTree
+        Updated DataTree with MATLAB trial information
+        
+    Raises
+    ------
+    FileNotFoundError
+        If input files don't exist
+    ValueError
+        If required data structures are missing
+    """
+    matlab_path = Path(matlab_path)
+    
+
+    if not matlab_path.exists():
+        raise FileNotFoundError(f"MATLAB file not found: {matlab_path}")
+
+    
+    # Load MATLAB data
+    mat_data = loadmat(
+        matlab_path, 
+        squeeze_me=True, 
+        struct_as_record=False
+    )
+    
+    if 'AllTrials' not in mat_data:
+        raise ValueError(f"'AllTrials' structure not found in {matlab_path}")
+    
+    all_trials = mat_data['AllTrials']
+    
+    # Create lookup for efficient trial matching
+    matlab_trials_dict = {
+        trial.trial_num: trial 
+        for trial in all_trials
+    }
+    
+    # Update each dataset in the tree
+    for node_name, node in dt.children.items():
+        if node.ds is None or 'trial' not in node.ds.attrs:
+            continue
+            
+        trial_num = node.ds.attrs['trial']
+        
+        if trial_num not in matlab_trials_dict:
+            continue
+            
+        trial = matlab_trials_dict[trial_num]
+        ds = node.ds
+        
+        # Update attributes
+        if hasattr(trial.info, 'poscat'):
+            ds.attrs['poscat'] = trial.info.poscat
+        if hasattr(trial.info, 'num_pellets'):
+            ds.attrs['num_pellets'] = trial.info.num_pellets
+        
+        # Process boundary events
+        event_data = _extract_boundary_events(trial.info)
+        if event_data is not None:
+            ds['boundary_events'] = ('events', event_data)
+            ds = ds.assign_coords(
+                events=('events', ['disp_out', 'disp_in', 'box_in', 'box_out'])
+            )
+        
+        # Initialize labels
+        n_time = len(ds.coords['time'])
+        n_individuals = len(ds.coords['individuals'])
+        ds['labels'] = (
+            ('time', 'individuals'), 
+            np.zeros((n_time, n_individuals))
+        )
+        
+        # Update labels if available
+        if hasattr(trial, 'label_infos') and hasattr(trial.label_infos, 'beakTip'):
+            if 'bird' in ds.attrs:
+                bird = ds.attrs['bird']
+                labels = trial.label_infos.beakTip.labels
+                ds['labels'].loc[dict(individuals=bird)] = labels
+    
+    
+    return dt
+
+
+def _extract_boundary_events(trial_info) -> Optional[np.ndarray]:
+    """
+    Extract boundary events from trial info structure.
+    
+    Parameters
+    ----------
+    trial_info : object
+        MATLAB trial info structure
+        
+    Returns
+    -------
+    Optional[np.ndarray]
+        Array of boundary events or None if extraction fails
+    """
+    event_data = np.zeros(4)
+    
+    if not hasattr(trial_info, 'stick_in_out_disp'):
+        return None
+        
+    disp_out_in = trial_info.stick_in_out_disp
+    
+    # Extract disp_out and disp_in
+    for j, val in enumerate([0, 1]):
+        try:
+            event_data[j] = int(disp_out_in[val]) - 1
+        except (IndexError, TypeError, ValueError):
+            event_data[j] = np.nan
+    
+    # Extract box_in and box_out
+    if hasattr(trial_info, 'first_in_last_out'):
+        for j, idx in enumerate([0, 1], start=2):
+            try:
+                event_data[j] = int(trial_info.first_in_last_out[idx-2]) - 1
+            except (IndexError, TypeError, ValueError):
+                event_data[j] = np.nan
+    else:
+        event_data[2:] = np.nan
+    
+    return event_data