WIP: FLIM script RTD example

docs/ops/doc/examples/example_flim_analysis.rst

@@ -0,0 +1,85 @@
+=============
+FLIM Analysis
+=============
+
+In this example we will use SciJava Ops within Fiji to perform `FLIM_` analysis on a sample from TODO that is TODO.
+This technique can be used to TODO
+
+SciJava Ops via Fiji's sripting engine with `script parameters`_:
+
+Loading the sample data
+-----------------------
+
+With the sample data downloaded, it can be loaded into Fiji with `Bio-Formats`_ using `File → Open`. When presented with the ``Bio-Formats Import Options`` screen, it may be helpful to select ``Metadata viewing → Display metadata`` to determine values necessary for analysis. Then, select ``OK``.data
+
+When presented with the ``Bio-Formats File Stitching`` window, again select ``OK``. The data may take a minute to load.data
+
+Running the script
+------------------
+
+.. tabs::
+
+    .. code-tab:: scijava-groovy
+
+       #@ OpEnvironment ops
+       #@ ROIService roiService
+       #@ Dataset input
+       #@ Float (description="The total time (ns) (timeBase in metadata)", label = "Time Base") timeBase
+       #@ Integer (description="The number of time bins (timeBins in metadata)", label = "Time Bins") timeBins
+       #@ Integer (description="The index of the lifetime axis (from metadata)", label = "Lifetime Axis", value=2) lifetimeAxis
+       #@ Integer (description="The time slice to analyze", label = "Slice", value = 12) c
+       #@OUTPUT Img Z
+       #@OUTPUT Img A1
+       #@OUTPUT Img Tau
+       #@OUTPUT Img pseudocolored
+
+       // Utility function to collapse all ROIs into a single mask for FLIM fitting
+       def getMask() {
+        // No ROIs
+        if (!roiService.hasROIs(input)) {
+            return null
+        }
+        // 1+ ROIs
+        rois = roiService.getROIs(input)
+        mask = rois.children()remove(0).data()
+        for(roi: rois.children()) {
+            mask = mask.or(roi.data())
+        }
+        return mask;
+       }
+
+       // The FitParams contain a set of reasonable defaults for FLIM curve fitting
+       import org.scijava.ops.flim.FitParams
+       param = new FitParams()
+       param.transMap = ops.op("transform.hyperSliceView").arity3().input(input, 2, c).apply()
+
+       // xInc is the difference (ns) between two bins
+       param.xInc = timeBase / timeBins
+       param.ltAxis = lifetimeAxis
+
+       // Fit curves
+       rld = ops.op("flim.fitRLD").arity2().input(param, getMask()).apply()
+
+       // The fit results paramMap is a XYC image, with result attributes along the Channel axis
+       fittedImg = rld.paramMap
+       // For RLD, we have Z, A1, and Tau as the three attributes
+       Z = ops.op("transform.hyperSliceView").arity3().input(fittedImg, lifetimeAxis, 0).apply()
+       A1 = ops.op("transform.hyperSliceView").arity3().input(fittedImg, lifetimeAxis, 1).apply()
+       Tau = ops.op("transform.hyperSliceView").arity3().input(fittedImg, lifetimeAxis, 2).apply()
+       // Finally, generate a pseudocolored result
+       pseudocolored = ops.op("flim.pseudocolor").arity1().input(rld).apply()
+
+Observing the outputs
+---------------------
+
+The script above will present 4 output images, each of which should be contrasted using ImageJ's B&C plugin (``Ctrl + Shift + C``) for ideal viewing. Using that plugin, the minimum and maximum can be set by selecting the ``Set`` option:
+*. The ``Z`` image should be set to ``[0, 1]``
+*. The ``A1`` image can be left as is.
+*. The ``Tau`` image should be set to ``[0, 1]``
+*. The ``Pseudocolored`` image can be left as is.
+
+The outputs then look like the following: TODO: upload to media.imagej.net and link.
+
+.. _`Bio-Formats` : https://www.openmicroscopy.org/bio-formats/
+.. _`FLIM` : https://en.wikipedia.org/wiki/Fluorescence-lifetime_imaging_microscopy
+.. _`script parameters`: https://imagej.net/scripting/parameters