Merge pull request #6 from qupath/pr/5

Pr/5
qupath · May 29, 2020 · ae653a1 · ae653a1
2 parents d6ed452 + 3d34aec
commit ae653a1
Show file tree

Hide file tree

Showing 26 changed files with 243 additions and 84 deletions.
diff --git a/docs/tutorials/cell_classification.rst b/docs/tutorials/cell_classification.rst
diff --git a/docs/tutorials/cell_detection.rst b/docs/tutorials/cell_detection.rst
@@ -71,24 +71,24 @@ Therefore the *Single threshold* option should be ticked, and only the first thr
   Positive cell detection dialog
 
 After pressing the *Run* button on the dialog, the results should appear as below.
-In this case, the original single 'annotation object' has been added to with 1207 'detection objects' (the cells).
+In this case, the original single 'annotation object' has been added to with 1088 'detection objects' (the cells).
 While the annotation is selected, you can also see from the panel on the left that 12.4% of the detected cells are classed as positive.
 
 .. note::
-  For a quick recap on the difference between annotation and detection objects, see [Introducing objects](First-steps#introducing-objects)
+  For a quick recap on the difference between annotation and detection objects, see `Introducing objects <../starting/first_steps.html#introducing-objects>`_.
 
-  .. figure:: images/ki67_detecting_final_markup.jpg
-    :class: shadow-image
-    :width: 75%
-    :align: center
+.. figure:: images/ki67_detecting_final_markup.jpg
+  :class: shadow-image
+  :width: 75%
+  :align: center
 
-    Positive cell detection image results
+  Positive cell detection image results
 
-  If you find that the cells do not appear, check that you do not have detection objects hidden.
-  This is controlled with the *Show/hide detection objects* button on the toolbar |icon_detections|.
-  You can also control whether the detections are shown 'hollow' or 'filled' with the button beside |icon_detections_fill|.
+If you find that the cells do not appear, check that you do not have detection objects hidden.
+This is controlled with the *Show/hide detection objects* button on the toolbar |icon_detections|.
+You can also control whether the detections are shown 'hollow' or 'filled' with the button beside |icon_detections_fill|.
 
-  It is a good idea to use these buttons (or their shortcuts :kbd:`D` and :kbd:`F`) to help confirm that the cells have been correctly detected.
+It is a good idea to use these buttons (or their shortcuts :kbd:`D` and :kbd:`F`) to help confirm that the cells have been correctly detected.
 
 
 View cell-by-cell results
@@ -119,7 +119,7 @@ A threshold of around 0.1 looks like it is likely to perform well (note, the thr
 .. note::
   The fact that a considerable number of the cells appear to have *negative* DAB OD staining (i.e. values below zero) - which ought not to be possible - the histogram suggests that the stain separation has not been perfect.
 
-  A small proportion of negative values is generally tolerable because of the inherent limitations in trying to quantify DAB staining in imperfect images, however the situation can (and in this case probably should) be improved using the [[Estimate-stains]] command.
+  A small proportion of negative values is generally tolerable because of the inherent limitations in trying to quantify DAB staining in imperfect images, however the situation can (and in this case probably should) be improved using the *Estimate stains* command.
   However, it is important to note that when the stain estimates are improved then all cell detection should be repeated.
 
 Analyze additional annotations
@@ -151,7 +151,7 @@ View results
 ============
 
 Whenever you have multiple annotations, it can be helpful to generate a results table for these.
-This is similar to creating a results table for detections, but requires the :menuselection:`Measure --> Show annotation measurements`; command instead.
+This is similar to creating a results table for detections, but requires the :menuselection:`Measure --> Show annotation measurements` command instead.
 You can also access this command from the *Measurement table* icon in the toolbar |icon_table|.
 
 .. figure:: images/ki67_detecting_results_annotations.jpg
@@ -161,6 +161,8 @@ You can also access this command from the *Measurement table* icon in the toolba
 
   Annotation results table
 
+Note that the figure above was taken before adding a fourth annotation (and detecting its cells).
+
 
 .. tip::
   You can use the :guilabel:`Convert detections to points` button within the **Points tool** |icon_points| to generate an editable points annotation from the detected cells.

diff --git a/docs/tutorials/exporting_measurements.rst b/docs/tutorials/exporting_measurements.rst
@@ -0,0 +1,131 @@
+**********************
+Exporting measurements
+**********************
+
+.. include:: ../tools.txt
+
+There are 3 different ways to export measurements within QuPath, via:
+
+1. the *measurement table*
+2. the *measurement exporter*
+3. a *script*
+
+Which one to use is up to you and depends on what you want to do.
+
+.. note::
+
+  As a rule of thumb, if you have:
+
+  * **a single image**: use the measurement table
+  * **multiple images**: use the *Measurement Exporter* or a script
+
+=========================
+Via the measurement table
+=========================
+
+The measurement table allows you to export measurements from a single image, currently opened in the viewer.
+It is therefore **not** recommended if you wish to export measurements for multiple images or across a whole project.
+Nevertheless, it is a good method to get some direct visualisation of what will be exported, before actually exporting anything.
+
+
+As mentioned in `Introducing objects <../starting/first_steps.html#introducing-objects>`_, you can create a measurement table by selecting the **Table** button in the toolbar |icon_table|.
+After choosing the objects you wish to export (e.g. detections, annotations), a similar measurement table to the one below will be shown on screen.
+
+.. figure:: images/measurement_table.png
+  :width: 70%
+  :align: center
+
+  Saving cell detection measurements via the measurement table.
+
+You can then save your measurement by pressing **Save** and choosing an appropriate name for your output ``.txt`` file.
+
+.. note::
+
+  This method creates a table with different columns, which all depend on the objects (and measurements) present in your image.
+
+  If your analysis involves combining measurements from different images, it is recommended to use the Measurement Exporter, detailed in the next subsection.
+
+============================
+Via the Measurement Exporter
+============================
+
+The cleanest way to export different types of measurements in QuPath across multiple images is with the **Measurement Exporter**.
+
+Provided that your images are stored in a :doc:`project <../tutorials/projects>`, you can access it through :menuselection:`Measure --> Export measurements` (as well as |icon_table| --> Export measurements).
+
+.. figure:: images/measurement_exporter.png
+  :width: 70%
+  :align: center
+  :class: shadow-image
+
+  The Measurement Exporter
+
+From there, you can decide from which image(s) the measurements will the be exported (similar to the :doc:`Run for project <../scripting/workflows_to_scripts>` command in the script editor).
+
+Below the image selection, a small number of parameters will allow you to shape your output file as needed:
+
+1. **Output file**: The desired `full path` location of your output file
+2. **Export type**: The measurement type to be exported (e.g. cells)
+3. **Separator**: The character that will be written to separate the measurement values (e.g. a tab)
+4. **Columns to include** (optional): The list of measurements to include in the export (if left empty, all existing measurements are included)
+
+.. note::
+  If you wish to **only** export specific measurements, the :guilabel:`Populate` button is what you need.
+  This will populate a list from which you can choose the exact columns to include in the export.
+  This list is constructed after performing a scan of all the selected images to check which measurements exist, and should only take a couple of seconds.
+  This means that you must have selected image(s) to do this.
+
+  Note that if an image is missing measurements for a specified column, empty values will be written to the output file.
+
+.. important::
+
+  If you have an open image in an active viewer, be sure to always save your data before running the measurement exporter.
+  A small red-colored warning will appear to remind you.
+
+
+=============
+Via scripting
+=============
+
+In cases where you would want to automate your analysis and exporting process, the Measurement Exporter can be easily used with scripting.
+To do so, you can create a ``MeasurementExporter``, customize it the way you want it, then call ``exportMeasurements(outputFile)`` to start the export process.
+
+The following script demonstrates a standard pipeline for exporting cell measurements from all the images in the current project to an output file ``measurements.tsv``.
+
+.. code-block:: groovy
+
+  import qupath.lib.gui.tools.MeasurementExporter
+  import qupath.lib.objects.PathCellObject
+
+  // Get the list of all images in the current project
+  def project = getProject()
+  def imagesToExport = project.getImageList()
+
+  // Separate each measurement value in the output file with a tab ("\t")
+  def separator = "\t"
+
+  // Choose the columns that will be included in the export
+  // Note: if 'columnsToInclude' is empty, all columns will be included
+  def columnsToInclude = new String[]{"Name", "Class", "Nucleus: Area"}
+
+  // Choose the type of objects that the export will process
+  // Other possibilities include:
+  //    1. PathAnnotationObject
+  //    2. PathDetectionObject
+  //    3. PathRootObject
+  // Note: import statements should then be modified accordingly
+  def exportType = PathCellObject.class
+
+  // Choose your *full* output path
+  def outputPath = "M:/measurements.tsv"
+  def outputFile = new File(outputPath)
+
+  // Create the measurementExporter and start the export
+  def exporter  = new MeasurementExporter()
+                    .imageList(imagesToExport)            // Images from which measurements will be exported
+                    .separator(separator)                 // Character that separates values
+                    .includeOnlyColumns(columnsToInclude) // Columns are case-sensitive
+                    .exportType(exportType)               // Type of objects to export
+                    .exportMeasurements(outputFile)        // Start the export process
+
+  print "Done!"
diff --git a/docs/tutorials/images/ki67_auto_cells_detected.jpg b/docs/tutorials/images/ki67_auto_cells_detected.jpg
diff --git a/docs/tutorials/images/ki67_auto_final_markup.jpg b/docs/tutorials/images/ki67_auto_final_markup.jpg
diff --git a/docs/tutorials/images/ki67_auto_map_raw.jpg b/docs/tutorials/images/ki67_auto_map_raw.jpg
diff --git a/docs/tutorials/images/ki67_auto_map_smoothed.jpg b/docs/tutorials/images/ki67_auto_map_smoothed.jpg
diff --git a/docs/tutorials/images/ki67_auto_original.jpg b/docs/tutorials/images/ki67_auto_original.jpg
diff --git a/docs/tutorials/images/ki67_auto_parallel.jpg b/docs/tutorials/images/ki67_auto_parallel.jpg
diff --git a/docs/tutorials/images/ki67_auto_smooth_features.jpg b/docs/tutorials/images/ki67_auto_smooth_features.jpg
diff --git a/docs/tutorials/images/ki67_auto_training_first.jpg b/docs/tutorials/images/ki67_auto_training_first.jpg
diff --git a/docs/tutorials/images/ki67_auto_training_intensity.jpg b/docs/tutorials/images/ki67_auto_training_intensity.jpg
diff --git a/docs/tutorials/images/ki67_auto_training_ring.jpg b/docs/tutorials/images/ki67_auto_training_ring.jpg
diff --git a/docs/tutorials/images/ki67_auto_training_tumor.jpg b/docs/tutorials/images/ki67_auto_training_tumor.jpg
diff --git a/docs/tutorials/images/ki67_auto_training_updated.jpg b/docs/tutorials/images/ki67_auto_training_updated.jpg
diff --git a/docs/tutorials/images/ki67_detecting_annotation.jpg b/docs/tutorials/images/ki67_detecting_annotation.jpg
diff --git a/docs/tutorials/images/ki67_detecting_final_markup.jpg b/docs/tutorials/images/ki67_detecting_final_markup.jpg
diff --git a/docs/tutorials/images/ki67_detecting_multiple_parallel_annotations.jpg b/docs/tutorials/images/ki67_detecting_multiple_parallel_annotations.jpg
diff --git a/docs/tutorials/images/ki67_detecting_multiple_rois.jpg b/docs/tutorials/images/ki67_detecting_multiple_rois.jpg
diff --git a/docs/tutorials/images/ki67_detecting_origin.jpg b/docs/tutorials/images/ki67_detecting_origin.jpg
diff --git a/docs/tutorials/images/ki67_detecting_positive_dialog.jpg b/docs/tutorials/images/ki67_detecting_positive_dialog.jpg
diff --git a/docs/tutorials/images/ki67_detecting_results_annotations.jpg b/docs/tutorials/images/ki67_detecting_results_annotations.jpg
diff --git a/docs/tutorials/images/ki67_detecting_results_detections.jpg b/docs/tutorials/images/ki67_detecting_results_detections.jpg
diff --git a/docs/tutorials/images/measurement_exporter.png b/docs/tutorials/images/measurement_exporter.png
diff --git a/docs/tutorials/images/measurement_table.png b/docs/tutorials/images/measurement_table.png
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -11,6 +11,7 @@ Tutorials
   measuring_areas
   cell_detection
   cell_classification
+  exporting_measurements
   multiplex_analysis
   pixel_classification
   superpixels