Skip to content

Prattbuw documentation #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Prattbuw wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Prattbuw documentation #19

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a616353
Update README.md
Prattbuw May 15, 2025
ab96c65
Update Lifealert section of README.md
Prattbuw May 16, 2025
52a73fa
Update neural activity visualization section of README.md
Prattbuw May 16, 2025
ccc8beb
Revised documentation
Prattbuw May 29, 2025
4c2eeb1
Create animal-handling-chronic-recordings.md
Prattbuw May 29, 2025
b485d3e
Added animal-handling-log
Prattbuw May 29, 2025
c1f0cb8
Delete docs/references/animal-handling-chronic-recordings.md
Prattbuw May 29, 2025
ea262b0
Delete docs/references/animal-handling-log.pdf
Prattbuw May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 89 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,93 @@
# Aind.Behavior.Pirouette

A repository with source code for long-term, freely moving, electrophisiology recordings in mice
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep a high-level description of the repo in the readme. Feel free to change it, but it would be great to leave one.

Authors: Bruno Cruz, Brandon Pratt, and Carl Schoonover
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I generally avoid adding this to the readme since the repository already keeps track of contributors. If you want to add Carl, he just has to push a single commit, or you can add him as a co-author in one of them.


## Getting started
Last Updated: 05/15/2025
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Last Updated is also redundant since this is one of the major perks of using Github for documentation. Changes are tracked for free.

Copy link
Collaborator Author

@Prattbuw Prattbuw May 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point!


1. Clone this repository
2. Regenerate the Bonsai environment by running `setup.ps1` from the `./bonsai` directory
3. Open Bonsai by running `./bonsai/Bonsai.exe`
4. Open the desired script from the `./src` directory
A repository with source code and instructions for long-term, electrophisiology recordings in behaving mice

---
## Content
### 1. Getting started
### 2. Pirouette Bonsai workflow
### 3. Lifealert
### 4. Neural activity visualization
---
### 1. Getting started
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds like instructions to setup the experiment in the Allen. As we discussed previously, it would be nice to leave the entry-point to the repo somewhat agnostic. Wouldnt it make more sense to put these instructions in a separate docs file? We can also just trigger the build of the sphinx website and move this there.

You should also consider linking, or reproducing the following deployment scipt: https://github.com/AllenNeuralDynamics/Aind.Behavior.Services/blob/main/scripts/install_dependencies.ps1

This is what I use for all tasks and it is what SIPE is using as reference for automatic deployment

1. If using a new computer, contact IT to set up the "svc_aind_chronic" service account, which is the account that all Pirouette systems use.
2. Clone this repository using git clone (may need to generate an ssh key and link it with your GitHub account -- https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repo is public, i dont think this is needed

3. Clone the lifealert repository (https://github.com/AllenNeuralDynamics/lifealert).
4. Install FFMPEG (https://www.wikihow.com/Install-FFmpeg-on-Windows).
5. Install UV package manager (https://docs.astral.sh/uv/).
6. In the root of the Aind.Behavior.Pirouette and lifealert, execute `uv sync` to install the dependencies denoted in the uv.lock file.
7. Regenerate the Bonsai environment in the Pirouette repo by running `setup.ps1` from the `./bonsai` directory.
8. Generate the rig.json, session.json, and task.json configuration files by running example.py found within the examples directory (update the content to reflect current experimental parameters, like device IDs).
---
### 2. Pirouette Bonsai workflow
1.Open Git Bash, navigate to the Aind.Behavior.Pirouette remote directory, and luanch visual studio.
Copy link
Member

@bruno-f-cruz bruno-f-cruz May 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing. In the previous section you tell people to use uv, but know you are telling them to run the workflow using a different tool?
I can see two solutions:

  1. Always tell them to use uv
  2. Explain the different ways to start bonsai, including passing the schema files as inputs
  3. Wrap the whole experiment in a launcher that takes care of the life-alert + launching bonsai with one command

Copy link
Collaborator Author

@Prattbuw Prattbuw May 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the third point as an issue in the repo because a launcher that takes care of both life-alert and Bonsai is something I would like to add in the future.


<img src="https://github.com/user-attachments/assets/5a7f9441-c6d2-4c14-8cb9-c3303e97611e" width="600">

2.Activate the virtual environments by executing `source .venv/Scripts/activate`.

<img src="https://github.com/user-attachments/assets/7dce5ce1-c64f-4ba2-bdc4-c9fc3cbd56ec" width="600">

3.Open Bonsai by running `./Bonsai.exe` within the bonsai directory.

<img src="https://github.com/user-attachments/assets/5bc1bf8e-a49a-4077-ac94-ea70eb1c1bfb" width="600">

4.Open the desired Pirouette script from the `./src` directory ("WrappedPirouette.bonsai" as of 5/15/2025).

<img src="https://github.com/user-attachments/assets/56c56e8d-2e13-40f8-a00c-e6d33f334e4d" width="600">

5.Load the Neuropixels 2.0 probe configuration file using the GUI that appears after double clicking on the "Headstage Neuropixel V2e" operator, which is located `pirouette/hardware/onix`. Also, make sure that the "Channel Presets" is set to "AllShanks0_95"(bottom sites on each shank). Note that the Probe Interface file (needed for SpikeInterface and compression) can be saved in the way that the image shows.

<img src="https://github.com/user-attachments/assets/fcf3011b-8dea-499d-b394-9c06df305576" width="600">
<img src="https://github.com/user-attachments/assets/c74938f6-3196-4742-be1d-0dee4f397000" width="600">

6.Check that the read block size in the StartAcquistion operator is set to 1048576 bytes.
7.Test the workflow before plugging in a mouse by instead plugging in the broken probe into the headstage, and launching the Bonsai workflow by pressing the start button. Check that the commutator rotates in the same direction as the probe.

<img src="https://github.com/user-attachments/assets/80d15458-45ee-46fb-9383-4ff0f4c95408" width="600">

8.Before proceeding, launch lifealert (see section below).

9.Plug the probe implanted in the mouse's brain into the headstage.

10.While holding the mouse, press "Start" (green arrow) to launch the workflow and turn on commutation. Confirm that the commutator is working.

11.Begin the experiment by placing the mouse in the behavior box.

---
### 3. Lifealert
1.Open Git Bash, navigate to the lifealert remote directory, and luanch visual studio.
2.Activate the virtual environments by executing `source .venv/Scripts/activate`.
3.Lauch the alert system by running `uv run .\src\lifealert\listner.py`. Once the Pirouette Bonsai workflow is started, a "heart beat" will be detected, which will be displayed in the command terminal where listener.py was run.

<img src="https://github.com/user-attachments/assets/e27c959c-ba8a-4b1e-ae97-769a64c126b3" width="600">

4.If an error occurs in Bonsai that stops the workflow, the error message and lack of heart beats (in 60 s intervals) will be displayed in the terminal. Note that the error and missing heart beats will be sent to the "Chronic Alerts" teams channel and as emails using PowerAutomate.

---
### 4. Neural activity visualization
Visualiztion of neural activity is done on the surgery computer in Lab 343. The directories of interest are located on the desktop and called "LOAD BONSAI-ONIX STREAM IN SPIKEGLX" and "LOAD BONSAI-ONIX STREAM IN OPENEHPYS". Below are instructions for the recommended way of visualizing data in SpikeGLX, but at the root of both directories is an "instructions.txt" file that can be used for visualizing data collected using Bonsai and Onix.

1.Copy .bin file that was collected using the Onix system to: \test-day7-Tuesday-May-13-g0\test-day7-Tuesday-May-13_g0_imec0 (Ignore the date, it doesn't matter for visualization).

2.Rename the .bin file to test-day7-Tuesday-May-13-g0_t0.imec0.ap.bin (if there was a previous file with that name, append something relevant to that file, like "_OLD".

3.The fileSizeBytes parameter within the .meta file needs to be updated to the number of bytes the .bin file is, which can be found by looking at the files properties.

4.Open SpikeGLX, File -->New Acquistion.

5.If slot 40 isn't already available, click Configure Slots and add 40 (i.e. the simulation slot).

6.In the probe table, enable slot 40, Port 1, Dock 1, and disable everything else.

7.Click "Detect" and then "Run".

8.Plot with the following settings: 300-INF filtering, <Tn> enabled, Glb Dmx, and BinMax enabled.

9.The recording neural activity can now be played from beginning to end.

10.OPTIONAL: the file can be also opened in SpikeGLX by File --> Open File Viewer. Select the .bin file, and plot with the following settings: 300-INF filtering, <Tn> enabled, Glb Dmx, and BinMax "Faster".