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

Latest tag #260

Merged
merged 3 commits into from
Sep 16, 2023
Merged

Latest tag #260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f5eaea7
change to latest tag
akhanf Sep 16, 2023
de6434e
use latest tag, remove zenodo link
akhanf Sep 16, 2023
903e252
use latest tag, remove zenodo container
akhanf Sep 16, 2023
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
16 changes: 8 additions & 8 deletions docs/getting_started/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,20 @@ Open your Windows Command Prompt by clicking the bottom left `Windows` button an

Pull the container (this will take some time and storage space, but like an installation it only needs to be done once and can then be run on many datasets):

docker pull khanlab/hippunfold:v1.3.3
docker pull khanlab/hippunfold:latest

Run HippUnfold without any arguments to print the short help:

docker run -it --rm khanlab/hippunfold:v1.3.3
docker run -it --rm khanlab/hippunfold:latest

Use the `-h` option to get a detailed help listing:

docker run -it --rm khanlab/hippunfold:v1.3.3 -h
docker run -it --rm khanlab/hippunfold:latest -h

Note that all the Snakemake command-line options are also available in
HippUnfold, and can be listed with `--help-snakemake`:

docker run -it --rm khanlab/hippunfold:v1.3.3 --help-snakemake
docker run -it --rm khanlab/hippunfold:latest --help-snakemake

## Running an example

Expand All @@ -47,13 +47,13 @@ ds002168/

Now let's run HippUnfold on the test dataset. Docker will need read/write access to the input and output directories, respectively. This is achieved with the `-v` flag. This 'binds' or 'mounts' a directory to a new directory inside the container.

docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold:/output khanlab/hippunfold:v1.3.3 /bids /output participant --modality T1w -n
docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold:/output khanlab/hippunfold:latest /bids /output participant --modality T1w -n

Explanation:

`-v c:\Users\jordan\Downloads\ds002168:/bids` tells Docker to mount the directory `c:\Users\jordan\Downloads\ds002168` into a new directory inside the container named `/bids`. We then do the same things for our output directory named `ds002168_hippunfold`, which we mount to `/output` inside the container. These arguments are not specific to HippUnfold but rather are general ways to use Docker. You may want to familiarize yourself with [Docker options](https://docs.docker.com/engine/reference/run/).

Everything after we specified the container (`khanlab/hippunfold:v1.3.3`) are arguments to HippUnfold itself. The first of these arguments (as with any BIDS App) are the input directory (`/bids`), the output directory (`/output`), and then the analysis level (`participant`). The `participant` analysis
Everything after we specified the container (`khanlab/hippunfold:latest`) are arguments to HippUnfold itself. The first of these arguments (as with any BIDS App) are the input directory (`/bids`), the output directory (`/output`), and then the analysis level (`participant`). The `participant` analysis
level is used in HippUnfold for performing the segmentation, unfolding, and any
participant-level processing. The `group` analysis is used to combine subfield volumes
across subjects into a single tsv file. The `--modality` flag is also required, and describes which image we use for segmentation. Here we used the T1w image. We also used the `--dry-run/-n` option to just print out what would run, without actually running anything.
Expand All @@ -68,7 +68,7 @@ useful if you are running multiple subjects.
Running the following command (hippunfold on a single subject) may take ~30 minutes if you have 8 cores, shorter if you have more
cores, but could be much longer (several hours) if you only have a single core.

docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold:/output khanlab/hippunfold:v1.3.3 /bids /output participant --modality T1w -p --cores all
docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold:/output khanlab/hippunfold:latest /bids /output participant --modality T1w -p --cores all

After this completes, you should have a `ds002168_hippunfold` directory with outputs for the one subject.

Expand All @@ -79,7 +79,7 @@ in the BIDS test dataset, you can use the `--modality T2w` option. In this case,
test dataset has a limited FOV, we should also make use of the `--t1-reg-template` command-line option,
which will make use of the T1w image for template registration, since a limited FOV T2w template does not exist.

docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold_t2w:/output khanlab/hippunfold:v1.3.3 /bids /output participant --modality T2w --t1-reg-template -p --cores all
docker run -it --rm -v c:\Users\jordan\Downloads\ds002168:/bids -v c:\Users\jordan\Downloads\ds002168_hippunfold_t2w:/output khanlab/hippunfold:latest /bids /output participant --modality T2w --t1-reg-template -p --cores all

Note that if you run with a different modality, you should use a separate output directory, since some of the files
would be overwritten if not.
Expand Down
25 changes: 10 additions & 15 deletions docs/getting_started/singularity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,28 +14,23 @@

## First time setup

Pull the container. This can be done from dockerhub, but this requires a large amount of disk space in your /tmp folder, since it has to convert from a docker container to a singularity container. To avoid this, we provide a Dropbox link to the singularity container itself:
Pull the container:

wget https://zenodo.org/record/8338481/files/hippunfold_v1.3.1.sif
singularity pull khanlab_hippunfold_latest.sif docker://khanlab/hippunfold:latest


Run HippUnfold without any arguments to print the short help:

singularity run -e khanlab_hippunfold_v1.3.1.sif
singularity run -e khanlab_hippunfold_latest.sif

Use the `-h` option to get a detailed help listing:

singularity run -e khanlab_hippunfold_v1.3.1.sif -h
singularity run -e khanlab_hippunfold_latest.sif -h

Note that all the Snakemake command-line options are also available in
HippUnfold, and can be listed with `--help-snakemake`:

singularity run -e khanlab_hippunfold_v1.3.1.sif --help-snakemake

If you really need to pull the container from docker hub, you can use the following command, but beware, it is more prone to errors and will take up lots of system resources (e.g. ~70GB of free disk space):

singularity pull khanlab_hippunfold_v1.3.1.sif docker://khanlab/hippunfold:v1.3.1

singularity run -e khanlab_hippunfold_latest.sif --help-snakemake

Note: If you encounter any errors pulling the container from dockerhub, it may be because you are running
out of disk space in your cache folders. Note, you can change these locations
Expand Down Expand Up @@ -70,11 +65,11 @@ ds002168/

Now let's run HippUnfold.

singularity run -e khanlab_hippunfold_v1.3.1.sif ds002168 ds002168_hippunfold participant -n --modality T1w
singularity run -e khanlab_hippunfold_latest.sif ds002168 ds002168_hippunfold participant -n --modality T1w

Explanation:

Everything prior to the container (`khanlab_hippunfold_v1.3.1.sif`) are arguments to singularity, and after are to HippUnfold itself. The first three arguments to HippUnfold (as with any BIDS App) are the input
Everything prior to the container (`khanlab_hippunfold_latest.sif`) are arguments to singularity, and after are to HippUnfold itself. The first three arguments to HippUnfold (as with any BIDS App) are the input
folder (`ds002168`), the output folder (`ds002168_hippunfold`), and then the analysis level (`participant`). The `participant` analysis
level is used in HippUnfold for performing the segmentation, unfolding, and any
participant-level processing. The `group` analysis is used to combine subfield volumes
Expand All @@ -88,7 +83,7 @@ When you run the above command, a long listing will print out, describing all th
will be run. This is a long listing, and you can better appreciate it with the `less` tool. We can
also have the shell command used for each rule printed to screen using the `-p` Snakemake option:

singularity run -e khanlab_hippunfold_v1.3.1.sif ds002168 ds002168_hippunfold participant -np --modality T1w | less
singularity run -e khanlab_hippunfold_latest.sif ds002168 ds002168_hippunfold participant -np --modality T1w | less


Now, to actually run the workflow, we need to specify how many cores to use and leave out
Expand All @@ -101,7 +96,7 @@ Running the following command (hippunfold on a single subject) may take ~30 minu
cores, but could be much longer (several hours) if you only have a single core.


singularity run -e khanlab_hippunfold_v1.3.1.sif ds002168 ds002168_hippunfold participant -p --cores all --modality T1w
singularity run -e khanlab_hippunfold_latest.sif ds002168 ds002168_hippunfold participant -p --cores all --modality T1w


Note that you may need to adjust your [Singularity options](https://sylabs.io/guides/3.1/user-guide/cli/singularity_run.html) to ensure the container can read and write to yout input and output directories, respectively. You can bind paths easily by setting an
Expand All @@ -120,7 +115,7 @@ in the BIDS test dataset, you can use the `--modality T2w` option. In this case,
test dataset has a limited FOV, we should also make use of the `--t1-reg-template` command-line option,
which will make use of the T1w image for template registration, since a limited FOV T2w template does not exist.

singularity run -e khanlab_hippunfold_v1.3.1.sif ds002168 ds002168_hippunfold_t2w participant --modality T2w --t1-reg-template -p --cores all
singularity run -e khanlab_hippunfold_latest.sif ds002168 ds002168_hippunfold_t2w participant --modality T2w --t1-reg-template -p --cores all

Note that if you run with a different modality, you should use a separate output folder, since some of the files
would be overwritten if not.
Expand Down
17 changes: 2 additions & 15 deletions docs/getting_started/vagrant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,22 +67,9 @@ speed: 2

## Download the HippUnfold container

We download the Singularity container for HippUnfold using
Dropbox in this example:
We pull/build the container from DockerHub:
```
wget https://www.dropbox.com/s/jtf6zyy0u8sc2k6/khanlab_hippunfold_v1.2.0.sif
```

Note, you can also pull/build the container from DockerHub:
```
singularity pull docker://khanlab/hippunfold:v1.2.0
```

```{asciinema} ../casts/vagrant_hippunfold_get_app_dropbox.cast
---
preload: 1
speed: 2
---
singularity pull docker://khanlab/hippunfold:latest
```

## Run HippUnfold
Expand Down