WIP on long-form documentation.

#69

docs_source/source/quick_start.rst

@@ -2,4 +2,46 @@ Quick-start
 ===========
 
 Before you begin, you need to:
-    1. Install MIRP (see :ref:`installation`).
+    1. Install MIRP (see :ref:`installation`).
+    2. Have a dataset with imaging and corresponding masks.
+
+Computing quantitative features
+-------------------------------
+Suppose you have a dataset of computed tomography (CT) DICOM images with corresponding segmentations. Suppose that both
+images and masks are located split by patient directories ``path/to/data``. For each patient, the CT image is in the
+``image`` directory, and its corresponding segmentation in ``mask``. For patient ``patient_003``, the full path to the
+image directory is ``path/to/data/patient_003/image``, and to the mask directory is ``path/to/data/patient_003/mask``.
+
+We want to compute features from the gross tumour mask (called ``GTV``). We are interested in the soft-tissue range,
+with Hounsfield Units between -150 and 200 HU. To harmonise differences in resolution and slice distance
+between CT images from different patients, all voxels are resampled to a 1.0 by 1.0 by 1.0 mm size. Histogram and
+texture features are computed after discretisation using the `fixed bin size` method with a bin size of 25 Hounsfield
+Units.
+
+.. code-block:: python
+
+    import pandas as pd
+    from mirp import extract_features
+
+    feature_data = extract_features(
+        image="path/to/data",
+        mask="path/to/data",
+        image_sub_folder="image",
+        mask_sub_folder="mask",
+        roi_name="GTV",
+        new_spacing=1.0,
+        resegmentation_intensity_range=[-150.0, 200.0],
+        base_discretisation_method="fixed_bin_size",
+        base_discretisation_bin_width=25.0
+    )
+
+The above code results in ``feature_data``, a list of ``pandas.DataFrame`` that contains feature values for every
+patient. These can combined into a single ``pandas.DataFrame`` as follows:
+
+.. code-block:: python
+
+    feature_data = pd.concat(feature_data)
+
+Computing quantitative features from filtered images
+----------------------------------------------------
+

test/documentation_example_test.py

@@ -1,9 +1,30 @@
 import os
 import numpy as np
+import pandas as pd
 
 CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
 
 
+def test_quick_start():
+    from mirp import extract_features
+
+    feature_data = extract_features(
+        image=os.path.join(CURRENT_DIR, "data", "sts_images"),
+        mask=os.path.join(CURRENT_DIR, "data", "sts_images"),
+        image_sub_folder=os.path.join("CT", "dicom", "image"),
+        mask_sub_folder=os.path.join("CT", "dicom", "mask"),
+        roi_name="GTV_Mass_CT",
+        new_spacing=1.0,
+        resegmentation_intensity_range=[-150.0, 200.0],
+        base_discretisation_method="fixed_bin_size",
+        base_discretisation_bin_width=25.0
+    )
+
+    feature_data = pd.concat(feature_data)
+
+    assert len(feature_data) == 3
+
+
 def test_extract_features_examples():
     from mirp import extract_features