aind-behavior-utils 0.3.2__tar.gz → 0.3.4__tar.gz

{aind_behavior_utils-0.3.2 → aind_behavior_utils-0.3.4}/.github/workflows/tag_and_publish.yml

@@ -62,9 +62,9 @@ jobs:
         add: '["README.md"]'
   tag:
     needs: update_badges
-    uses: AllenNeuralDynamics/aind-github-actions/.github/workflows/tag.yml@main
+    uses: AllenNeuralDynamics/.github/.github/workflows/release-bump-version.yml@main
     secrets:
-      SERVICE_TOKEN: ${{ secrets.SERVICE_TOKEN }}
+      repo-token: ${{ secrets.SERVICE_TOKEN }}
   publish:
     needs: tag
     if: true

{aind_behavior_utils-0.3.2 → aind_behavior_utils-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aind-behavior-utils
-Version: 0.3.2
+Version: 0.3.4
 Summary: Generated from aind-library-template
 Author: Allen Institute for Neural Dynamics
 License: MIT

aind_behavior_utils-0.3.4/docs/CAMStim Behavior Pickle Structure.md

@@ -0,0 +1,499 @@
+# Camstim Behavior Pickle File Structure
+
+This document describes the data structure of a Camstim behavior pickle file (`*_stim.pkl`) generated during a visual change detection task session.
+
+## Loading the File
+
+```python
+import pickle
+
+with open("1464696201_stim.pkl", "rb") as p:
+    data = pickle.load(p, encoding="latin1")
+```
+
+---
+
+## Top-Level Keys
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `comp_id` | str | Computer identifier |
+| `items` | dict | Main data container — see [Items](#items) |
+| `start_time` | datetime | Session start time |
+| `stop_time` | datetime | Session stop time |
+| `script` | str | Script text used to run the session |
+| `rig_id` | str | Rig identifier |
+| `threads` | list | Thread info (typically empty) |
+| `session_uuid` | str | Unique session identifier |
+| `platform_info` | dict | Software version info — see [Platform Info](#platform-info) |
+
+---
+
+## Platform Info
+
+`data["platform_info"]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `camstim` | str | Camstim version |
+| `opengl` | str | OpenGL version |
+| `python` | str | Python version |
+| `rig_id` | str | Rig identifier |
+| `hardware` | tuple | Hardware info |
+| `pyglet` | str | Pyglet version |
+| `os` | str | Operating system |
+| `psychopy` | str | PsychoPy version |
+| `camstim_git_hash` | None | Git hash of camstim (if available) |
+
+---
+
+## Items
+
+`data["items"]["behavior"]`
+
+The top-level `items` dict contains a single key `behavior` with the following fields:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `lick_sensors` | list | Lick sensor data — see [Lick Sensors](#lick-sensors) |
+| `volume_dispensed` | list | String stored in a list (total volume dispensed) |
+| `rewards_dispensed` | int | Total number of rewards dispensed |
+| `rewards` | list | Reward event data — see [Rewards](#rewards) |
+| `params` | dict | Task parameters — see [Params](#params) |
+| `window` | dict | Display window configuration — see [Window](#window) |
+| `trial_log` | list | Per-trial data — see [Trial Log](#trial-log) |
+| `auto_update` | bool | Whether auto-update was enabled |
+| `encoders` | list | Running wheel encoder data — see [Encoders](#encoders) |
+| `sync_pulse` | None | Sync pulse data (typically None) |
+| `stim_config` | dict | Stimulus display config — see [Stim Config](#stim-config) |
+| `cl_params` | dict | Full closed-loop params as delivered — see [CL Params](#cl-params) |
+| `stimuli` | dict | Stimulus presentation logs — see [Stimuli](#stimuli) |
+| `omitted_flash_frame_log` | dict | Dict of `{image_name: [frame_indices]}` for omitted flashes |
+| `update_count` | int | Number of update cycles |
+| `behavior_text` | str | Behavior script text (often empty) |
+| `intervalsms` | array | Frame interval durations in ms, shape `(n_frames,)` |
+| `nidaq_tasks` | dict | NI-DAQ task configuration |
+
+---
+
+## Lick Sensors
+
+`behavior["lick_sensors"][0]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `lick_events` | list | Initial contact lick events (tongue-first-touch) |
+| `lick_data` | list | All detected lick samples |
+| `line` | — | DAQ line identifier |
+
+---
+
+## Rewards
+
+`behavior["rewards"][0]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `calibration` | — | Solenoid calibration data |
+| `reward_times` | list | List of `(time_ms, frame_index)` tuples for each reward |
+| `reward_count` | int | Total number of rewards delivered |
+| `volume_dispensed` | float | Total volume dispensed (µL) |
+
+---
+
+## Params
+
+`behavior["params"]`
+
+Task parameters set at runtime.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `auto_reward_delay` | int | Delay before auto-reward is delivered |
+| `free_reward_trials` | int | Number of trials with free (unconditional) rewards |
+| `end_after_response` | bool | Grace period after stimulus change — licks cannot trigger abort |
+| `change_flashes_max` | int | Maximum flashes before a change can occur |
+| `change_flashes_min` | int | Minimum flashes before a change can occur |
+| `change_time_dist` | str | Distribution for change timing (e.g. `"geometric"`) |
+| `change_time_scale` | float | Scale parameter for change time distribution |
+| `stimulus_window` | float | Duration of the stimulus window (s) |
+| `response_window` | list[float] | `[start, end]` of response window in seconds |
+| `catch_frequency` | float | Frequency of catch trials (NaN if not set) |
+| `min_no_lick_time` | float | Minimum no-lick time required before trial start |
+| `timeout_duration` | float | Timeout duration after an aborted trial (s) |
+| `volume_limit` | float | Maximum total reward volume per session (µL) |
+| `max_task_duration_min` | float | Maximum session duration (minutes) |
+| `reward_volume` | float | Volume per reward delivery (µL) |
+| `end_after_response_sec` | float | Duration of post-response grace period (s) |
+| `start_stop_padding` | float | Padding time at session start/stop (s) |
+| `periodic_flash` | list[float] | `[on_duration, off_duration]` for periodic flashing (s) |
+| `failure_repeats` | int | Number of times to repeat a failed trial |
+| `warm_up_trials` | int | Number of auto-reward warm-up trials at session start |
+| `pre_change_time` | float | Duration of the pre-change period (s) |
+| `stage` | str | Stage name |
+| `task_id` | str | Task identifier |
+| `stimulus` | dict | Stimulus class config — see [Stimulus Config](#stimulus-config-in-params) |
+| `epilogue` | dict | Epilogue movie config — see [Epilogue](#epilogue) |
+
+### Epilogue
+
+`params["epilogue"]`
+
+| Key | Path | Type | Description |
+|-----|------|------|-------------|
+| `name` | `epilogue["name"]` | str | Epilogue name |
+| `frame_length` | `epilogue["params"]["frame_length"]` | float | Frame length (s) |
+| `movie_path` | `epilogue["params"]["movie_path"]` | str | Path to epilogue movie file |
+| `runs` | `epilogue["params"]["runs"]` | int | Number of times to play the movie |
+| `size` | `epilogue["params"]["size"]` | list[int, int] | Movie frame size in pixels |
+
+### Stimulus Config in Params
+
+`params["stimulus"]`
+
+| Key | Path | Type | Description |
+|-----|------|------|-------------|
+| `image_set` | `stimulus["params"]["image_set"]` | str | Path to the image set |
+| `sampling` | `stimulus["params"]["sampling"]` | str | Sampling strategy |
+| `class_type` | `stimulus["class"]` | str | Python class name for the stimulus |
+
+---
+
+## Window
+
+`behavior["window"]`
+
+PsychoPy window configuration and state captured at session end.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `scrDistCM` | int | Screen distance in cm |
+| `scrWidthCM` | int | Screen width in cm |
+| `scrWidthPIX` | int | Screen width in pixels |
+| `mon_width_pix` | int32 | Monitor width in pixels |
+| `mon_height_pix` | int32 | Monitor height in pixels |
+| `mon_width_cm` | int | Monitor width in cm |
+| `mon_height_cm` | float | Monitor height in cm |
+| `dist_cm` | int | Viewing distance in cm |
+| `aspect` | float | Aspect ratio |
+| `size` | array[int, int] | Window size `[width, height]` in pixels |
+| `pos` | array[int, int] | Window position on screen |
+| `color` | array[float] | Background color as RGB floats `[r, g, b]` |
+| `colorSpace` | str | Color space (e.g. `"rgb"`) |
+| `rgb` | array[float] | RGB values |
+| `flipCounter` | int | Total number of frame flips |
+| `frames` | int | Total frames rendered |
+| `frameIntervals` | list | Per-frame interval durations (s) |
+| `monitorFramePeriod` | float | Nominal frame period (s) |
+| `nDroppedFrames` | int | Number of dropped frames |
+| `recordFrameIntervals` | bool | Whether frame intervals were recorded |
+| `warpGridsize` | int | Warp grid size |
+| `warp` | int | Warp mode |
+| `warpfile` | None | Warp file path |
+| `projectorType` | int | Projector type code |
+| `useFBO` | bool | Whether FBO was used |
+| `useNativeGamma` | bool | Whether native gamma was used |
+| `gamma` | array[float] | Gamma values `[r, g, b]` |
+| `origGammaRamp` | array | Original gamma ramp, shape `(3, 256)` |
+| `blendMode` | str | Blend mode |
+| `units` | str | Default units |
+| `viewScale` | None | View scale |
+| `viewPos` | None | View position |
+| `viewOri` | float | View orientation |
+| `flipHorizontal` | bool | Horizontal flip |
+| `flipVertical` | bool | Vertical flip |
+| `flipEvery3rdFrame` | bool | Whether every 3rd frame is flipped |
+| `stereo` | bool | Stereo mode |
+| `screen` | int | Screen index |
+| `allowStencil` | bool | Whether stencil buffer is allowed |
+| `allowGUI` | bool | Whether GUI is allowed |
+| `winType` | str | Window type |
+| `mouseVisible` | str | Mouse cursor visibility |
+| `movieFrames` | list | Captured movie frames |
+| `autoLog` | bool | Whether auto-logging is enabled |
+| `config_path` | str | Path to monitor config file |
+| `config` | dict | Monitor config — see [Window Config](#window-config) |
+| `monitor` | dict | PsychoPy monitor calibration object |
+| `xgrid` / `ygrid` | int | Grid dimensions |
+| `nverts` | int | Number of warp vertices |
+
+### Window Config
+
+`window["config"]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `showmouse` | bool | Whether mouse cursor is shown |
+| `monitor_brightness` | int | Monitor brightness level |
+| `fps` | float | Target frame rate |
+| `monitor_contrast` | int | Monitor contrast level |
+
+---
+
+## Trial Log
+
+`behavior["trial_log"]` — list of trial dicts, one per trial.
+
+`trial_log[i]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `index` | int | Trial number (0-indexed) |
+| `cumulative_rewards` | int | Total rewards delivered up to and including this trial |
+| `cumulative_volume` | float | Total reward volume dispensed up to this trial (µL) |
+| `licks` | list[tuple] | List of `(time_s, frame_index)` tuples for licks during this trial |
+| `stimulus_changes` | list | Stimulus change events during this trial |
+| `success` | bool | Whether the trial was a hit |
+| `rewards` | list | Rewards delivered during this trial |
+| `trial_params` | dict | Trial-specific parameters — see [Trial Params](#trial-params) |
+| `encoder` | dict | Running wheel snapshot for this trial — see [Trial Encoder](#trial-encoder) |
+| `events` | list[list] | Ordered behavioral events — see [Trial Events](#trial-events) |
+
+### Trial Events
+
+`trial["events"]` — list of `[event_name, activity, time_s, frame_index]` entries.
+
+| Event Name | Description |
+|------------|-------------|
+| `trial_start` | Trial begins |
+| `initial_blank` | Initial blank period |
+| `pre_change` | Pre-change period (gray screen with flashes) |
+| `stimulus_window` | Active window where a change can be detected |
+| `early_response` | Mouse licked before the response window |
+| `abort` | Trial aborted (early lick or no-lick timeout) |
+| `timeout` | Timeout period after an abort |
+| `trial_end` | Trial ends |
+
+### Trial Params
+
+`trial["trial_params"]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `catch` | bool | Whether this is a catch trial (no image change) |
+| `auto_reward` | bool | Whether an automatic reward was given (warm-up trials) |
+| `change_time` | int | Flash index at which the change occurred |
+
+### Trial Encoder
+
+`trial["encoder"]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `count` | int | Encoder count |
+| `radius_cm` | float | Wheel radius in cm |
+| `degree` | — | Rotation in degrees |
+
+---
+
+## Encoders
+
+`behavior["encoders"][0]` — full running wheel encoder log for the session.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `counter_index` | int | Counter index |
+| `distance` | float | Total distance traveled (cm) |
+| `mdr0_register_setting` | str | MDR0 register setting |
+| `base_time` | int | Base timestamp |
+| `timestamp` | array[float32] | Timestamps for each encoder sample |
+| `arduino_version` | str | Arduino firmware version |
+| `treadmill` | bool | Whether a treadmill was used |
+| `vin` | array | Input voltage signal |
+| `vsig` | array | Signal voltage |
+| `index_list` | array | List of encoder indices |
+| `catching_encoder_failures` | int | Count of encoder failures caught |
+| `degrees` | array | Rotation in degrees per sample |
+| `dx` | array | Position delta per sample |
+| `counts` | array | Raw encoder counts |
+| `analog_encoder` | bool | Whether an analog encoder was used |
+| `raw_data` | array | Raw encoder data |
+| `encoder_radius` | float | Encoder wheel radius (cm) |
+
+---
+
+## Stim Config
+
+`behavior["stim_config"]`
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `showmouse` | bool | Whether mouse cursor is shown |
+| `monitor_brightness` | int | Monitor brightness level |
+| `fps` | float | Target frame rate |
+| `monitor_contrast` | int | Monitor contrast level |
+
+---
+
+## CL Params
+
+`behavior["cl_params"]`
+
+The full set of closed-loop task parameters as delivered to the task at runtime. These largely mirror [Params](#params) with some additions.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `auto_reward_delay` | float | Delay before auto-reward |
+| `free_reward_trials` | int | Free reward trial count |
+| `end_after_response` | bool | End trial after response |
+| `stimulus_window` | float | Stimulus window duration (s) |
+| `change_flashes_max` | int | Max flashes before change |
+| `change_flashes_min` | int | Min flashes before change |
+| `mouse_id` | str | Mouse subject ID |
+| `user_id` | str | Experimenter user ID |
+| `change_time_dist` | str | Change time distribution |
+| `response_window` | list[float] | `[start, end]` of response window (s) |
+| `catch_frequency` | None | Catch trial frequency |
+| `min_no_lick_time` | float | Min no-lick time before trial (s) |
+| `volume_limit` | float | Max reward volume (µL) |
+| `max_task_duration_min` | float | Max session duration (minutes) |
+| `end_after_response_sec` | float | Post-response grace period (s) |
+| `start_stop_padding` | float | Start/stop padding (s) |
+| `periodic_flash` | list[float] | Flash on/off durations (s) |
+| `timeout_duration` | float | Abort timeout duration (s) |
+| `failure_repeats` | int | Failure repeat count |
+| `warm_up_trials` | int | Number of warm-up (auto-reward) trials |
+| `pre_change_time` | float | Pre-change period duration (s) |
+| `auto_reward_vol` | float | Auto-reward volume (µL) |
+| `stage` | str | Stage name |
+| `task_id` | str | Task identifier |
+| `epilogue` | dict | Epilogue config — same structure as [Epilogue](#epilogue) |
+| `stimulus` | dict | Stimulus config — same structure as [Stimulus Config in Params](#stimulus-config-in-params) |
+
+---
+
+## Stimuli
+
+`behavior["stimuli"]["images"]`
+
+Logs of all stimulus presentations during the session.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `image_set` | str | Path to the image set used |
+| `image_path` | str | Path to image files |
+| `obj_type` | str | Stimulus object type |
+| `size` | tuple[int, int] | Stimulus size in pixels |
+| `pos` | tuple | Stimulus position |
+| `units` | str | Stimulus units |
+| `sampling` | str | Image sampling strategy |
+| `fps` | float | Display frame rate |
+| `flash_interval_sec` | list[float] | `[on_duration, off_duration]` for each flash (s) |
+| `flash_omit_probability` | float | Probability of omitting a flash |
+| `flashes_omitted` | list[int] | Frame indices where flashes were omitted |
+| `draw_log` | list[int] | Per-frame draw flag: `1` = image drawn, `0` = not drawn |
+| `set_log` | list[tuple] | Log of every image set event — see [Set Log](#set-log) |
+| `change_log` | list[tuple] | Log of every image change event — see [Change Log](#change-log) |
+| `stim_groups` | list[tuple] | Stimulus group definitions |
+| `image_walk` | list[array] | Ordered sequence of images shown |
+| `sampling_matrix` | array | Sampling matrix, length 64 |
+| `initial_group` | str | Name of the initial stimulus group |
+| `correct_freq` | float | Correct response frequency |
+| `stimulus` | dict | PsychoPy ImageStim object state — see [ImageStim](#imagestim) |
+| `sequence` | None | Image sequence (unused) |
+| `correct_table` | None | Correct response table (unused) |
+| `incorrect_table` | None | Incorrect response table (unused) |
+| `possibility_table` | None | Possibility table (unused) |
+| `log` | list | General log (typically empty) |
+| `on_draw` | dict | On-draw callbacks (typically empty) |
+| `kwargs` | dict | Additional kwargs |
+| `param_names` | None | Parameter names (unused) |
+
+### Set Log
+
+`stimuli["images"]["set_log"]` — list of tuples recording every image presentation.
+
+```
+('Image', 'im000', 5.3695128, 0)
+  ^        ^        ^           ^
+  type     image    timestamp   frame_index
+           name     (s, display-relative)
+```
+
+> **Timing note:** Set log timestamps are relative to when the display started, not the absolute session clock. The absolute session time of the first image is `trial_log[0]["events"][0][2]` (trial_start). The offset between display-relative and absolute time is approximately the gray-screen duration before the task begins (~300 s).
+
+### Change Log
+
+`stimuli["images"]["change_log"]` — list of tuples recording every stimulus change.
+
+```
+(('im000', 'im000'), ('im031', 'im031'), 312.1264287, 18390)
+  ^                    ^                  ^            ^
+  (from_group,         (to_group,         timestamp    frame_index
+   from_image)          to_image)         (s, absolute)
+```
+
+### Draw Log
+
+`stimuli["images"]["draw_log"]` — integer array with one entry per display frame.
+
+- `1` = an image was drawn on this frame
+- `0` = no image was drawn (gray screen, inter-flash interval, or omitted flash)
+
+Used to reconstruct precise image onset/offset times from frame indices.
+
+---
+
+## ImageStim
+
+`stimuli["images"]["stimulus"]`
+
+PsychoPy `ImageStim` object state captured at session end.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `_rotationMatrix` | array (2,2) | Rotation matrix |
+| `rgbPedestal` | list[float] | RGB pedestal values |
+| `color` | array (1,3) | Color |
+| `colorSpace` | str | Color space |
+| `pos` | array (1,2) | Position |
+| `size` | array (1,2) | Size in display units |
+| `_requestedSize` | array (1,2) | Originally requested size |
+| `_origSize` | None | Original image size |
+| `rgb` | array (1,3) | RGB values |
+| `contrast` | float | Contrast |
+| `opacity` | float | Opacity |
+| `ori` | float | Orientation (degrees) |
+| `useShaders` | bool | Whether shaders are used |
+| `texRes` | int | Texture resolution |
+| `interpolate` | float | Interpolation setting |
+| `mask` | None | Mask |
+| `maskParams` | None | Mask parameters |
+| `isLumImage` | bool | Whether image is luminance-only |
+| `flipHoriz` | bool | Horizontal flip |
+| `flipVert` | bool | Vertical flip |
+| `_verticesBase` | array (4,2) | Base vertex positions |
+| `verticesPix` | array (4,2) | Vertex positions in pixels |
+| `_needUpdate` | bool | Update flag |
+| `_needTextureUpdate` | bool | Texture update flag |
+| `_needVertexUpdate` | bool | Vertex update flag |
+| `_tex1D` | bool | 1D texture flag |
+| `image` | None | Loaded image (not serialized) |
+| `_imName` | None | Image name (internal) |
+| `_listID` | int | OpenGL display list ID |
+| `_initParams` | list[str] | List of initialized parameter names |
+| `units` | str | Stimulus units |
+| `name` | str | Stimulus name |
+| `depth` | int | Depth (draw order) |
+| `status` | int | PsychoPy status flag |
+| `autoLog` | bool | Auto-logging flag |
+
+---
+
+## Session Epochs
+
+The session is divided into two epochs based on `trial_params["auto_reward"]`:
+
+| Epoch | Description |
+|-------|-------------|
+| **Warm-up** | First `warm_up_trials` trials — rewards are given automatically regardless of response |
+| **Change detection** | Remaining trials — mouse must respond within the response window to receive a reward |
+
+The boundary can be found programmatically:
+
+```python
+warmup_end_idx = next(
+    i for i, t in enumerate(trial_log)
+    if not t["trial_params"]["auto_reward"]
+)
+```