diff --git a/README.md b/README.md index f786d7e0..3d8485b2 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,30 @@ -OHBA Software Library (OSL) -=========================== +# OHBA Software Library (OSL) Documentation: https://osl.readthedocs.io/en/latest/. -Install from Source Code ------------------------- -The recommended installation depends on your operating system. OSL can be installed from source using: +## Installation + +See the [official documentation](https://osl.readthedocs.io/en/latest/install.html) for comprehensive installation instructions. + +OSL can be installed from source code within a [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html) (or [Anaconda](https://docs.anaconda.com/free/anaconda/install/index.html)) environment using: ``` git clone https://github.com/OHBA-analysis/osl.git cd osl -conda env create -f envs/.yml +conda env create -f envs/linux-generic.yml conda activate osl pip install -e . ``` -where the environment file `.yml` can be: -- `linux.yml` for a generic linux machine. -- `hbaws.yml` if you are using an OHBA workstation at Oxford. -- `bmrc.yml` if you are using the BMRC at Oxford. +## Deleting osl -Note, all of the above environments come with Jupyter Notebook installed. The `hbaws.yml` environment also comes with Spyder installed. - -Deleting osl ------------- If you installed osl using the instructions above then to completely remove it simply delete the conda environment and delete the repo on your local machine: ``` conda env remove -n osl rm -rf osl ``` -For Developers --------------- +## For Developers + Run tests: ``` cd osl diff --git a/doc/source/install.rst b/doc/source/install.rst index 8e937f32..b7637249 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,28 +1,134 @@ Installation ============ -We recommend installing OSL within a virtual environment. You can do this with `Anaconda `_ (or `miniconda `_). +A full installation of the OHBA Software Library (OSL) includes: -Linux ------ +- `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 OSL either via pip using:: +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 :code:`conda` installed as a software module and might be able to load Anaconda with:: + + module load Anaconda + +and skip step 2. + +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 :code:`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 :code:`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 - pip install osl +This will create a conda environment called :code:`osl` which contains both OSL and osl-dynamics. -or from source (in editable mode) using:: +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 :code:`osl` environment is activated if it says :code:`(osl)[...]` at the start of your terminal command line. + +Note, if you get a :code:`conda init` error when activating the :code:`osl` environment during a job on an HPC cluster, you can resolve this by replacing:: + + conda activate osl + +with:: + + source activate osl + +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 - conda env create -f envs/linux.yml - conda activate 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 -Windows -------- +within the :code:`osl` or :code:`osl-dynamics` directory. -If you're using a Windows machine, we recommend you install FSL within a `Ubuntu `_ (linux) subsystem following the instructions `here `_. +Getting help +------------ -Then install OSL using the instructions above. +If you run into problems while installing OSL, please open an issue on the `GitHub repository `_. diff --git a/envs/README.md b/envs/README.md new file mode 100644 index 00000000..b39d886b --- /dev/null +++ b/envs/README.md @@ -0,0 +1,19 @@ +# Conda Environments + +See the official documentation for the [installation instructions](https://osl.readthedocs.io/en/latest/install.html). + +OSL only environments: + +- `linux-generic.yml`: most generic environment for linux computers. +- `bmrc.yml`: for the Oxford BMRC cluster. +- `hbaws.yml`: for the OHBA workstation. Comes with Spyder. +- `m1-mac.yml`: for M1 Macs. Comes with Spyder. +- `m2-mac.yml`: for M2 Macs. Comes with Spyder. + +OSL + osl-dynamics environments: + +- **`linux-full.yml`: recommended environment for linux computers.** +- **`mac-full.yml`: recommended environment for Mac computers.** +- `osl-workshop-23.yml`: used in the [2023 OSL Workshop](https://osf.io/zxb6c/). + +All environments come with Jupyter Notebook. diff --git a/envs/windows.yml b/envs/linux-full.yml similarity index 100% rename from envs/windows.yml rename to envs/linux-full.yml diff --git a/envs/m1-mac.yml b/envs/m1-mac.yml index 8c54a66d..eeab01bd 100644 --- a/envs/m1-mac.yml +++ b/envs/m1-mac.yml @@ -277,7 +277,7 @@ dependencies: - rfc3986-validator==0.1.1 - rope==1.7.0 - rtree==1.0.1 - - sails==1.4.0 + - sails==1.6.0 - scikit-learn==1.2.2 - scipy==1.10.1 - send2trash==1.8.0 diff --git a/envs/m2-mac.yml b/envs/m2-mac.yml index 1335de17..58afdde8 100644 --- a/envs/m2-mac.yml +++ b/envs/m2-mac.yml @@ -337,7 +337,7 @@ dependencies: - pyviz-comms==2.2.1 - rfc3339-validator==0.1.4 - rfc3986-validator==0.1.1 - - sails==1.4.0 + - sails==1.6.0 - scikit-learn==1.2.2 - scipy==1.10.1 - send2trash==1.8.0 diff --git a/envs/mac-full.yml b/envs/mac-full.yml new file mode 100644 index 00000000..ad86f395 --- /dev/null +++ b/envs/mac-full.yml @@ -0,0 +1,46 @@ +name: osl +channels: +- conda-forge +dependencies: +- python=3.8.16 +- pip=23.0.1 +- vtk=9.1.0=*osmesa* +- pyvista=0.38.5 +- pip: + - jupyter==1.0.0 + - ipympl==0.9.3 + - ipywidgets==8.0.5 + - ipyevents==2.0.1 + - ipyvtklink==0.2.2 + - jupyter-client==8.1.0 + - numpy==1.23.5 + - scipy==1.10.1 + - matplotlib==3.7.1 + - mne==1.3.1 + - scikit-learn==1.2.2 + - fslpy==3.11.3 + - sails==1.4.0 + - tabulate==0.9.0 + - pyyaml==6.0 + - neurokit2==0.2.3 + - jinja2==3.1.2 + - glmtools==0.2.1 + - numba==0.56.4 + - nilearn==0.10.2 + - dask==2023.3.2 + - distributed==2023.3.2 + - parse==1.19.0 + - opencv-python==4.7.0.72 + - h5io==0.1.7 + - mat73==0.60 + - nibabel==5.0.1 + - pandas==1.5.3 + - panel==1.2.3 + - pqdm==0.2.0 + - seaborn==0.12.2 + - tensorflow-macos==2.9.1 + - tensorflow_probability==0.17.0 + - tqdm==4.65.0 + - osfclient==0.0.5 + - osl + - osl-dynamics