<commit_before>.. include:: links.rst

------------
Installation
------------

There are two ways to use *fMRIPrep*:

* within a `Manually Prepared Environment (Python 3.5+)`_; or
* using container technologies (RECOMMENDED), such as :ref:`run_docker`
  or :ref:`run_singularity`.

Once you are ready to run *fMRIPrep* via either of the options above,
see :ref:`usage` for details.


Container technologies: Docker and Singularity
==============================================
Container technologies are operating-system-level virtualization methods to run Linux systems
using the host's Linux kernel.
This is a lightweight approach to virtualization, as compares to virtual machines.


.. _installation_docker:

Docker (recommended for PC/laptop and commercial Cloud)
-------------------------------------------------------
Probably, the most popular framework to execute containers is Docker.
If you are to run *fMRIPrep* on your PC/laptop, this is the RECOMMENDED way of execution.
Please make sure you follow the `Docker installation`_ instructions.
You can check your `Docker Engine`_ installation running their ``hello-world`` image: ::

    $ docker run --rm hello-world

If you have a functional installation, then you should obtain the following output. ::
    
    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     1. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     1. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     1. The Docker daemon streamed that output to the Docker client, which sent it<commit_msg>enh: make more clear how containers modify the command-line<commit_after>.. include:: links.rst

------------
Installation
------------

There are two ways to get *fMRIPrep* installed:

* within a `Manually Prepared Environment (Python 3.5+)`_, also known as
  *bare-metal installation*; or
* using container technologies (RECOMMENDED), such as :ref:`run_docker`
  or :ref:`run_singularity`.

Once you have your *bare-metal* environment set-up (first option above),
the next step is executing the ``fmriprep`` command-line.
The ``fmriprep`` command-line options are documented in the :ref:`usage`
section.
The ``fmriprep`` command-line adheres to the `BIDS-Apps recommendations
for the user interface <usage.html#execution-and-the-bids-format>`__.
Therefore, the command-line has the following structure:
::

  $ fmriprep <input_bids_path> <derivatives_path> <analysis_level> <named_options>

On the other hand, if you chose a container infrastructure, then
the command-line will be composed of a preamble to configure the
container execution followed by the ``fmriprep`` command-line options
as if you were running it on a *bare-metal* installation.
The command-line structure above is then modified as follows:
::

  $ <container_command_and_options> <container_image> \
       <input_bids_path> <derivatives_path> <analysis_level> <fmriprep_named_options>

Therefore, once specified the container options and the image to be run
the command line is the same as for the *bare-metal* installation but dropping
the ``fmriprep`` executable name.

Container technologies: Docker and Singularity
==============================================
Container technologies are operating-system-level virtualization methods to run Linux systems
using the host's Linux kernel.
This is a lightweight approach to virtualization, as compares to virtual machines.


.. _installation_docker:

Docker (recommended for PC/laptop and commercial Cloud)
-------------------------------------------------------
Probably, the most popular framework to execute containers is Docker.
If you are to run *fMRIPrep* on your PC/laptop, this is the RECOMMENDED way of execution.
Please make sure you follow the `Docker installation`_ instructions.
You can check your `Docker Engine`_ installation running their ``hello-world`` image: ::

    $ docker run --rm hello-world

If you have a functional installation, then you should obtain the following output. ::
    
    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     1. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     1. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     1. The Docker daemon streamed that output to the Docker client, which sent it
{'fraction_non_alphanumeric': 0.11131840796019901, 'fraction_numerical': 0.003316749585406302, 'mean_word_length': 3.702729044834308, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3670811', 'n_tokens_mistral': 1268, 'n_tokens_neox': 1176, 'n_words': 591}