More overall Documentation tweaking, and updating README to 19.2 (ace…

…s#312)

* Morr overall Documentation tweaking, and updating README to 19.2

* fix some links and reorder two lines

* will the links work now?

* typo in dicom archive link

* Suggestions of edits for loris mri docs (#2)

* Some typo fixes and harmonization

* e.g. in italic throughout documentation

* i.e. in italic throughout documentation

* Loris written as LORIS

* reread up till section 3

* reread up till section 4

* Finished reading the docs

* link to docs instead of wiki and a minor detail

* Christine feedback

* one missed comment

* Mo feedback incorporated

* formatting and a typo

* formatting again

* more feedback from MUhammad from a slack chat session

* cecile feedback

* more fixes by cecile

* a few more changes to reflect recent releases

* added arrow on DICOM Archive failure to user story diagram

* modified the documentation for the localizer section

* mouna's feedback

README.md

@@ -1,7 +1,7 @@
-This Readme covers release 19.0 of the LORIS Imaging Insertion Pipeline for Ubuntu or CentOS systems
+This Readme covers release 19.2 of the LORIS Imaging Insertion Pipeline for Ubuntu or CentOS systems
 
-This repo accompanies the [LORIS neuroimaging data platform main repo](https://github.com/aces/Loris/releases)</b>, release 19.0.*.<br>
-For documentation and detailed setup information, please see the [LORIS wiki](https://github.com/aces/Loris/wiki/Imaging-Database)</b>.
+This repo accompanies the [LORIS neuroimaging data platform main repo](https://github.com/aces/Loris/releases)</b>, release 19.2.*.<br>
+For documentation and detailed setup information, please see the [LORIS-MRI documentation](docs/) for your installed version</b>.
 
 This repo can be installed on the same VM as the main LORIS codebase, or on a different machine such as a designated fileserver where large imaging filesets are to be stored. 
 
@@ -66,10 +66,6 @@ Download the pre-compiled package for your operating system.  Install required d
   Note: The installer will allow Apache to write to the /data/ directories by adding user lorisadmin to the Apache linux group.  To ensure this change takes effect, log out and log back into your terminal session before running the imaging pipeline.
 The installer will also set Apache group ownership of certain /data/ subdirectories.
 
-  After having run the install script, it is possible to verify that certain
-    fields were correctly populated by `imaging_install.sh` (see
-    [section 2.4](02-Install.md#2.4-post-installation-checks)).
-
 #### 4. Configure paths and environment
 
    Ensure that /home/lorisadmin/.bashrc includes the statement:
@@ -78,8 +74,12 @@ The installer will also set Apache group ownership of certain /data/ subdirector
 
    Then source the .bashrc file.   
 
-<br>
-Installation complete.
+**INSTALLATION COMPLETE!**
+
+Please refer to the [Install](docs/02-Install.md) section in the 
+[LORIS-MRI documentation](docs/) for your installed version for:
+- customizations and protocol configurations ([Section 2.2](docs/02-Install.md#configuration)).
+- verifying that certain fields were correctly populated by `imaging_install.sh`
+([Section 2.3](docs/02-Install.md#post-installation-checks)).
 
-For customizations and protocol configurations, see LORIS Imaging Setup Guide : https://github.com/aces/Loris/wiki/Imaging-Database 
 

docs/01-Introduction.md

@@ -1,51 +1,63 @@
 # 1.0 - Introduction
 
 ### 1.1 What is LORIS-MRI? 
-LORIS-MRI is the backbone of the imaging component that makes up LORIS.
- It is maintained in a separate repository so that it can be installed
- on the file server and separated from the web server.
+
+LORIS-MRI comprises the core libraries for loading and inserting imaging 
+data in LORIS. 
+It is maintained in a separate repository so that it can be installed 
+on the file server and separated from the web server.
 These documents assume you have some knowledge regarding LORIS and
-a functioning installation. For information regarding LORIS itself,
-please consult the [LORIS wiki][1].
-
-LORIS-MRI is a set of libraries responsible for the insertion,
-organization, and archival of uploaded imaging datasets.
- It expects an uploaded, compressed file containing
-a [DICOM][2] study composed of several DICOM files. These DICOM files
- will be archived on the server and converted to [MINC][3] and (optionally)
+a functioning installation of the core LORIS codebase. For information 
+regarding LORIS itself, please consult the [LORIS wiki][1].
+
+LORIS-MRI is a set of libraries, scripts, and settings responsible for the 
+insertion, organization, and archiving of uploaded imaging datasets. 
+It expects an uploaded, compressed file containing 
+a [DICOM][2] scan session composed of many DICOM files. These DICOM files 
+will be archived on the server and converted to [MINC][3] and (optionally)
 [NIfTI][4] files. Knowledge of these file formats can be helpful, but are not 
 necessary for using or installing LORIS-MRI.
 
 LORIS-MRI allows you to easily organize and archive your imaging datasets
-and links them with
- corresponding behavioral data in LORIS. Scans can be viewed and quality
- controlled through the user's web browser, facilitating collaboration
- between radiologists, clinicians and researchers.
+and links them with corresponding behavioral data in LORIS. Scans can be viewed 
+and quality controlled in the LORIS front end via web browser, facilitating 
+collaboration between radiologists, clinicians and researchers.
+
+### 1.2 How does LORIS-MRI work? 
+
+![user_story](images/user_story.png)
 
-### 1.2 How does LORIS-MRI work?  ![user_story](images/user_story.png)
 LORIS-MRI allows multiple ways to upload scans, but typically, users
-upload a compressed (.tgz, .tar.gz, or .zip) DICOM folder to Imaging
-Uploader.  LORIS requires that the uploaded file name follow the naming
-convention PSCID_CANDID_VISIT-LABEL. 
+upload a compressed (.tgz, .tar.gz, or .zip) DICOM folder via the Imaging
+Uploader module that should be composed of **only** DICOM files. LORIS requires 
+that the uploaded file name follow the naming convention 
+`PSCID_CANDID_VISIT-LABEL`. 
 In addition, all DICOM datasets uploaded via the Imaging Uploader or 
 transferred on the LORIS-MRI server must be free of any identifying 
-information (e.g. patient name). A tool can be provided to the sites to 
-facilitate deidentification. Please contact the LORIS team for details.
+information (*e.g.* patient name). A tool can be provided to the sites to 
+facilitate de-identification. Please contact the LORIS team for details.
 
 The LORIS-MRI pipeline starts once the scans are uploaded to the server.
 The pipeline can start automatically if the autolaunch configuration is
-set, otherwise manual intervention is required by a developer with backend 
-access to the server. More details about these options and the scripts
-needed to run the pipeline can be found [here](05-PipelineLaunchOptions.md). 
+set, otherwise a back-end administrator can manually run the pipeline. 
+These options and scripts are detailed in the 
+[Pipeline Triggering Options documentation](05-PipelineLaunchOptions.md). 
 
-Insertion progress can be tracked by the user through the Log Viewer in 
-Imaging Uploader, where descriptive messages can be consulted.
+Insertion progress can be tracked by the user through the Log Viewer in the
+Imaging Uploader module, where descriptive messages can be consulted.
 The output of the main key steps in the insertion progress can also be consulted 
-through the LORIS DICOM archive module for successfully archived DICOM datasets, 
-Imaging Browser for MINC-generated files that pass the study-defined MRI protocol, 
-and 3D or 4D navigation of these MINC files in BrainBrowser. More details on the
-capabilities of BrainBrowser can be found [here.][5]
+through:
+ - the LORIS DICOM Archive module for successfully archived DICOM datasets`*` 
+ - the Imaging Browser module for MINC files (generated from DICOM) that pass the 
+study-defined MRI protocol`*`
+ - BrainBrowser using 3D or 4D navigation of these MINC files. More details on 
+BrainBrowser's capabilities can be found [here.][5]
 
+`*` Please note that all acquisitions are included in the DICOM archival
+step. However, specific acquisitions (such as `localizers` or `scouts`) can be
+excluded from the steps of the pipeline that start at, and follow the DICOM to
+MINC conversion by specifying them in the `excluded_series_description`
+field of the Config module (under the Imaging Pipeline section).
 
 [1]: https://github.com/aces/Loris/wiki 
 [2]: http://dicomiseasy.blogspot.ca/2011/10/introduction-to-dicom-chapter-1.html