Installation#

Please send questions/issues to danrijs@stanford.edu, so we can improve UNRAVEL and/or its documentation
If you are new to the terminal, please see the start of the UNRAVEL guide

TL;DR on Installation#

Activate a virtual environment in Python

# Installing UNRAVEL
git clone https://github.com/b-heifets/UNRAVEL.git
cd UNRAVEL
pip install -e .

# Updating UNRAVEL
git pull 
pip install -e . 

Confirm that installation worked by running:

unravel_commands -c  # or run: uc -c
# This should print common UNRAVEL commands

# For more info, run
uc -h 

Download atlas/template files
- This has an iDISCO/LSFM-specific template that we warped to 30 µm CCFv3 atlas space
Required software:
- FSL for voxel-wise stats, CLI tools, and viewing .nii.gz images with FSLeyes
  - See below on setting this up by adding lines to a terminal configuration file (e.g., .bashrc or .zshrc)
  - Extra steps are required for Windows (even if the GUI does not work, commands may work ok and ITK-SNAP instead of FSLeyes)
- Ilastik for segmenting features of interest
  - See below for .bashrc configuration
Recommended software:
- 3D Slicer for 3D painting to make brains more like the average template (improves registration)
- DSI Studio for 3D brain models.
- Flourish for sunburst plots (free web app)
- Visual Studio Code for viewing source code, debugging, editing files (e.g., .bashrc), etc.
  - Enstall the Python extension

TL;DR on Getting Started#

Review the UNRAVEL guide for analysis steps.
Add raw stitched LSFM data into sample?? folders (e.g., sample01, sample02, …).
Try out the command utils_get_samples to test out batch processing of sample?? folders.
The first command in the workflow is io_metadata.
Each command has a help guide with inputs, outputs, next steps, etc.
For example, run io_metadata -h to get started.

Installing UNRAVEL on Linux or WSL#

Setting Up Windows Subsystem for Linux (WSL)

If you’re new to WSL, watch the first few minutes of this video. After installation, refer to this tutorial for navigating your files.

Installing WSL:

Open the Start menu, search for PowerShell, and right-click to run as Administrator.

Run:

wsl --install  # Installs Ubuntu by default

Restart your computer when prompted.
After the reboot, WSL will be ready. Open PowerShell and type:
```
wsl
```
Follow the prompts to set up your username and password.

To enable copy/paste in PowerShell or WSL, go to the top-left icon –> Properties –> Edit Options –> check “Use Ctrl+Shift+C/V as Copy/Paste” –> OK.

If you install FSL (includes FSLeyes) and Ilastik for linux for use via WSL, the graphic user interface may not work. If that is an issue, try installing the Windows versions.

Running Linux Applications in WSL#

If you install graphical applications like FSL (which includes FSLeyes) or Ilastik for Linux in WSL, the graphical user interface may not work out of the box.

Option 1: Install the Windows versions of these tools for GUI support (the linux versions could still be used for headless processing via commands in WSL)
Option 2: Set up a graphical server, such as VcXsrv, to enable GUIs for Linux applications running in WSL.
- For example, here are detailed steps to set up FSL on Windows: Installation on Windows

Open a terminal
Install venv, pyenv, conda, or other tool(s) to manage Python versions and create a virtual environment:

Setting up a virtual environment for installing python dependencies with venv

Install Python 3.11 if it’s not already installed:

For Linux and WSL:

sudo apt-get update
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev

For macOS:

brew install python@3.11

Create and activate a virtual environment:

python3.11 -m venv unravel
source unravel/bin/activate  # Edit path if needed. To deactivate, run: deactivate

Easier virtual environment activation with venv

Automatically Activate or Create an Alias for Your Virtual Environment

You can either set your virtual environment to activate automatically when opening a terminal, or create an alias for easier activation.

Open your .bashrc or .zshrc file with a code editor:

Using nano:

nano ~/.bashrc  # or ~/.zshrc for zsh

Using VS Code:

code ~/.bashrc  # or ~/.zshrc for zsh

For automatic activation, add the following line to the end of the file:

source unravel/bin/activate   # Edit path if needed

Or, to create an alias, add this line instead:

alias unravel="source unravel/bin/activate"  # Edit path if needed

Save and apply the changes:
- If using nano, press Ctrl+X to exit and follow the prompts.
- Apply changes by running:
```
source ~/.bashrc  # or ~/.zshrc for zsh
```

Now, either your virtual environment will automatically activate when you open a terminal, or you can activate it using the unravel command.

Install UNRAVEL

With your virtual environment active, follow these steps to install UNRAVEL

Option A: Editable installation of UNRAVEL (recommended)

This is allows for editing source code and incremental updates.

cd <path>  # Insert path to where you want to clone the GitHub repository

git clone https://github.com/b-heifets/UNRAVEL.git  # Code from the main branch is downloaded

cd UNRAVEL

pip install -e .  # This installs python dependencies and sets up commands (both defined in pyproject.toml)

Option B: Install UNRAVEL via PyPI and use it as-is

pip install heifetslab-unravel

Download atlas/template files:
- Google Drive Link
- We use a 30 µm version of the mouse Allen brain atlas (CCFv3 with 2020 region labels): atlas_CCFv3_2020_30um.nii.gz
- The left hemisphere region labels/IDs are increased by 20,000 in this version: atlas_CCFv3_2020_30um_split.nii.gz
- For registeration with iDISCO/LSFM data, use this iDISCO_template_CCFv3_30um.nii.gz (we warped the Gubra atlas to CCFv3 space and refined alignment)
- For registeration with serial 2P data, use: average_template_CCFv3_30um.nii.gz
- This binary brain mask can be used for 3D brain models: mask_CCFv3_2020_30um.nii.gz
- Use a template that matches your tissue, along with a mask that includes only regions of interest.
Install Ilastik:
- Ilastik installation website.
- This is used for making a brain mask and segmenting features of interest (e.g., c-Fos+ cells)
Install FSL:
- Follow the installation instructions from the FSL website.
- FSL includes FSLeyes, which is useful for visualizing data in atlas space and with colored wireframe atlas.
- Some scripts depend on FSL.
- FSL has several command line tools (e.g., fslmaths, fslstats, fslroi, fslcpgeom) that are useful for working with .nii.gz images.
- Check that commands work after setting up .bashrc (step 9)
```
fslmaths -h  # This should print the help for fslmaths after .bashrc is set up (see below)
```
- Check if the GUIs work
```
fsleyes  # This .nii.gz image viewer is useful for checking registration and p value maps
fsl  # This is used for making files for voxel-wise ANOVAs
```
- If FSL’s GUI’s don’t work, ITK-SNAP can be used. Contact us for info, a look-up table for atlas coloring, and a wireframe atlas.
Optional: Install 3D Slicer
- 3D Slicer installation
- This is useful for improving registration by making the autofluo tissue better match the average template (e.g., digitally trimming or adding tissue)
Confirm that the installation worked
```
unravel_commands -c 
```
Edit .bashrc or .zshrc to set up dependencies
- Add the following to your .bashrc or .zshrc shell configuration file, and change /usr/local/ to the path where FSL and Ilastik are installed:
```
FSLDIR=/usr/local/fsl  # Update the path to fsl
. ${FSLDIR}/etc/fslconf/fsl.sh
PATH=${FSLDIR}/bin:${PATH}
export FSLDIR PATH

export PATH=/usr/local/ilastik-1.4.0.post1-Linux:$PATH  # Update the path and version
```
- Apply the changes by restarting the terminal or source your shell configuration file:
```
. ~/.bashrc
```

Update scripts periodically:

Hint

Note the release/version and/or backup code before updating for reproducibility

Option A. Updating UNRAVEL if installed via GitHub:

cd <path/to/UNRAVEL>
git pull  # This will update the local repo, pulling the latest code from the main branch
pip install -e .  # This will update commands and install new dependencies

Option B. Updating UNRAVEL if installed via PyPI:

pip install --upgrade heifetslab-unravel

# Check the installed version of UNRAVEL
pip show heifetslab-unravel

To check the latest version, go to the heifetslab-unravel PyPI page

Checking UNRAVEL Version Changes#

Releases and update notes for UNRAVEL can be found here on GitHub.
For more detailed information, you can view the commit history:
- Main branch commits
- Dev branch commits

Viewing Images:#

For full-resolution LSFM images, use Fiji or napari.
NIfTI images (.nii.gz) are commonly used in neuroimaging analysis.
- They compress well when the images are ~small or if there are many voxels with an intensity of zero.
- They can be viewed with Fiji, napari, or neuroimaging viewers (e.g., FSLeyes or 3D Slicer).
- Fiji needs the nifti_io plugin
- Napari needs the napari-nifti plugin
- FSLeyes is great for viewing the atlas_CCFv3_2020_30um.nii.gz and matching images; however, it does not work for the 10 µm atlas and larger images.
- For larger .nii.gz images, use 3D Slicer, ITK-SNAP, Fiji, or napari
.zarr images are useful for fast compression of large images with lots of non-zero voxels (e.g., raw LSFM data)
- Use napari to view them.

Get Started With Analysis#

UNRAVEL guide