Add a few feature examples

Author: AdvancedImagingUTSW

docs/source/user_guide/acquiring_home.rst

@@ -6,4 +6,5 @@ Acquiring Data
    :maxdepth: 2
 
    acquiring_guide
-   features
+   features/features
+   features/example_feature_lists

docs/source/user_guide/features/example_feature_lists.rst

@@ -0,0 +1,70 @@
+=====================
+Example Feature Lists
+=====================
+
+Fairly complex imaging sequences can be created by chaining together multiple
+features. Here are a few examples of feature lists that can be used to create custom
+acquisition protocols.
+
+
+Multi-Position Imaging with Automated Autofocus
+------------------------------------------------
+
+Large volumes are often acquired in a tiling format, where the sample is imaged at
+multiple positions. In some cases, if the sample is not perfectly transparent, the focus
+may need to be adjusted at each position. This can be done automatically using the
+autofocus feature.
+#. You can load customized functions in the software by selecting the menu
+
+Here, we begin by moving to the first position of the multi-position table, then move to
+the first z-position, measure the autofocus, set the F_Start position, move to the last
+z-position, measure the autofocus, set the F_End position, and image the full z-stack
+prior to moving to the next position in the multi-position table.
+
+.. code-block:: python
+
+    [
+        {"name": PrepareNextChannel,},
+        (
+            {"name": MoveToNextPositionInMultiPositionTable,"args": (None,None,None,),},
+            {"name": CalculateFocusRange,},
+            {"name": ZStackAcquisition,"args": (True,True,"z-stack",),},
+            {"name": WaitToContinue,},
+            {"name": LoopByCount,"args": ("experiment.MicroscopeState.multiposition_count",),},
+        ),
+    ]
+
+
+-----------
+
+Time-Lapse Imaging with Automated Autofocus
+--------------------------------------------
+
+Time-lapse imaging is a common technique used to monitor changes in samples over time
+. If you do not have a hardware solution for maintaining the focus of the specimen, a
+common technique for maintaining the focus of a microscope is to intermittently measure
+the focus using the image as a metric.
+
+.. code-block:: python
+
+    [
+        (
+            {"name": PrepareNextChannel, },
+            (
+                {"name": Snap, "args": (True,),},
+                {"name": LoopByCount, "args": (10,),},
+            ),
+            {"name": LoopByCount, "args": (2,),},),
+            {"name": PrepareNextChannel, },
+            {"name": WaitToContinue, },
+            (
+                {"name": Autofocus, "args": ("stage","z",),},
+                (
+                    {"name": Snap, "args": (True,),},
+                    {"name": LoopByCount, "args": (5,),},
+                ),
+                {"name": StackPause, "args": ("experiment.MicroscopeState.timepoints",),},
+                {"name": LoopByCount, "args": (10,),},
+            ),
+        ),
+    ]

docs/source/user_guide/features.rst renamed to docs/source/user_guide/features/features.rst

@@ -155,8 +155,8 @@ Editing Feature Lists on the Fly
    .. image:: images/step_18.png
 
 
-#. Click one feature in the preview window, a :guilabel:`Feature Parameters` window 
-   will show up. Then set the desired parameters (e.g., :guilabel:`planes` 
+#. Click one feature in the preview window, a :guilabel:`Feature Parameters` window
+   will show up. Then set the desired parameters (e.g., :guilabel:`planes`
    in this screenshot). Close the :guilabel:`Feature Parameters` window.
 
 
@@ -189,13 +189,13 @@ Text Representation of Feature Lists
 
 At the bottom of each of the :guilabel:`Feature List Configuration` frames above, there
 is a text box with a textual representation of the feature list. As an alternative to
-point-and-click editing, a user can update feature lists by editing this textual 
+point-and-click editing, a user can update feature lists by editing this textual
 representation and then pressing :guilabel:`Preview`.
 
 The square brackets ``[]`` create a sequence of events to run in the feature container.
-The ``{}`` braces contain features. The parentheses ``()`` indicate a loop. 
+The ``{}`` braces contain features. The parentheses ``()`` indicate a loop.
 
-As an example, let's look at the feature list that describes the 
+As an example, let's look at the feature list that describes the
 :ref:`Continuous Scan <user_guide/acquiring_guide:continuous scan>` mode:
 
 .. code-block:: python
@@ -211,12 +211,12 @@ As an example, let's look at the feature list that describes the
     ]
 
 Here, we have a sequence defined by ``[]`` containing one element, a loop, indicated
-by the closed parentheses. There are two features within this loop. One feature has the 
+by the closed parentheses. There are two features within this loop. One feature has the
 name
 :doc:`PrepareNextChannel <../_autosummary/navigate.model.features.common_features.PrepareNextChannel>`
-and the other 
+and the other
 :doc:`LoopByCount <../_autosummary/navigate.model.features.common_features.LoopByCount>`.
-The parentheses indicate we will keep looping through both of these features until 
+The parentheses indicate we will keep looping through both of these features until
 stopping criteria is met. In this case, the looping will stop when ``LoopByCount``
 returns ``False`` due to running out of ``selected_channels`` to loop through. That is,
 it will end once all :ref:`selected channel <user_guide/gui_walkthrough:channel settings>` have