Update examples documentation (SyneRBI#1135)

updated examples/***/README.md etc

Co-authored-by: Kris Thielemans <k.thielemans@ucl.ac.uk>

CHANGES.md

@@ -1,12 +1,12 @@
 # ChangeLog
 ## v3.4.0
-* added support for spiral trajectories that are pre-computed by the user by exposing a setter.
+* MR:
+  - added support for spiral trajectories that are pre-computed by the user by exposing a setter.
+  - writing MR images and their attributes to `.dcm` and `.xml` files fixed.
+  - use C++ 17 if Gadgetron-support is enabled
 
-## v3.X
-
-* writing MR images and their attributes to `.dcm` and `.xml` files fixed.
-
-* Use C++ 17 if Gadgetron-support is enabled
+* documentation
+  - revision of READMEs for the examples
 
 ## v3.3.0
 

examples/Matlab/readme.txt → examples/Matlab/README.md

@@ -1,10 +1,15 @@
 This folder's subfolders contain Matlab demo scripts for PET and MR reconstruction.
 
-The folder YOUR_PATH/build/install/bin (see SIRF/INSTALL.txt) must be in Windows path,
+Unfortunately, we no longer support Matlab, so have not checked in a while if these
+demos work. Apologies.
+
+See [the main README section](../README.md#environment-variables) for information
+on environment variables.
+
+The folder YOUR_PATH/build/install/bin (see SIRF/INSTALL.txt) must be in the Windows path,
 and the folder YOUR_PATH/build/install/matlab in Matlab path.
 
 To use Matlab doc feature on demo scripts, you also need to add folders 
 YOUR_PATH/SIRF/examples/Matlab/MR and YOUR_PATH/SIRF/examples/Matlab/PET and their 
-sub-folders to Matlab path.
+sub-folders to the Matlab path.
 
-Please also see the Wiki page on Examples (MR).

examples/Python/MR/README.md

@@ -1,11 +1,34 @@
-This folder contains scripts intended to be run from the command line.
-For instance,
-```bash
-python acquisition_model.py 
-```
-The demos also have some options. Try
-```bash
-python acquisition_model.py --help
-```
-
-Check the `interactive` folder for demos that you run from an IDE.
+This folder contains scripts demonstrating the use of SIRF for MR reconstruction and related tasks.
+
+All scripts currently use Gadgetron as the reconstruction engine, however only the demos located in the subfolder named `Gadgetron` employ Gadgetron's gadget chains explicitly. Those outside of this subfolder allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `preprocess_acquisition_data` function etc.
+
+See the [Python/README](../README.md) for instructions.
+
+### Fully Sampled Data Reconstructions
+
+The script `fully_sampled_recon.py` shows the reconstruction of fully sampled data without the explicit use of Gadgetron gadgets.
+
+The scripts `Gadgetron/fully_sampled_recon_single_chain.py`, `Gadgetron/fully_sampled_recon_single_chain_short.py` and `Gadgetron/fully_sampled_recon_two_chains.py` show the reconstruction of fully sampled data with explicit use of chains of Gadgetron gadgets. The first of them demonstrates the use of two standard Gadgetron fully sampled reconstruction chains. The second demonstrates the use of Gadgetron's gadgets together with a gadget set provided by SIRF. The last one shows how a Gadgetron reconstruction chain can be split into 2 separate chains - a preprocessing chain and a reconstruction chain - with data filtering applied between these chains.
+
+### GRAPPA Undersampled reconstructions
+
+The script `grappa_basic.py` shows basic reconstruction of data acquired with GRAPPA undersampling without explicit use of Gadgetron gadgets.
+
+The script `Gadgetron/grappa_detail.py` is similar to `grappa_basic.py` but with more annotations in code, output of g-factors and explicit use of gadgets.
+
+The script `grappa_and_steepest_descent.py` shows how to use MR acquisition model to improve the accuracy of GRAPPA reconstruction via the steepest descent iterations.
+
+### Other
+
+The script `acquisition_data.py` shows how to access and manipulate acquisition data.
+
+The script `acquisition_model.py` shows how to generate simulated acquisition data and backproject it into image space (see `grappa_and_steepest_descent.py` demo for an illustration on how this functionality can be employed in the improvement of the accuracy of reconstruction).
+
+The script `coil_sensitivity_maps.py` demonstrates methods for calculating coil sensitivity maps.
+
+The script `noncartesian_recon.py` illustrates the use of a non-cartesian
+radial phase-encoding acquisition model for reconstruction.
+
+The script `noncartesian_cg_sense.py` illustrates how to use a non-cartesian
+radial phase-encoding acquisition model to reconstruct data iteratively and
+without the use of any k-space density weighting.

examples/Python/PET/README.md

@@ -1,11 +1,31 @@
-This folder contains scripts intended to be run from the command line.
-For instance,
-```bash
-python acquisition_model.py 
-```
-The demos also have some options. Try
-```bash
-python acquisition_model.py --help
-```
-
-Check the `interactive` folder for demos that you run from an IDE.
+This folder contains scripts demonstrating the use of SIRF for PET reconstruction and related tasks.
+
+All scripts currently use STIR as the reconstruction engine but actually allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `make_Poisson_loglikelihood` function etc.
+
+See the [Python/README](../README.md) for instructions.
+
+
+| demo script  | purpose |
+|--|--|
+|`acquisition_data.py`  | illustrates acquisition data handling|
+|`acquisition_data_from_scanner_info.py`  | shows how to create acquisition data from scanner parameters and axial compression etc.|
+|`acquisition_model.py` | illustrates the use of PET acquisition model: creates an image, projects it to simulate acquisition data and backprojects simulated data|
+|`acquisition_sensitivity_from_attenuation.py`  | illustrates acquisition sensitivity model representing attenuation factor|
+|`acquisition_sensitivity_from_bin_efficiencies.py`  | illustrates acquisition sensitivity model representing bin efficiencies factor|
+|`acquisition_sensitivity_from_ecat8.py`  | illustrates acquisition sensitivity model based on ECAT8 bin normalisation|
+|`fbp2d_reconstruction.py`  | illustrates reconstruction by two-dimensional filtered backprojection|
+|`get_multiplicative_sinogram.py`  | illustrates obtaining  multiplicative sinograms from normalisation and/or attenuation|
+|`hkem_reconstruction.py`  | illustrates Hybrid Kernelized Expectation Maximization reconstruction|
+| input_output.py | illustrates reading/writing acquisition data and images from/to files|
+|`listmode_to_sinograms.py`  | illustrates the conversion of listmode data to sinograms|
+|`osem_reconstruction.py`  | illustrates reconstruction by Ordered Subsets (OS) version of the One Step Late (OSL) algorithm of Green et al for Maximum a Posteriori (MAP) maximisation|
+|`osem_reconstruction_gpu.py` | implements the above OSMAPOSL reconstruction on GPU|
+|`osl_reconstruction.py` | illustrates reconstruction by OSMAPOSL algorithm with penalty term|
+|`osl_reconstruction.py` | illustrates reconstruction by Ordered Subsets Separable Paraboloidal Surrogate (OSSPS) algorithm|
+|`randoms_from_listmode.py`  | illustrates estimation of randoms from listmode data|
+|`reconstruct_from_listmode.py`  | illustrates the conversion of listmode data to sinograms with subsequent reconstruction|
+|`scatter_estimation.py`  | illustrates estimation of scatter|
+|`scatter_simulation.py`  | illustrates simulation of scatter|
+|`steepest_ascent.py` | applies few steps of steepest ascent for the maximization of Poisson log-likelihood objective function using subset gradients|
+|`STIR_acquisition_model_using_raytracing` | illustrates setting advanced parameters in STIR acquisition model that uses raytracing|
+|`osl_reconstruction.py` | Python implementation of OSMAPOSL algorithm with penalty term|

examples/Python/PETMR/README.md

@@ -0,0 +1,5 @@
+This folder contains simple scripts demonstrating the use of SIRF for
+PETMR related tasks. There are examples on synergistic image reconstruction
+in  our Jupyter notebooks in the [SIRF Exercises](https://github.com/SyneRBI/SIRF-Exercises/#readme).
+
+See the [Python/README](../README.md) for instructions.

examples/Python/README.md

@@ -1,14 +1,22 @@
-This folder's subfolders contain Python demo scripts for PET and MR reconstruction.
+This folder's subfolders contains Python demo scripts.
 
-Note that the SIRF Python utilities should be in your `PYTHONPATH` (see the
-installation instructions).
+For a brief description of each script's purpose and usage type
+```sh
+python <script_name>.py --help
+```
+(on the VM use `python3` instead of `python`).
 
-To run the demo scripts, please create an environment variable 
-`SIRF_PATH` with as value the location of your SIRF source, e.g. 
-`/home/sirfuser/devel/SIRF`.
-If you do not do this, you can still run the non-interactive demos but
-you will have to give full path to raw data files via 
-command-line options `-p` or `--path`.
+Note that the SIRF Python utilities should be in your `PYTHONPATH` (see the installation instructions).
 
-NOTE: on Windows, you must use / in paths, not \\.
+See [the main README section](../README.md#environment-variables) for information
+on environment variables.
+If you do not set the environment variables that allow SIRF to find the example data,
+you can still run most demos but you will have to give full path to raw data files via command-line options `-p` or `--path`.
+
+## Subfolders:
+- [MR](MR#readme)
+- [PET](PET#readme)
+- [PETMR](PETMR#readme)
+- [Registration](Registration#readme)
+- [SPECT](SPECT#readme)
 

examples/Python/Registration/README.md

@@ -0,0 +1,5 @@
+This folder contains scripts demonstrating the use of SIRF for image registration reconstruction and related tasks.
+
+Scripts currently use NiftyReg or SPM as the registration engine
+
+See the [Python/README](../README.md) for instructions.

examples/Python/SPECT/README.md

@@ -0,0 +1,5 @@
+This folder contains scripts demonstrating the use of SIRF for SPECT reconstruction and related tasks.
+
+All scripts currently use STIR as the reconstruction engine but actually allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `make_Poisson_loglikelihood` function etc.
+
+See the [Python/README](../README.md) for instructions.

examples/README.md

@@ -1,9 +1,58 @@
 This directory contains examples and demos on how to use SIRF. 
-Please also see the [related Wiki page](https://github.com/CCPPETMR/SIRF/wiki/Examples).
+
+Please also our Jupyter notebooks in the [SIRF Exercises](https://github.com/SyneRBI/SIRF-Exercises/#readme)
+which are more extensive and allow you to learn step-by-step.
+
 
 Most of the demos use simplistic data for illustration. The images might therefore be
 not very interesting either. The idea here is to illustrate what you can do with SIRF,
 not to give you a polished script that you would want to use on a daily basis.
 
 The demos display usually some images. Generally, these might not make too much sense
 unless you have a look at the code.
+
+The structure of the examples subfolder is as follows:
+
+    examples
+        Matlab
+            MR
+                Gadgetron
+            PET
+            PETMR
+            Registration
+        Python
+            MR
+                Gadgetron
+            PET
+            PETMR
+            Registration
+            SPECT
+                interactive
+
+The contents of subfolder named Python are described [here](Python/README.md). The contents of subfolder named Matlab are of similar nature but are not documented as we no longer support Matlab.
+
+## Environment variables
+
+The correct setup of SIRF requires defining the environment variables `SIRF_PATH` and `SIRF_INSTALL_PATH`.
+
+If you built SIRF with the SIRF-Superbuild, these environment variables can be sourced from the `env_sirf.*` files, e.g.
+on Unix/Linux [`env_sirf.sh`](https://github.com/SyneRBI/SIRF-SuperBuild/blob/master/env_sirf.sh.in).
+
+Alternatively,  `SIRF_PATH` should be set by the user to the full path to the root folder containing the SIRF source,
+and `SIRF_INSTALL_PATH` to the full path to the folder where the user installed SIRF binaries and other files (i.e.
+set by `CMAKE_INSTALL_PREFIX`).
+
+Additionally, the user may define the variable `SIRF_DATA_PATH` to point to an alternative location. For instance, when the
+installation files are in a write-protected location, the user can make a copy elsewhere and point there.
+
+<!--
+(NOTE: even on Windows, you must use `/` in paths, not `\\`.)
+-->
+
+### Examples data path
+
+The resolution order for the examples data path is:
+
+1. The directory pointed by `${SIRF_DATA_PATH}` if it is set by the user.
+2. The directory `${SIRF_INSTALL_PATH}/share/SIRF-<version_major>.<version_minor>` if `SIRF_INSTALL_PATH` is set.
+3. The directory `${SIRF_PATH}/data/examples` if `SIRF_PATH` is set.