active-units 0.1.0__py3-none-any.whl

active_units/__init__.py

@@ -0,0 +1,34 @@
+"""
+Active Units: Interactive unit filtering by activity response.
+
+Minimal, flat-structure package for computing and filtering neural units
+based on baseline/response firing rates.
+
+Three inputs:
+  1. sorted_spikes_dir: Path to spike sorting output folder
+  2. trials_csv: Path to trials.csv (columns: experiment, trial, sample)
+  3. config: Path to config.json or dict with activity_filter parameters
+
+Example:
+    >>> from active_units import compute_activity
+    >>> summary = compute_activity(
+    ...     sorted_spikes_dir="/path/to/sorted_spikes",
+    ...     trials_csv="/path/to/trials.csv",
+    ...     config="/path/to/config.json",
+    ...     output_dir="/path/to/output"
+    ... )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Lab Team"
+
+from .activity import compute_activity
+from .dashboard import make_app
+from .utils import load_config, load_trials
+
+__all__ = [
+    "compute_activity",
+    "make_app",
+    "load_config",
+    "load_trials",
+]

active_units/activity.py

@@ -0,0 +1,228 @@
+"""Compute unit activity metrics from kilosort output."""
+
+import numpy as np
+import pandas as pd
+from pathlib import Path
+from typing import Union, Dict, Any, Tuple
+from scipy import stats
+
+from .utils import load_config, load_trials, validate_sorted_spikes_dir
+
+
+def compute_activity(
+    sorted_spikes_dir: str,
+    trials_csv: str,
+    config: Union[str, Dict[str, Any]],
+    output_dir: str = None,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    """
+    Compute baseline/response activity for all units.
+
+    Loads spike data from spike sorting output, samples random trials per experiment,
+    calculates baseline and response firing rates, performs paired t-tests.
+
+    Args:
+        sorted_spikes_dir: Path to spike sorting output folder with spike_times.npy,
+                          spike_clusters.npy, cluster_group.tsv
+                          (works with kilosort4, kilosort3, IBL pipeline, etc.)
+        trials_csv: Path to trials.csv with columns: experiment, trial, sample
+        config: Path to config.json or dict with activity_filter parameters
+                Required keys: baseline_window_start/end, response_window_start/end,
+                n_random_trials, sample_rate
+        output_dir: Directory to save activity_summary.csv (default: current dir)
+        verbose: Print diagnostic info
+
+    Returns:
+        pd.DataFrame: Summary statistics with columns:
+                      experiment, unit, bsl_mean, bsl_std, signal_mean,
+                      signal_std, difference, p_value
+
+    Saves:
+        - activity_summary.csv: Activity summary per unit per experiment
+        - clusters_included.txt: List of cluster IDs that were included
+
+    Example:
+        >>> summary = compute_activity(
+        ...     sorted_spikes_dir="/path/to/sorted_spikes",
+        ...     trials_csv="/path/to/trials.csv",
+        ...     config="/path/to/config.json",
+        ...     output_dir="/tmp/results",
+        ...     verbose=True
+        ... )
+        >>> print(summary[['experiment', 'unit', 'bsl_mean', 'signal_mean']])
+    """
+
+    # Load configuration
+    if verbose:
+        print("Loading configuration...")
+    config_dict = load_config(config)
+
+    baseline_start_s = config_dict["baseline_window_start"]
+    baseline_end_s = config_dict["baseline_window_end"]
+    response_start_s = config_dict["response_window_start"]
+    response_end_s = config_dict["response_window_end"]
+    n_random = config_dict["n_random_trials"]
+    sample_rate = config_dict["sample_rate"]
+
+    # Load trials
+    if verbose:
+        print("Loading trials...")
+    trials_df = load_trials(trials_csv)
+
+    # Validate sorted spikes directory
+    if verbose:
+        print("Validating spike sorting output directory...")
+    ss_files = validate_sorted_spikes_dir(sorted_spikes_dir)
+
+    # Load spike data
+    if verbose:
+        print("Loading spike data...")
+    spike_times = np.load(ss_files["spike_times"]).flatten()
+    spike_clusters = np.load(ss_files["spike_clusters"]).flatten()
+
+    # Load or create cluster_group
+    if ss_files["cluster_group"] and Path(ss_files["cluster_group"]).exists():
+        cluster_group = pd.read_csv(ss_files["cluster_group"], sep="\t")
+        valid_mask = cluster_group["group"].isin(["good", "mua"])
+        valid_units = cluster_group[valid_mask]["cluster_id"].values
+    else:
+        # If no cluster_group, use all unique cluster IDs
+        valid_units = np.unique(spike_clusters)
+        if verbose:
+            print("  (cluster_group.tsv not found, using all units)")
+
+    if verbose:
+        print(f"  {len(valid_units)} valid units")
+        print(f"  {len(spike_times)} total spikes")
+
+    # Convert time windows from seconds to samples
+    baseline_start_samples = int(baseline_start_s * sample_rate)
+    baseline_end_samples = int(baseline_end_s * sample_rate)
+    response_start_samples = int(response_start_s * sample_rate)
+    response_end_samples = int(response_end_s * sample_rate)
+
+    baseline_duration = (baseline_end_samples - baseline_start_samples) / sample_rate
+    response_duration = (response_end_samples - response_start_samples) / sample_rate
+
+    if verbose:
+        print(f"  Baseline window: {baseline_start_s:.2f} to {baseline_end_s:.2f}s ({baseline_duration:.2f}s)")
+        print(f"  Response window: {response_start_s:.2f} to {response_end_s:.2f}s ({response_duration:.2f}s)")
+
+    # Results
+    summary_data = []
+
+    # Process each experiment
+    experiments = sorted(trials_df["experiment"].unique())
+
+    if verbose:
+        print(f"\nProcessing {len(experiments)} experiments...")
+
+    for exp_id in experiments:
+        exp_trials = trials_df[trials_df["experiment"] == exp_id]
+
+        if verbose:
+            print(f"  Experiment {exp_id}: {len(exp_trials)} trials")
+
+        # Sample random trials
+        if len(exp_trials) > n_random:
+            sampled_trials = exp_trials.sample(n=n_random, random_state=int(exp_id))
+        else:
+            sampled_trials = exp_trials
+
+        if verbose:
+            print(f"    Sampling {len(sampled_trials)} trials for activity estimation")
+
+        # For each valid unit
+        for unit_id in valid_units:
+            unit_mask = spike_clusters == unit_id
+            unit_spikes = spike_times[unit_mask]
+
+            baseline_rates = []
+            response_rates = []
+
+            # Process each trial
+            for _, trial_row in sampled_trials.iterrows():
+                trial_sample = int(trial_row["sample"])
+
+                # Baseline period
+                baseline_start_sample = trial_sample + baseline_start_samples
+                baseline_end_sample = trial_sample + baseline_end_samples
+                baseline_spikes = unit_spikes[
+                    (unit_spikes >= baseline_start_sample) &
+                    (unit_spikes < baseline_end_sample)
+                ]
+                baseline_rate = len(baseline_spikes) / baseline_duration if baseline_duration > 0 else 0
+                baseline_rates.append(baseline_rate)
+
+                # Response period
+                response_start_sample = trial_sample + response_start_samples
+                response_end_sample = trial_sample + response_end_samples
+                response_spikes = unit_spikes[
+                    (unit_spikes >= response_start_sample) &
+                    (unit_spikes < response_end_sample)
+                ]
+                response_rate = len(response_spikes) / response_duration if response_duration > 0 else 0
+                response_rates.append(response_rate)
+
+            # Calculate statistics
+            baseline_rates = np.array(baseline_rates)
+            response_rates = np.array(response_rates)
+
+            bsl_mean = np.mean(baseline_rates)
+            bsl_std = np.std(baseline_rates)
+            sig_mean = np.mean(response_rates)
+            sig_std = np.std(response_rates)
+            difference = sig_mean - bsl_mean
+
+            # Paired t-test (baseline vs response for same trials)
+            if len(baseline_rates) > 1:
+                t_stat, p_value = stats.ttest_rel(response_rates, baseline_rates)
+            else:
+                p_value = np.nan
+
+            summary_data.append({
+                "experiment": exp_id,
+                "unit": unit_id,
+                "bsl_mean": bsl_mean,
+                "bsl_std": bsl_std,
+                "signal_mean": sig_mean,
+                "signal_std": sig_std,
+                "difference": difference,
+                "p_value": p_value,
+            })
+
+        if verbose:
+            print(f"    ✓ Processed {len(valid_units)} units")
+
+    # Create summary dataframe
+    summary_df = pd.DataFrame(summary_data)
+
+    # Round for display
+    for col in ["bsl_mean", "bsl_std", "signal_mean", "signal_std", "difference"]:
+        summary_df[col] = summary_df[col].round(2)
+    summary_df["p_value"] = summary_df["p_value"].round(4)
+
+    # Save results
+    if output_dir is None:
+        output_dir = "."
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    summary_file = output_path / "activity_summary.csv"
+    summary_df.to_csv(summary_file, index=False)
+
+    clusters_file = output_path / "clusters_included.txt"
+    with open(clusters_file, "w") as f:
+        for unit_id in sorted(valid_units):
+            f.write(f"{unit_id}\n")
+
+    if verbose:
+        print(f"\n✓ Summary saved to: {summary_file}")
+        print(f"  Total rows: {len(summary_df)}")
+        print(f"  Unique units: {summary_df['unit'].nunique()}")
+        print(f"  Unique experiments: {summary_df['experiment'].nunique()}")
+        print(f"  Clusters included: {len(valid_units)}")
+
+    return summary_df

active_units/cli.py

@@ -0,0 +1,148 @@
+"""Command-line interface for active-units."""
+
+import click
+import sys
+from pathlib import Path
+
+from .activity import compute_activity
+from .dashboard import make_app
+
+
+@click.group()
+def cli():
+    """Active Units — compute and filter neural units interactively."""
+    pass
+
+
+@cli.command()
+@click.argument('sorted_spikes_dir', type=click.Path(exists=True))
+@click.argument('trials_csv', type=click.Path(exists=True))
+@click.argument('config', type=click.Path(exists=True))
+@click.option('--output-dir', type=click.Path(), default=None,
+              help='Output directory (default: current directory)')
+@click.option('--verbose', is_flag=True, help='Print diagnostic info')
+def compute(sorted_spikes_dir, trials_csv, config, output_dir, verbose):
+    """
+    Compute baseline/response activity for all units.
+
+    SORTED_SPIKES_DIR: Path to spike sorting output folder
+                       (works with kilosort4, kilosort3, IBL pipeline, etc.)
+    TRIALS_CSV: Path to trials.csv (columns: experiment, trial, sample)
+    CONFIG: Path to config.json (activity_filter parameters)
+
+    Example:
+        active-units compute /path/to/sorted_spikes trials.csv config.json --output-dir ./results
+    """
+    try:
+        summary = compute_activity(
+            sorted_spikes_dir=sorted_spikes_dir,
+            trials_csv=trials_csv,
+            config=config,
+            output_dir=output_dir,
+            verbose=verbose
+        )
+
+        if verbose:
+            print("\nActivity Summary Statistics:")
+            print(summary[['experiment', 'unit', 'bsl_mean', 'signal_mean', 'difference', 'p_value']].head(10))
+
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('activity_csv', type=click.Path(exists=True))
+@click.argument('trials_csv', type=click.Path(exists=True))
+@click.argument('sorted_spikes_dir', type=click.Path(exists=True))
+@click.argument('config', type=click.Path(exists=True))
+@click.option('--port', type=int, default=5006, help='Bokeh server port (default: 5006)')
+@click.option('--show', is_flag=True, help='Open in browser')
+def dashboard(activity_csv, trials_csv, sorted_spikes_dir, config, port, show):
+    """
+    Launch interactive filtering dashboard.
+
+    ACTIVITY_CSV: Path to activity_summary.csv (output from compute command)
+    TRIALS_CSV: Path to trials.csv
+    SORTED_SPIKES_DIR: Path to spike sorting output folder
+    CONFIG: Path to config.json
+
+    Example:
+        active-units dashboard results/activity_summary.csv trials.csv /path/to/sorted_spikes config.json --port 5006 --show
+    """
+    try:
+        from bokeh.server.server import Server
+        from bokeh.plotting import curdoc
+
+        def bkapp(doc):
+            layout = make_app(
+                activity_csv=activity_csv,
+                trials_csv=trials_csv,
+                sorted_spikes_dir=sorted_spikes_dir,
+                config=config,
+            )
+            doc.add_root(layout)
+            doc.title = "Unit Activity Filter"
+
+        server = Server(
+            {'/': bkapp},
+            port=port,
+            show=show,
+            allow_websocket_origin=['localhost:' + str(port)]
+        )
+
+        click.secho(f"✓ Dashboard running at http://localhost:{port}", fg='green')
+        click.echo("Press Ctrl+C to stop")
+
+        server.start()
+        server.io_loop.start()
+
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('sorted_spikes_dir', type=click.Path(exists=True))
+@click.argument('trials_csv', type=click.Path(exists=True))
+def status(sorted_spikes_dir, trials_csv):
+    """
+    Check setup and data integrity.
+
+    SORTED_SPIKES_DIR: Path to spike sorting output folder
+    TRIALS_CSV: Path to trials.csv
+
+    Validates that all required files exist and have expected structure.
+    """
+    try:
+        from .utils import validate_sorted_spikes_dir, load_trials
+
+        click.echo("Checking spike sorting output directory...")
+        ss_files = validate_sorted_spikes_dir(sorted_spikes_dir)
+        click.secho("  ✓ Spike sorting files found", fg='green')
+
+        click.echo("Loading spike data...")
+        import numpy as np
+        spike_times = np.load(ss_files["spike_times"]).flatten()
+        spike_clusters = np.load(ss_files["spike_clusters"]).flatten()
+        click.secho(f"  ✓ {len(spike_times)} spikes from {len(np.unique(spike_clusters))} clusters", fg='green')
+
+        click.echo("Loading trials...")
+        trials = load_trials(trials_csv)
+        click.secho(f"  ✓ {len(trials)} trials across {trials['experiment'].nunique()} experiments", fg='green')
+
+        click.echo("\n" + "=" * 50)
+        click.secho("Setup looks good!", fg='green')
+
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+        sys.exit(1)
+
+
+def main():
+    """Entry point for CLI."""
+    cli()
+
+
+if __name__ == '__main__':
+    main()