marm-viz 0.1.0__tar.gz

marm_viz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Menegas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marm_viz-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: marm-viz
+Version: 0.1.0
+Summary: Visualization toolkit for marmoset homecage behavioral data (marm_behavior outputs).
+Author-email: William Menegas <william.s.menegas@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/williammenegas/marm_viz
+Project-URL: Repository, https://github.com/williammenegas/marm_viz
+Project-URL: Issues, https://github.com/williammenegas/marm_viz/issues
+Keywords: marmoset,behavior,visualization,neuroscience,ethogram
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: h5py>=3.6
+Provides-Extra: annotate
+Requires-Dist: opencv-python>=4.5; extra == "annotate"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: opencv-python>=4.5; extra == "dev"
+
+# marm_viz
+
+Visualization toolkit for marmoset homecage behavioral data. Designed to work with outputs from [`marm_behavior`](https://github.com/williammenegas/marm_behavior).
+
+## Installation
+
+```bash
+pip install marm-viz
+```
+
+## Quick Start
+
+Point `marm_viz` at a folder containing `marm_behavior` outputs (hlabel, hcoord, edges, depths files):
+
+```bash
+# Generate all 10 plot types (default: JPG output)
+python -m marm_viz /path/to/recording_folder
+
+# Single plot type
+python -m marm_viz /path/to/recording_folder --plot ethogram
+
+# Vector output for Illustrator
+python -m marm_viz /path/to/recording_folder --format svg
+```
+
+## Plot Types
+
+| Flag | Output | Description |
+|------|--------|-------------|
+| `qc` | QC panels | 8-panel overview: head XY colored by depth/distance/angle/behavior + histograms |
+| `heatmaps` | Category heatmaps | Per-category spatial occupancy + near-stimulus + overall occupancy + P(move) |
+| `timeseries` | Stim proximity | Fraction near stimulus across time chunks + per-chunk heatmaps + pooled XY |
+| `density` | 2D density | Smoothed occupancy density with contours |
+| `behavior` | State usage + t-SNE | 80-state bar chart grouped by category + t-SNE centroid bubble plot |
+| `ethogram` | Ethogram | Per-category binary raster for each animal across time |
+| `transitions` | Transition matrix | 5x5 category transition probabilities (diagonal NaN'd) |
+| `polar` | Head direction | Polar histogram of head angle relative to stimulus (near vs far) |
+| `track` | Head tracks | Per-animal + merged XY trajectory line plots |
+| `correlation` | Cagemate correlation | Pairwise Spearman correlation of 80-state usage vectors across time chunks |
+
+## CLI Options
+
+```
+--plot TYPE        Which plot to generate (default: all)
+--format FMT       Output format: jpg (default), svg, png, pdf
+--output-dir DIR   Output directory (default: <input>/marm_viz_output/)
+--video STEM       Only process this video stem
+--type-to-use STR  Only process videos whose filename contains STR (case-insensitive)
+--verbose          Print detailed diagnostic information
+--fps N            Frames per second (default: 60)
+--chunk-minutes N  Chunk size in minutes for time series (default: 5)
+--radius-px N      Near-stimulus radius in pixels (default: 120)
+--augment          Enable left/right flip augmentation
+```
+
+## Python API
+
+```python
+from marm_viz import build_recording_set, plot_ethogram
+
+data = build_recording_set("/path/to/folder")
+fig = plot_ethogram(data, fps=60)
+fig.savefig("ethogram.svg")
+```
+
+## License
+
+MIT

marm_viz-0.1.0/README.md

@@ -0,0 +1,68 @@
+# marm_viz
+
+Visualization toolkit for marmoset homecage behavioral data. Designed to work with outputs from [`marm_behavior`](https://github.com/williammenegas/marm_behavior).
+
+## Installation
+
+```bash
+pip install marm-viz
+```
+
+## Quick Start
+
+Point `marm_viz` at a folder containing `marm_behavior` outputs (hlabel, hcoord, edges, depths files):
+
+```bash
+# Generate all 10 plot types (default: JPG output)
+python -m marm_viz /path/to/recording_folder
+
+# Single plot type
+python -m marm_viz /path/to/recording_folder --plot ethogram
+
+# Vector output for Illustrator
+python -m marm_viz /path/to/recording_folder --format svg
+```
+
+## Plot Types
+
+| Flag | Output | Description |
+|------|--------|-------------|
+| `qc` | QC panels | 8-panel overview: head XY colored by depth/distance/angle/behavior + histograms |
+| `heatmaps` | Category heatmaps | Per-category spatial occupancy + near-stimulus + overall occupancy + P(move) |
+| `timeseries` | Stim proximity | Fraction near stimulus across time chunks + per-chunk heatmaps + pooled XY |
+| `density` | 2D density | Smoothed occupancy density with contours |
+| `behavior` | State usage + t-SNE | 80-state bar chart grouped by category + t-SNE centroid bubble plot |
+| `ethogram` | Ethogram | Per-category binary raster for each animal across time |
+| `transitions` | Transition matrix | 5x5 category transition probabilities (diagonal NaN'd) |
+| `polar` | Head direction | Polar histogram of head angle relative to stimulus (near vs far) |
+| `track` | Head tracks | Per-animal + merged XY trajectory line plots |
+| `correlation` | Cagemate correlation | Pairwise Spearman correlation of 80-state usage vectors across time chunks |
+
+## CLI Options
+
+```
+--plot TYPE        Which plot to generate (default: all)
+--format FMT       Output format: jpg (default), svg, png, pdf
+--output-dir DIR   Output directory (default: <input>/marm_viz_output/)
+--video STEM       Only process this video stem
+--type-to-use STR  Only process videos whose filename contains STR (case-insensitive)
+--verbose          Print detailed diagnostic information
+--fps N            Frames per second (default: 60)
+--chunk-minutes N  Chunk size in minutes for time series (default: 5)
+--radius-px N      Near-stimulus radius in pixels (default: 120)
+--augment          Enable left/right flip augmentation
+```
+
+## Python API
+
+```python
+from marm_viz import build_recording_set, plot_ethogram
+
+data = build_recording_set("/path/to/folder")
+fig = plot_ethogram(data, fps=60)
+fig.savefig("ethogram.svg")
+```
+
+## License
+
+MIT

marm_viz-0.1.0/marm_viz/__init__.py

@@ -0,0 +1,63 @@
+"""
+marm_viz
+========
+
+Visualization package for marm_behavior outputs. Loads the artifacts
+written by the marm_behavior pipeline (edges_*.mat, depths_*.mat,
+hlabel_*.csv) into a per-(video x animal) data structure and provides
+a set of plotting routines for spatial, behavioural, and density
+visualizations.
+
+Quick-start (library use)::
+
+    from marm_viz import build_recording_set, plot_qc_panels
+    rs = build_recording_set('path/to/marm_behavior/folder')
+    fig = plot_qc_panels(rs)
+    fig.savefig('qc.png', dpi=150)
+
+Quick-start (CLI)::
+
+    python -m marm_viz path/to/folder --plot qc
+    python -m marm_viz path/to/folder --plot heatmaps
+    python -m marm_viz path/to/folder --plot timeseries
+    python -m marm_viz path/to/folder --plot density --mid-color green
+"""
+
+from .types import Recording, RecordingSet
+from .collect.video_data import build_recording, build_recording_set
+from .plot.qc_panels import plot_qc_panels
+from .plot.category_heatmaps import (
+    plot_category_fraction_heatmaps,
+    plot_xy_occupancy_heatmap,
+    plot_stay_move_heatmaps,
+)
+from .plot.stim_time_series import plot_stim_proximity_time_series
+from .plot.density_2d import plot_density_2d
+from .plot.behavior_overview import plot_state_usage, plot_tsne_centroids
+from .plot.ethogram import plot_ethogram
+from .plot.behavior_detail import (
+    plot_transition_matrix,
+    plot_head_direction_polar,
+)
+from .plot.correlation import plot_cagemate_correlation
+
+__all__ = [
+    "Recording",
+    "RecordingSet",
+    "build_recording",
+    "build_recording_set",
+    "plot_qc_panels",
+    "plot_category_fraction_heatmaps",
+    "plot_xy_occupancy_heatmap",
+    "plot_stay_move_heatmaps",
+    "plot_stim_proximity_time_series",
+    "plot_density_2d",
+    "plot_state_usage",
+    "plot_tsne_centroids",
+    "plot_ethogram",
+    "plot_transition_matrix",
+    "plot_head_direction_polar",
+    "plot_cagemate_correlation",
+]
+
+__version__ = "0.1.0"