Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New SPM release #7

Merged
merged 5 commits into from
Jan 22, 2025
Merged

New SPM release #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b91fdcd
update the installation instructions for the new release
Jan 3, 2025
76079e7
Update the standalone installation instructions
Jan 3, 2025
bc007a9
update container instructions
Jan 3, 2025
5da12a7
fix typos
Jan 3, 2025
3b794da
don't specify python version for spell checking
Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions .github/workflows/spelling.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,9 @@ jobs:
spell:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v1
with:
python-version: '3.7'
architecture: 'x64'
uses: actions/setup-python@v5
- name: Install dependencies
run: |
python3 -m pip install --upgrade pip setuptools
Expand Down
5 changes: 2 additions & 3 deletions docs/development/git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ We use the [Git](https://git-scm.com/) version control system for the developmen

We provide here instructions to interact with the SPM repository using the [GitHub Desktop](https://desktop.github.com/). This mainly concerns Windows developers -- we also mention the command line equivalents when relevant. For Linux users, [additional steps](https://www.fil.ion.ucl.ac.uk/spm/docs/development/ssh_authentication/) are required to enable SSH authentication.

## Git Installation
## Git Installation

First, please install the GitHub Desktop:

Expand All @@ -27,7 +27,6 @@ During installation, you can accept most defaults. There are three options to be
![line ending conversions](../assets/figures/git_windows_eol.png){ width="45%" }
![default behavior of `git pull`](../assets/figures/git_windows_rebase.png){ width="45%" }


## Git Configuration

### Username and commit email address
Expand Down Expand Up @@ -81,7 +80,7 @@ To apply this setting from GitHub Desktop, you need to open the command prompt b

### Git autostash

Pull with rebase will fail if you have unstaged changes. One way around this if you're not ready to commit your changes is to stash the changed before doing a pull (`git stash`) and then restore then (`git stash pop`) afterwards. This can be automated by using the `autostash` option of `git rebase`.
Pull with rebase will fail if you have unstaged changes. One way around this if you're not ready to commit your changes is to stash the changes before doing a pull (`git stash`) and then restore them (`git stash pop`) afterwards. This can be automated by using the `autostash` option of `git rebase`.

```
git config --global rebase.autoStash true
Expand Down
53 changes: 18 additions & 35 deletions docs/installation/containers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,28 @@
# SPM and Containers

## Docker
??? info "What is Docker?"
[Docker](https://www.docker.com/) is a container technology, performing operating-system-level virtualisation.

Docker is a container technology, performing operating-system-level
virtualisation.

[`https://www.docker.com/`](https://www.docker.com/)

## Singularity

Singularity is another container technology that performs
operating-system-level virtualization. One of the main uses of
Singularity is to bring containers and reproducibility to scientific
computing and HPC.

<!-- markdown-link-check-disable-next-line -->
[`https://sylabs.io/singularity/`](https://sylabs.io/singularity/)
[`https://apptainer.org/`](https://apptainer.org/)
??? info "What is Singularity?"
Singularity is another container technology that performs operating-system-level virtualization. One of the main uses of Singularity is to bring containers and reproducibility to scientific computing and HPC.
<!-- markdown-link-check-disable-next-line -->
[`https://sylabs.io/singularity/`](https://sylabs.io/singularity/)
[`https://apptainer.org/`](https://apptainer.org/)

## SPM Containers

Official SPM12 `Dockerfile` and `singularity.def` (using the [Standalone
SPM](standalone.md)):

[`https://github.com/spm/spm-docker`](https://github.com/spm/spm-docker)

[`https://github.com/spm/spm-docker/pkgs/container/spm-docker`](https://github.com/spm/spm-docker/pkgs/container/spm-docker)

[`https://hub.docker.com/r/spmcentral/spm/`](https://hub.docker.com/r/spmcentral/spm/)
Official SPM [`Dockerfile`](https://github.com/spm/spm-docker) (using the [Standalone SPM](standalone.md)) with the docker images hosted on the [GitHub container registry](https://github.com/spm/spm-docker/pkgs/container/spm-docker)

For example, to start SPM with its graphical user interface:
```

```bash
xhost +local:docker
docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp:/tmp -v /tmp/.X11-unix:/tmp/.X11-unix spmcentral/spm fmri
docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp:/tmp -v /tmp/.X11-unix:/tmp/.X11-unix ghcr.io/spm/spm-docker:docker-matlab-latest fmri
```

If the container\'s root filesystem is mounted as read only
(*\--read-only* flag), you need to bind mount an extra volume:
```
If the container\'s root filesystem is mounted as read only (*\--read-only* flag), you need to bind mount an extra volume:

```bash
-v /tmp/.matlab:/root/.matlab
```

Expand All @@ -46,14 +31,12 @@ If the container\'s root filesystem is mounted as read only
<!-- markdown-link-check-disable-next-line -->
[SingularityCE User Guide](https://docs.sylabs.io/guides/latest/user-guide/)

```
sudo singularity build spm12.sif spm12-octave.def
singularity exec spm12.sif
./spm12.sif --help
```bash
singularity pull oras://ghcr.io/spm/spm-docker:singularity-matlab-latest
singularity run spm-docker_singularity-matlab-latest.sif --version
```

([how to install singularity on
Ubuntu](https://github.com/hpcng/singularity/issues/5390#issuecomment-899111181))
([how to install singularity on Ubuntu](https://github.com/hpcng/singularity/issues/5390#issuecomment-899111181))

## See also

Expand Down
95 changes: 23 additions & 72 deletions docs/installation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# SPM Installation with MATLAB

!!! info "Prerequisites"
The SPM software is a collection of [MATLAB](https://www.mathworks.com/products/matlab.html) functions and thus requires the MATLAB software to be installed on your computer in order to run. SPM requires only core MATLAB to run (no special toolboxes are required - unless stated otherwise).
The SPM software is a collection of [MATLAB](https://www.mathworks.com/products/matlab.html) functions and thus requires the MATLAB (or GNU Octave) software to be installed on your computer in order to run. SPM requires only core MATLAB to run (no special toolboxes are required - unless stated otherwise).

Each SPM version was written for a particular MATLAB version and will not work with earlier versions. MATLAB versions released after SPM can have some peculiarities but SPM developers try to provide compatibility fixes in the updates.

## Installation

=== "Windows"

1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/).
1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/).

2. Unzip `spm12.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm12`.
2. Unzip `spm_<version>.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm`.

3. Start MATLAB and add SPM to your path, either using:

Expand All @@ -20,73 +20,33 @@
or type the following at the MATLAB prompt:

```matlab
addpath('C:\Users\<login>\Documents\MATLAB\spm12')
addpath('C:\Users\<login>\Documents\MATLAB\spm')
savepath % if you want to save the current MATLAB path
```

If you are using MATLAB without its desktop, you can open the Set Path dialog box by typing `pathtool` at the MATLAB prompt.

=== "macOS"

1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.

If using Apple Silicon and Matlab 2023b or higher, download the [development version of SPM](https://github.com/spm/spm) or the [maintenance branch of SPM12](https://github.com/spm/spm12/tree/maint) from GitHub.
1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/) in your home directory.

2. Uncompress the archive by typing the following in a Terminal:
2. Uncompress the archive by typing the following in a terminal:

```bash
cd /Users/<login>
unzip spm12.zip
unzip spm_<version>.zip
```

3. Start MATLAB and add SPM to your path, either using:
`File` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...`

`Home` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...`: select the directory containing your SPM installation then click on `Save` and `Close`.

or typing the following at the MATLAB prompt:

```matlab
addpath /Users/<login>/spm12
addpath /Users/<login>/spm
savepath % if you want to save the current MATLAB path
```

??? info "Using Apple Silicon with Matlab 2023b (onwards)"

If, after installation, you get an error indicating that the MEX files for MACA64 are **missing**:
```
Error using spm_check_installation>check_basic
SPM uses a number of MEX files, which are compiled functions.
These need to be compiled for the various platforms on which SPM
is run. It seems that the compiled files for your computer platform
are missing or not compatible. See
https://en.wikibooks.org/wiki/SPM/Installation_on_64bit_Mac_OS_(Intel)
for information about how to compile MEX files for MACA64
in MATLAB 23.2.0.2365128 (R2023b).
```
This is because you are running [native Apple silicon MATLAB (R2023b onwards)](https://uk.mathworks.com/support/requirements/apple-silicon.html) and the MEX files are not available for that platform in SPM12. Instead download and install the [development version of SPM](https://github.com/spm/spm) or the [maintenance branch of SPM12](https://github.com/spm/spm12/tree/maint) where the `*.mexmaca64` MEX files have been compiled.

Then complete the steps detailed below if you receive a MEX file **validation error**, such as:

```
"*.mexmaca64" cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware
```
or:
```
Code signature not valid for use in process using Library Validation: library load disallowed by system policy
```
Open a Terminal, `cd` to the SPM directory and type:

```
find . -name "*.mexmaca64" -exec xattr -d com.apple.quarantine {} \;
```

If it doesn't work, please try this equivalent alternative, replacing `SPM_PATH` with the path of your SPM installation:

```
sudo xattr -r -d com.apple.quarantine SPM_PATH
sudo find SPM_PATH -name "*.mexmaca64" -exec spctl --add {} \;
```

??? info "Using any other Mac and Matlab version combination"
??? info "MEX file validation issues"
If you have **validation issues** with MEX files with one of these errors:

```
Expand All @@ -110,46 +70,36 @@
sudo find SPM_PATH -name "*.mexmaci64" -exec spctl --add {} \;
```



=== "Linux"

1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.
1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/) in your home directory.

2. Uncompress the archive by typing the following in a terminal:

```bash
cd /home/<login>
unzip spm12.zip
unzip spm_<version>.zip
```

3. Start MATLAB and add SPM into your path, either using:
3. Start MATLAB and add SPM to your path, either using:

`File` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...`
`Home` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...`: select the directory containing your SPM installation then click on `Save` and `Close`.

or typing the following at the MATLAB prompt:

```matlab
addpath /home/<login>/spm12
addpath /home/<login>/spm
savepath % if you want to save the current MATLAB path
```

!!! failure "`Crash at startup`"
??? failure "`Crash at startup`"

The following concerns a situation where MATLAB generates a segmentation fault when opening the SPM interface with errors like:
```
BadWindow (invalid Window parameter)
```
```
serial 20133 error_code 3 request_code 20 minor_code 0
```
```
Pango-CRITICAL **: pango_font_description_from_string: assertion 'str != NULL' failed
```
```
GLib-CRITICAL **: g_once_init_leave: assertion 'result != 0' failed
```
```
GLib-GObject-CRITICAL **: g_type_register_dynamic: assertion 'parent_type > 0' failed
```

Expand All @@ -160,20 +110,21 @@
setenv('SPM_HTML_BROWSER','0')
```

If you are using MATLAB without its desktop, you can open the Set Path dialog box by typing `pathtool` at the MATLAB prompt.

!!! danger
If using the graphical interface, make sure to use the `Add Folder...` button and not `Add with Subfolders...`. SPM will automatically add the appropriate subfolders to the MATLAB path at runtime.

![](../assets/figures/matlab_setpath.png)
![Matlab Setpath Window](../assets/figures/matlab_setpath.png)

You can then launch SPM by typing `spm` at the MATLAB prompt.

## Update

If you have just downloaded the `spm12.zip` archive, it already contains the latest set of updates. To update SPM when a new version is released:
If you have just downloaded the `spm_<version>.zip` archive, it already contains the latest set of updates. To update SPM when a new version is released:

1. [Download `spm12_updates_rxxxx.zip`](https://www.fil.ion.ucl.ac.uk/spm/download/spm12_updates/).
2. Uncompress `spm12_updates_rxxxx.zip` on top of the folder containing your SPM installation so that newer files overwrite existing files.
1. Download the latest [`spm_<version>.zip`](https://github.com/spm/spm/releases/latest/).
2. Replace your current SPM installation with the newer version so that newer files overwrite existing files.

Alternatively, you can use the `spm_update.m` function:

Expand Down
Loading
Loading