Fix docs landing page

docs/data.rst

@@ -1,14 +1,21 @@
 Data Format
 ===========
 
-RIESLING uses `HDF5 <https://www.hdfgroup.org/solutions/hdf5>`_ to store input, intermediate and output data. A command is provided to convert the ``.h5`` format to NiFTI (``.nii``).
+RIESLING uses `HDF5 <https://www.hdfgroup.org/solutions/hdf5>`_ to store input, intermediate and output data. A command is provided to convert reconstructed images in ``.h5`` format to NiFTI (``.nii``).
 
-**Important** RIESLING uses the column-major / fastest-varying first convention internally. The dimensions below are specified in column-major order. HDF5 uses the row-major convention. When interacting with RIESLING via HDF5 you will need to reverse the order of the dimensions.
-
-HDF5 uses a row-major convention, if your software is column major (RIESLING is internally) then the order of the dimensions given below should be reversed.
+Complex Numbers
+---------------
 
 All data in RIESLING is complex-valued. HDF5 does not have a native complex-valued datatype, hence a compound datatype with ``r`` and ``i`` members corresponding to the real and imaginary parts must be used.
 
+Dimension Order
+---------------
+
+RIESLING uses *column-major / fastest-varying first convention* internally. The dimensions below are written in column-major order. However HDF5 uses row-major convention. RIESLING reverses the order of the dimensions when reading/writing files from/to HDF5. The Matlab and Python file utilities handle this reversal correctly. If constructing your own HDF5 file for use with RIESLING please take care with the order of the dimensions.
+
+Dimensions
+----------
+
 The terminology in RIESLING is:
 - "Channel" corresponds to one element in a multi-channel/multi-element receive coil. In contrast to other toolkits RIESLING stores the channels as the fastest-varying index, i.e. the data for each k-space point across all channels is stored contiguously.
 - "Sample" is a single complex-valued k-space sample.

docs/faq.rst

@@ -32,15 +32,15 @@ Help! My data is anisotropic!
 
 Various places in the ``riesling`` code used to make assumptions that both the matrix- and voxel-sizes were isotropic. These assumptions have mostly been removed and anisotropic data can be reconstructed quite happily.
 
-A potential difficulty is that by default ``riesling`` will work with a 256 mm isotropic field of view during iterations, before cropping to the nominal field of view at the end. If one dimension of the nominal field of view is too small, ``riesling`` will not be able to create sensitivity maps large enough. The simplest way to fix this is to specify a suitable size with the ``--sense-fov=x,y,z`` option, where the units ``x,y,z`` match the units of the voxel size in the header (usually mm). An alternative is to increase the oversampling beyond 2, but you should check your data actually supports higher oversampling first.
+A potential difficulty is that by default ``riesling`` will work with a 256 mm isotropic field of view during iterations, before cropping to the nominal field of view at the end. If one dimension of the nominal field of view is too small, ``riesling`` will not be able to create sensitivity maps large enough. The simplest way to fix this is to specify a suitable size with the ``--sense-fov=x,y,z`` option, where the units ``x,y,z`` match the units of the voxel size in the header (usually mm). Setting any of ``x,y,z`` to 0 will use the nominal FOV. An alternative is to increase the oversampling beyond 2, but you should check your data actually supports higher oversampling first.
 
 
 What if I have Cartesian data?
 ------------------------------
 
-The default gridding options in ``riesling`` were picked for non-cartesian data and likely will not work with a cartesian dataset. In particular, a twice over-sampled grid is used and the FOV during iterations (determined by `--sense-fov``) is expanded to 256 mm on the basis that most non-cartesian acquisitions oversample the center of k-space and so in practice acquire signal from outside the nominal FOV. These settings will cause artefacts during an iterative recon with cartesian data.
+The default gridding options in ``riesling`` were picked for non-cartesian data and likely will not work with a cartesian dataset. In particular, a twice over-sampled grid is used and the FOV during iterations (determined by ``--sense-fov``) is expanded to 256 mm on the basis that most non-cartesian acquisitions oversample the center of k-space and so in practice acquire signal from outside the nominal FOV. These settings will cause artefacts during an iterative recon with cartesian data.
 
-Adding ``--sense-fov=0,0,0`` will instead crop the sensitivity maps tightly the FOV. I then recommend addding either ``--osamp=1.3`` or ``--osamp=1 --kernel=NN``. The latter will effectively switch off the NUFFT functionality and run a plain FFT instead.
+Adding ``--sense-fov=0,0,0`` will instead crop the sensitivity maps to the nominal FOV. I then recommend addding either ``--osamp=1.3`` or ``--osamp=1 --kernel=NN``. The latter will effectively switch off the NUFFT functionality and run a plain FFT.
 
 Which regularizer should I pick with ADMM?
 ------------------------------------------

docs/index.rst

@@ -3,23 +3,41 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to RIESLING!
-====================================
+RIESLING
+========
 
-.. image:: riesling-logo.png
+.. image:: ../riesling-logo.png
    :alt: RIESLING Logo
 
-RIESLING is a reconstruction toolbox tuned for 3D radial MRI - the name stands for Radial Interstices Enable Speedy Low-volume imagING - but it can process other trajectories as well.
+Radial Interstices Enable Speedy Low-volume imagING (RIESLING) is a tool for reconstructing non-cartesian MRI scans. It was developed for reconstructing 3D radial center-out trajectories associated with Zero Echo-Time (ZTE) or Ultrashort Echo-Time (UTE) sequences. These trajectories provide unique challenges in efficient reconstruction compared to Cartesian trajectories (both 2D and 3D). However it is capable of reconstructing any trajectory.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
+   :caption: Contents
 
-   contents
+   faq
+   data
+   recon
+   util
+   op
 
-Indices and tables
-==================
+Commands
+--------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+RIESLING is provided as a single executable file, similar to ``bart``. The ``riesling`` executable provides multiple individual commands, which vary from basic utilities to interrogate files to complete reconstruction pipelines. To see a full list of commands currently available, run ``riesling``. Detailed help for each command can be found in the category pages: :doc:`util`, :doc:`op`, and :doc:`recon`. The full list is not repeated here as they are subject to change. However, the most useful are:
+
+- ``riesling h5`` Prints information about compatible ``.h5`` files
+- ``riesling rss`` Performs the most basic reconstruction possible
+- ``riesling admm`` Regularized least-squares reconstruction, similar to ``bart pics``. *You probably want this one*.
+
+RIESLING exploits the inherent oversampling of most non-Cartesian trajectories at the center of k-space to generate SENSE maps directly from the input data, but utilities are provided to explicitly extract sensitivities if desired. Further details can be found in :doc:`util`. Internally, similarly to BART, RIESLING pipelines are constructed as a series of Linear Operators. These operators are exposed as individual commands if you wish to build up your own pipeline, see :doc:`op`.
+
+Examples
+--------
+
+A `tutorial notebook <https://github.com/spinicist/riesling-examples/tutorial.ipynb>`_ can be run interactively at on `MyBinder <https://mybinder.org/v2/gh/spinicist/riesling-examples/HEAD?filepath=tutorial.ipynb>`_. This explains the various steps required to generate a simulated phantom dataset and then reconstruct it.
+
+Input Data
+----------
+
+An important step with using RIESLING is providing data in the correct ``.h5`` format. Details of this format can be found in :doc:`data`. Matlab code to generate these files is provided in the ``/matlab`` directory of the repository. Users of the ZTE sequence on GE platforms should contact the authors to discuss conversion strategies.

docs/recon.rst

@@ -177,7 +177,7 @@ Uses the Alternating Directions Method-of-Multipliers to add regularizers to the
 
 * ``--scale=bart/otsu/S``
 
-    The optimal regularization strength λ depends both on the particular regularizer and the typical intensity values in the unregularized image. To make values of λ roughly comparable, it is usual to scale the data such that the intensity values are approximately 1 during the optimization (and then unscale the final image). By default ``riesling`` will perform a NUFFT and then use Otsu's method to find the median foreground intensity as the scaling factor. Alternatively the BART automatic scaling can ne chosen, or a fixed scaling value which _multiplies_ the data can be specified. In the latter case, the NUFFT will not be performed.
+    The optimal regularization strength λ depends both on the particular regularizer and the typical intensity values in the unregularized image. To make values of λ roughly comparable, it is usual to scale the data such that the intensity values are approximately 1 during the optimization (and then unscale the final image). By default ``riesling`` will perform a NUFFT and then use Otsu's method to find the median foreground intensity as the scaling factor (specify ``otsu`` to make this explicit). The BART automatic scaling can be chosen with ``bart``. Alternately a fixed numeric *multiplicative* scaling factor can be specified, which will skip the initial NUFFT. If you already know the approximate scaling of your data (from a test recon), this option will be the fastest.
 
 *Regularization Options*