Fix/docs2 (#554)

* fix: prioritized the use of subordinate metadata when choosing between feature level and subordinate level

* fix: updated installation instructions on MacOS

* feat, wip: revising optimize workflow step section

* feat: added screen shots for workflow edit/view

* feat: added section on feature finding selection filtering

* feat: added section for debugging automated QC/QA

Author: dmccloskey

docs/guide/install.rst

@@ -40,5 +40,5 @@ A warning from Windows Defender SmartScreen may appear.
 Example on MacOS
 ----------------
 
-.. todo::
-    Add instructions how to install SmartPeak on MacOS.
+Download latest release for MacOS, e.g. ``SmartPeak-1.26.0-Darwin.dmg``. 
+Drag and drop **both** the application files **and** `share` folder from the SmartPeak installation to the MacOS `Applications` folder.

docs/start/features.rst

@@ -1,12 +1,14 @@
 SmartPeak Features
 =============================================================================
 
-SmartPeak provides a plethora of features for analytical chemistry data processing.  An incomplete set of features are described below.
+SmartPeak provides a plethora of features for analytical chemistry data processing.
+An incomplete set of features are described below.
 
 Audit trail and data provenance
 -----------------------------------------------------------------------------
 
-A complete record of all actions and data processing steps invoked by the user is often required in regulated environments.  In addition, for debugging, it is useful to have a record of all actions the software has taken.
+A complete record of all actions and data processing steps invoked by the user is often required in regulated environments.
+In addition, for debugging, it is useful to have a record of all actions the software has taken.
 
 SmartPeak records all actions and data processing steps for audit trail and debugging purposes at two levels: 1) an application log, and 2) feature log.
 
@@ -292,41 +294,54 @@ Optimize workflow step algorithm parameters
 Usage
 ~~~~~
 
-.. todo::
-    Describe the usage.
+The algorithms behind each workflow step can be optimized and fine-tuned for each particular use case.
+The parameters used in a workflow can be viewed and modified through ``View | Workflow settings | Parameters``.
 
-Example
-~~~~~~~
+.. image:: ../images/workflow_parameters_view.png
 
-.. todo::
-    Provide an example.
+The parameters that have been specified by the user are shown in white, defaults not set by the user are shown in grey, and unused paramters are shown in blue.
+Hovering over the name of the parameter displays a tooltip that provides a brief explanation of what the paramter does.
 
-Debug feature picking, selection, and filtering (and acquisition methods)
------------------------------------------------------------------------------
+.. image:: ../images/workflow_parameters_edit.png
 
-Usage
-~~~~~
+Examples of optimized parameters for different acquisition methods are provided in the :ref:`tutorials`.
 
-.. todo::
-    Describe the usage.
+Example 1: Debug feature finding, selection, and filtering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Example
-~~~~~~~
+The first part of developing an automated data processing method is to optimize the feature finding, selection, and filtering paramters.
+We recommend using the bulk statistics in ``View | Statistics`` and visualizations provided in ``View | Chromatograms`` to gain intuition about how each of the parameter changes affect feature finding, selection, and filtering.
+We also recommend using the feature reports in ``Actions | Report`` and exporting the long (Feature DB) or matrix (Feature Table) formats to get a more fine-grained view of how each of the parameter changes affect feature finding, selection, and filtering.
 
-.. todo::
-    Provide an example.
+**Feature Finding**
+The feature finding step entails (optionally) smoothing and integrating the features (also called peaks or convex hulls) in 2D (e.g., XIC chromatogram of intensity vs time or XIC spectrum of time vs m/z) or 3D (e.g., intensity vs time vs m/z).
+Note that multiple features are found in any given chromatogram or spectrum.
+Additional steps including baseline normalizing, windowing, etc. are available to preprocess the data before running the feature finding step.
+For single reaction monitoring (SRM/MRM) or data independent (DIA) methods, the ``MRMFeatureFinderScoring`` functions are the ones to be manipulated.
+For data dependent (DDA) or full scan methods, the ``FeatureFindingMetabo``, ``ElutionPeakDetection``, ``MassTraceDetection`` functions are the ones to be manipulated.
+*Check that all features are being found and properly integrated prior to moving on to Feature Selection!*
 
-Enable automated QC/QA of workflows
------------------------------------------------------------------------------
+**Feature Selection**
+The feature selection step entails aligning the retention time of features and selecting the most probable feature.
+Feature alignment is one of the biggest bottlenecks in targeted and non-targeted chromatography-based mass spectrometry.
+SmartPeak provides an advanced feature alignment algorithm that is based on relative retention time instead of absolute retention time to allow for accurate feature alignment even when retention time shifts of several minutes occur.
+For single reaction monitoring (SRM/MRM) or data independent (DIA) methods, the ``MRMFeatureSelector.schedule_MRMFeatures_qmip` functions are the ones to be manipulated.
+*Check that all features are being properly selected prior to moving on to Feature Filtering!*
 
-Usage
-~~~~~
+**Feature Filtering**
+The feature filtering step removes features from a chromatogram or spectrum based on user specified criteria.
+Feature filtering can be performed before or after feature selection.
+The feature filters are specified in the ``ComponentGroupFilters.csv`` and ``ComponentFilters.csv`` files for filtering at the ComponentGroup (TransitionGroup in SRM) and Component (Tansition in SRM) levels, respectively.
+It is our experience that if the feature finding and selection parameters have been well optimized, the feature filtering step is not needed.
+However, there are use cases where there are only a few components (transitions in SRM) that make optimal feature selection difficult, and feature filtering can come in handy.
 
-.. todo::
-    Describe the usage.
+Example 2: Debug automated QC/QA of workflows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Example
-~~~~~~~
+The next part of developing an automated data processing method is to optimize the QC/QA reporting metrics.
+We recommend using the feature reports in ``Actions | Report`` and exporting the long (Feature DB) or matrix (Feature Table) formats after checking ``QC_transition_message``, ``QC_transition_score``, ``QC_transition_group_message``, and ``QC_transition_group_score`` to get a more fine-grained view of how each of the parameter changes affect feature finding, selection, and filtering.
 
-.. todo::
-    Provide an example.
+**Feature QC**
+The feature QC step flags features from a chromatogram or spectrum based on user specified criteria (same algorithm and similar format to Feature Filtering above).
+Feature QC can be performed at anytime during a data processing workflow.
+The feature QCs are specified in the ``ComponentGroupQCs.csv`` and ``ComponentQCss.csv`` files for QC/QA at the ComponentGroup (TransitionGroup in SRM) and Component (Tansition in SRM) levels, respectively.