Installation#

A full installation of the OHBA Software Library (OSL) includes:

  • FSL (FMRIB Software Library) - only needed if you want to do source reconstruction.

  • Miniconda (or Anaconda).

  • OSL (OHBA Software Library).

  • osl-dynamics (OSL Dynamics Toolbox) - only needed if you want to train models for dynamics.

Linux Instructions#

  1. Install FSL using the instructions here.

  2. Install Miniconda inside the terminal:

    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
rm Miniconda3-latest-Linux-x86_64.sh

If you’re using a high-performance computing cluster, you may already have conda installed as a software module and might be able to load Anaconda with:

module load Anaconda

and skip step 2.

  1. Install OSL and osl-dynamics:

    curl https://raw.githubusercontent.com/OHBA-analysis/osl/main/envs/linux-full.yml > osl.yml
conda env create -f osl.yml
rm osl.yml

This will create a conda environment called osl which contains both OSL and osl-dynamics.

Mac Instructions#

Instructions:

  1. Install FSL using the instructions here.

  2. Install Miniconda inside the terminal:

    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh
rm Miniconda3-latest-MacOSX-x86_64.sh

  3. Install OSL and osl-dynamics:

    curl https://raw.githubusercontent.com/OHBA-analysis/osl/main/envs/mac-full.yml > osl.yml
conda env create -f osl.yml
rm osl.yml

This will create a conda environment called osl which contains both OSL and osl-dynamics.

Windows Instructions#

If you’re using a Windows machine, you will need to install the above in Ubuntu using a Windows subsystem.

Instructions:

  1. Install FSL using the instructions here. Make sure you setup XLaunch for the visualisations.

  2. Install Miniconda inside your Ubuntu terminal:

    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
rm Miniconda3-latest-Linux-x86_64.sh

  3. Install OSL and osl-dynamics:

    curl https://raw.githubusercontent.com/OHBA-analysis/osl/main/envs/linux-full.yml > osl.yml
conda env create -f osl.yml
rm osl.yml

This will create a conda environment called osl which contains both OSL and osl-dynamics.

Loading the packages#

To use OSL/osl-dynamics you need to activate the conda environment:

conda activate osl

You need to do every time you open a new terminal. You know if the osl environment is activated if it says (osl)[...] at the start of your terminal command line.

Note, if you get a conda init error when activating the osl environment during a job on an HPC cluster, you can resolve this by replacing:

conda activate osl

with:

source activate osl

Integrated Development Environments (IDEs)#

The OSL installation comes with Jupyter Notebook. To open Jupyter Notebook use:

conda activate osl
jupyter notebook

There is also an installation with Sypder. To install this on linux use the envs/linux-full-with-spyder.yml environment. The Mac environments come with Spyder by default. To open Spyder use:

conda activate osl
spyder

Test the installation#

The following should not raise any errors:

conda activate osl
python
>> import osl
>> import osl_dynamics

Get the latest source code (optional)#

If you want the very latest code you can clone the GitHub repo. This is only neccessary if you want recent changes to the package that haven’t been released yet.

First install OSL/osl-dynamics using the instructions above. Then clone the repo and install locally from source:

conda activate osl

git clone https://github.com/OHBA-analysis/osl.git
cd osl
pip install -e .
cd ..

git clone https://github.com/OHBA-analysis/osl-dynamics.git
cd osl-dynamics
pip install -e .

After you install from source, you can run the code with local changes. You can update the source code using:

git pull

within the osl or osl-dynamics directory.

Getting help#

If you run into problems while installing OSL, please open an issue on the GitHub repository.