Handle sform errors in sMRI files + PSD plot fix + installation instr…

…uctions (#267)

README.md

@@ -1,6 +1,8 @@
 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:
@@ -14,11 +16,10 @@ pip install -e .
 where the environment file `<os>.yml` can be:
 
 - `linux.yml` for a generic linux machine.
-- `m1_mac.yml` if you are using a modern Mac computer.
 - `hbaws.yml` if you are using an OHBA workstation at Oxford.
 - `bmrc.yml` if you are using the BMRC at Oxford.
 
-Note, all of the above environments come with Jupyter Notebook installed. The `hbaws.yml` and `m1_mac.yml` environments also comes with Spyder installed.
+Note, all of the above environments come with Jupyter Notebook installed. The `hbaws.yml` environment also comes with Spyder installed.
 
 Deleting osl
 ------------

doc/source/conf.py

@@ -21,12 +21,12 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'osl'
-copyright = '2023, OMG'
-author = 'OMG'
+project = 'OSL'
+copyright = '2023, OHBA Analysis Group'
+author = 'OHBA Analysis Group'
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1dev'
+release = '0.5.1'
 
 
 # -- General configuration ---------------------------------------------------

doc/source/install.rst

@@ -1,12 +1,28 @@
 Installation
 ============
 
-First, make sure you have conda (or miniconda) installed: https://docs.conda.io/en/latest. Then oslpy can be installed from source using the following:
+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>`_).
 
-::
-    
-    git clone https://github.com/OHBA-analysis/oslpy.git
-    cd oslpy
+Linux
+-----
+
+1. Install FSL using the instructions `here <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/Linux>`_.
+
+2. Install OSL either via pip using::
+
+    pip install osl
+
+or from source (in editable mode) using::
+
+    git clone https://github.com/OHBA-analysis/osl.git
+    cd osl
     conda env create -f envs/linux.yml
     conda activate osl
     pip install -e .
+
+Windows
+-------
+
+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>`_.
+
+Then install OSL using the instructions above.

examples/fix_smri_files.py

@@ -0,0 +1,29 @@
+"""Fix sform code of structurals.
+
+This script uses FSL to set the sform code of any structural
+whose sform code is not 1 or 4 to make sure it is compatible
+with OSL.
+
+Warning: this script will permanently change the SMRI file.
+"""
+
+import nibabel as nib
+
+from osl import source_recon
+
+source_recon.setup_fsl("/path/to/fsl")
+
+# Paths to files to fix
+files = [
+    "smri/sub-001.nii.gz",
+    "smri/sub-002.nii.gz",
+]
+
+for file in files:
+    smri = nib.load(file)
+    sformcode = smri.header.get_sform(coded=True)[-1]
+    if sformcode not in [1, 4]:
+        cmd = f"fslorient -setsformcode 1 {file}"
+        source_recon.rhino.utils.system_call(cmd)
+
+print("Done”)

osl/source_recon/parcellation/parcellation.py

@@ -476,12 +476,16 @@ def plot_psd(parc_ts, fs, freq_range, parcellation_file, filename):
         Output filename.
     """
     if parc_ts.ndim == 3:
-        # (parcels, time, epochs) -> (parcels, time)
-        shape = parc_ts.shape
-        parc_ts = parc_ts.reshape(shape[0], shape[1] * shape[2])
+        # Calculate PSD for each epoch individually and average
+        psd = []
+        for i in range(parc_ts.shape[-1]):
+            f, p = welch(parc_ts[..., i], fs=fs)
+            psd.append(p)
+        psd = np.mean(psd, axis=0)
+    else:
+        # Calcualte PSD of continuous data
+        f, psd = welch(parc_ts, fs=fs)
 
-    # Calculate PSD
-    f, psd = welch(parc_ts, fs=fs)
     n_parcels = psd.shape[0]
 
     # Re-order to use colour to indicate anterior->posterior location

osl/source_recon/rhino/utils.py

@@ -281,7 +281,10 @@ def _get_sform(nii_file):
     if sformcode == 1 or sformcode == 4:
         sform = nib.load(nii_file).header.get_sform()
     else:
-        raise ValueError("sform code for {} is {}, and needs to be 4 or 1".format(nii_file, sformcode))
+        raise ValueError(
+            f"sform code for {nii_file} is {sformcode}, and needs to be 4 or 1.\n"
+            "To fix see: https://github.com/OHBA-analysis/osl/blob/main/examples/fix_smri_files.py"
+        )
 
     sform = Transform("mri_voxel", "mri", sform)
     return sform
@@ -299,7 +302,10 @@ def _get_mni_sform(nii_file):
     if sformcode == 1 or sformcode == 4:
         sform = nib.load(nii_file).header.get_sform()
     else:
-        raise ValueError("sform code for {} is {}, and needs to be 4 or 1".format(nii_file, sformcode))
+        raise ValueError(
+            f"sform code for {nii_file} is {sformcode}, and needs to be 4 or 1.\n"
+            "To fix see: https://github.com/OHBA-analysis/osl/blob/main/examples/fix_smri_files.py"
+        )
 
     sform = Transform("unknown", "mni_tal", sform)
     return sform