Updating installation instructions/environments.

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/<os>.yml
+conda env create -f envs/linux-generic.yml
 conda activate osl
 pip install -e .
 ```
-where the environment file `<os>.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

doc/source/install.rst

@@ -1,28 +1,134 @@
 Installation
 ============
 
-We recommend installing OSL within a virtual environment. You can do this with `Anaconda <https://docs.anaconda.com/free/anaconda/install/index.html>`_ (or `miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_).
+A full installation of the OHBA Software Library (OSL) includes:
 
-Linux
------
+- `FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation>`_ (FMRIB Software Library) - only needed if you want to do source reconstruction.
+- `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_ (or `Anaconda <https://docs.anaconda.com/free/anaconda/install/index.html>`_).
+- `OSL <https://github.com/OHBA-analysis/osl>`_ (OHBA Software Library).
+- `osl-dynamics <https://github.com/OHBA-analysis/osl-dynamics>`_ (OSL Dynamics Toolbox) - only needed if you want to train models for dynamics.
+
+Linux Instructions
+------------------
 
 1. Install FSL using the instructions `here <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/Linux>`_.
 
-2. Install OSL either via pip using::
+2. Install `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_ 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 <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/MacOsX>`_.
+
+2. Install `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_ 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 <https://ubuntu.com/wsl>`_ using a Windows subsystem. 
+
+Instructions:
+
+1. Install FSL using the instructions `here <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/Windows>`_. Make sure you setup XLaunch for the visualisations.
+
+2. Install `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_ 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 <https://ubuntu.com/wsl>`_ (linux) subsystem following the instructions `here <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/Windows>`_.
+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 <https://github.com/OHBA-analysis/osl/issues>`_.

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.

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

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

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