Update docs

src/deepmr/io/header/__init__.py

@@ -17,6 +17,11 @@
 def read_acquisition_header(filepath, *args, device="cpu", verbose=False, **kwargs):
     """
     Read acquisition header from file.
+    
+    The header info (e.g., k-space trajectory, shape) can be used to 
+    simulate acquisitions or to inform raw data loading (e.g., via ordering)
+    to reshape from acquisition to reconstruction ordering and image post-processing
+    (transposition, flipping) and exporting.
 
     Parameters
     ----------

src/deepmr/io/kspace/__init__.py

@@ -34,9 +34,112 @@ def read_rawdata(filepath, acqheader=None, device="cpu", verbose=0):
     Returns
     -------
     data : torch.tensor
-        Complex k-space data of shape (nslices, ncoils, ncontrasts, nviews, nsamples).
+        Complex k-space data.
     head : deepmr.Header
         Metadata for image reconstruction.
+        
+     Example
+    -------
+    >>> import deepmr
+
+    Get the filename for an example .mrd file.
+
+    >>> filepath = deepmr.testdata("mrd")
+
+    Load the file contents.
+
+    >>> data, head = deepmr.io.read_matfile(filepath)
+
+    The result is a data/header pair. 'Data' contains k-space data.
+    Here, it represents a 2D spiral acquisition with 1 slice, 36 coils, 32 arms and 1284 samples per arm:
+    
+    >>> data.shape
+    torch.Size([1, 36, 1, 32, 1284])
+    
+    'Head' contains the acquisition information. We can inspect the k-space trajectory and dcf size,
+    the expected image shape and resolution:
+    
+    >>> head.traj.shape
+    torch.Size([1, 32, 1284, 2])
+    >>> head.dcf.shape
+    torch.Size([1, 32, 1284])
+    >>> head.shape
+    tensor([  1, 192, 192])
+    >>> head.ref_dicom.SliceThickness
+    '5.0'
+    >>> head.ref_dicom.PixelSpacing
+    [1.56, 1.56]
+
+    Notes
+    -----
+    The returned 'data' tensor contains raw k-space data. Dimensions are defined as following:
+        * 2Dcart: (nslices, ncoils, ncontrasts, ny, nx).
+        * 2Dnoncart: (nslices, ncoils, ncontrasts, nviews, nsamples).
+        * 3Dcart: (nx, ncoils, ncontrasts, nz, ny).
+        * 3Dnoncart: (ncoils, ncontrasts, nviews, nsamples).
+    When possible, data are already pre-processed:
+        * For Cartesian data (2D and 3D) readout oversampling is removed
+            if the number of samples along readout is larger than the number of
+            rows in the image space (shape[-1]).
+        * For Non-Cartesian (2D and 3D), fov is centered according to trajectory and 
+            isocenter info from the header.
+        * Separable acquisitions (3D stack-of-Non-Cartesians and 3D Cartesians),
+            k-space is decoupled via FFT (along slice and readout axes, respectively).
+            
+    The returned 'head' (deepmr.io.types.Header) is a structure with the following fields:
+    
+        * shape (torch.Tensor):
+            This is the expected image size of shape (nz, ny, nx).
+        * t (torch.Tensor): 
+            This is the readout sampling time (0, t_read) in ms.
+            with shape (nsamples,).
+        * traj (torch.Tensor): 
+            This is the k-space trajectory normalized as (-0.5, 0.5) 
+            with shape (ncontrasts, nviews, nsamples, ndims).
+        * dcf (torch.Tensor): 
+            This is the k-space sampling density compensation factor
+            with shape (ncontrasts, nviews, nsamples).
+        * FA (torch.Tensor, float): 
+            This is either the acquisition flip angle in degrees or the list
+            of flip angles of shape (ncontrasts,) for each image in the series.
+        * TR (torch.Tensor, float): 
+            This is either the repetition time in ms or the list
+            of repetition times of shape (ncontrasts,) for each image in the series.
+        * TE (torch.Tensor, float): 
+            This is either the echo time in ms or the list
+            of echo times of shape (ncontrasts,) for each image in the series.
+        * TI (torch.Tensor, float): 
+            This is either the inversion time in ms or the list
+            of inversion times of shape (ncontrasts,) for each image in the series.
+        * user (dict):
+            User parameters. Common parameters are:
+                * ordering (torch.Tensor): 
+                    Indices for reordering (acquisition to reconstruction)
+                    of acquired k-space data, shaped (3, nslices * ncontrasts * nview), whose rows are
+                    'contrast_index', 'slice_index' and 'view_index', respectively.
+                * mode (str): 
+                    Acquisition mode ('2Dcart', '3Dcart', '2Dnoncart', '3Dnoncart').
+                * separable (bool): 
+                    Whether the acquisition can be decoupled by fft along slice / readout directions
+                    (3D stack-of-noncartesian / 3D cartesian, respectively) or not (3D noncartesian and 2D acquisitions).
+                * slice_profile (torch.Tensor): 
+                    Flip angle scaling along slice profile of shape (nlocs,).
+                * basis (torch.Tensor): 
+                    Low rank subspace basis for subspace reconstruction of shape (ncoeff, ncontrasts).
+        * affine (np.ndarray): 
+            Affine matrix describing image spacing, orientation and origin of shape (4, 4).
+        * ref_dicom (pydicom.Dataset): 
+            Template dicom for image export.
+        * flip (list): 
+            List of spatial axis to be flipped after image reconstruction.
+            The default is an empty list (no flipping).
+        * transpose (list): 
+             Permutation of image dimensions after reconstruction, depending on acquisition mode:
+                * 2Dcart: reconstructed image has (nslices, ncontrasts, ny, nx) -> transpose = [1, 0, 2, 3] 
+                * 2Dnoncart: reconstructed image has (nslices, ncontrasts, ny, nx) -> transpose = [1, 0, 2, 3] 
+                * 3Dcart: reconstructed image has (ncontrasts, nz, ny, nx) -> transpose = [0, 1, 2, 3] 
+                * 3Dnoncart: reconstructed image has (nx, ncontrasts, nz, ny) -> transpose = [1, 2, 3, 0] 
+            The default is an empty list (no transposition).
     """
     tstart = time.time()
     if verbose >= 1: