danforthcenter · nfahlgren · Jul 22, 2021 · Mar 2, 2021 · Mar 9, 2021 · Mar 9, 2021
diff --git a/docs/analysis_approach.md b/docs/analysis_approach.md
@@ -118,7 +118,7 @@ These are the general categories of object analysis that are available in PlantC
 *  Object shape parameters: see the [analyze shape](analyze_shape.md) and [analyze bound](analyze_bound_horizontal.md) functions.
 *  Object color or other signal intensity values: see the [analyze color](analyze_color.md), 
 [analyze NIR](analyze_NIR_intensity.md), [analyze thermal](analyze_thermal_values.md),
-and [analyze FvFm](photosynthesis_analyze_fvfm.md) functions.
+and [analyze FvFm](photosynthesis_analyze_yii.md) functions.
 *  Object classification (For example, classification of disease symptoms, identification of organ structures 
 [naive-bayesian multiclass mode](naive_bayes_multiclass.md)).
 *  Object hyperspectral parameters: see the [analyze spectral](analyze_spectral.md) and [analyze index](analyze_index.md) functions.

diff --git a/docs/img/documentation_images/analyze_npq/npq_colormap.png b/docs/img/documentation_images/analyze_npq/npq_colormap.png
diff --git a/docs/img/documentation_images/analyze_npq/npq_histogram.png b/docs/img/documentation_images/analyze_npq/npq_histogram.png
diff --git a/docs/img/documentation_images/fluor_fvfm/dark_fluor_induction.png b/docs/img/documentation_images/fluor_fvfm/dark_fluor_induction.png
diff --git a/docs/img/documentation_images/fluor_fvfm/fdark.jpg b/docs/img/documentation_images/fluor_fvfm/fdark.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/fmax.jpg b/docs/img/documentation_images/fluor_fvfm/fmax.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/fmin.jpg b/docs/img/documentation_images/fluor_fvfm/fmin.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/fqfm_colormap.png b/docs/img/documentation_images/fluor_fvfm/fqfm_colormap.png
diff --git a/docs/img/documentation_images/fluor_fvfm/fqfm_histogram.png b/docs/img/documentation_images/fluor_fvfm/fqfm_histogram.png
diff --git a/docs/img/documentation_images/fluor_fvfm/fvfm_colormap.png b/docs/img/documentation_images/fluor_fvfm/fvfm_colormap.png
diff --git a/docs/img/documentation_images/fluor_fvfm/fvfm_histogram.jpg b/docs/img/documentation_images/fluor_fvfm/fvfm_histogram.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/fvfm_histogram.png b/docs/img/documentation_images/fluor_fvfm/fvfm_histogram.png
diff --git a/docs/img/documentation_images/fluor_fvfm/fvfm_images.jpg b/docs/img/documentation_images/fluor_fvfm/fvfm_images.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/fvfm_pseudocolored.jpg b/docs/img/documentation_images/fluor_fvfm/fvfm_pseudocolored.jpg
diff --git a/docs/img/documentation_images/fluor_fvfm/light_fluor_induction.png b/docs/img/documentation_images/fluor_fvfm/light_fluor_induction.png
diff --git a/docs/img/tutorial_images/psII/cropreporter_images.png b/docs/img/tutorial_images/psII/cropreporter_images.png
diff --git a/docs/img/tutorial_images/psII/eroded_plant_mask.png b/docs/img/tutorial_images/psII/eroded_plant_mask.png
diff --git a/docs/img/tutorial_images/psII/f0_fill_holes_mask.png b/docs/img/tutorial_images/psII/f0_fill_holes_mask.png
diff --git a/docs/img/tutorial_images/psII/f0_img.png b/docs/img/tutorial_images/psII/f0_img.png
diff --git a/docs/img/tutorial_images/psII/f0_otsu_mask.png b/docs/img/tutorial_images/psII/f0_otsu_mask.png
diff --git a/docs/img/tutorial_images/psII/fdark2.png b/docs/img/tutorial_images/psII/fdark2.png
diff --git a/docs/img/tutorial_images/psII/filled_plant_mask2.png b/docs/img/tutorial_images/psII/filled_plant_mask2.png
diff --git a/docs/img/tutorial_images/psII/fmax2.png b/docs/img/tutorial_images/psII/fmax2.png
diff --git a/docs/img/tutorial_images/psII/fmax_rescaled2.png b/docs/img/tutorial_images/psII/fmax_rescaled2.png
diff --git a/docs/img/tutorial_images/psII/fmin2.png b/docs/img/tutorial_images/psII/fmin2.png
diff --git a/docs/img/tutorial_images/psII/fvfm_hist2.png b/docs/img/tutorial_images/psII/fvfm_hist2.png
diff --git a/docs/img/tutorial_images/psII/id_obj2.png b/docs/img/tutorial_images/psII/id_obj2.png
diff --git a/docs/img/tutorial_images/psII/objcomp2.png b/docs/img/tutorial_images/psII/objcomp2.png
diff --git a/docs/img/tutorial_images/psII/plant_mask2.png b/docs/img/tutorial_images/psII/plant_mask2.png
diff --git a/docs/img/tutorial_images/psII/pseudocolored.png b/docs/img/tutorial_images/psII/pseudocolored.png
diff --git a/docs/img/tutorial_images/psII/shapes2.png b/docs/img/tutorial_images/psII/shapes2.png
diff --git a/docs/output_measurements.md b/docs/output_measurements.md
@@ -145,15 +145,22 @@ suggestions for additional metadata we should track that would be useful to you,
 
 ## Output Observations
 
-Functions that automatically store data to the [`Outputs` class](outputs.md) are [acute_vertex](acute_vertex.md), [analyze_color](analyze_color.md),
-[analyze_bound_horizontal](analyze_bound_horizontal.md), [analyze_bound_vertical](analyze_bound_vertical.md), [analyze_nir_intensity](analyze_NIR_intensity), 
-[analyze_object](analyze_shape.md), [analyze_thermal_values](analyze_thermal_values.md), [photosynthesis.analyze_fvfm](photosynthesis_analyze_fvfm.md), [hyperspectral.analyze_spectral](analyze_spectral.md),
-[hyperspectral.analyze_index](analyze_index.md), [landmark_reference_pt_dist](landmark_reference_pt_dist.md), [morphology.check_cycles](check_cycles.md), 
-[morphology.fill_segments](fill_segments.md), [morphology.find_tips](find_tips.md), [morphology.find_branch_pts](find_branch_pts.md), [morphology.segment_angle](segment_angle.md), 
-[morphology.segment_curvature](segment_curvature.md), [morphology.segment_euclidean_length](segment_euclidean_length.md), 
-[morphology.segment_insertion_angle](segment_insertion_angle.md), [morphology.segment_path_length](segment_pathlength.md), 
-[morphology.segment_tangent_angle](segment_tangent_angle.md), [report_size_marker_area](report_size_marker.md), [watershed_segmentation](watershed.md),
-[within_frame](within_frame.md), [x_axis_pseudolandmarks](x_axis_pseudolandmarks.md), and [y_axis_pseudolandmarks](y_axis_pseudolandmarks.md). All of these functions include an optional `label` parameter 
+Functions that automatically store data to the [`Outputs` class](outputs.md) are [acute_vertex](acute_vertex.md), 
+[analyze_color](analyze_color.md), [analyze_bound_horizontal](analyze_bound_horizontal.md), 
+[analyze_bound_vertical](analyze_bound_vertical.md), [analyze_nir_intensity](analyze_NIR_intensity),
+[analyze_object](analyze_shape.md), [analyze_thermal_values](analyze_thermal_values.md), 
+[photosynthesis.analyze_fvfm](photosynthesis_analyze_yii.md), 
+[photosynthesis.analyze_npq](photosynthesis_analyze_npq.md), [hyperspectral.analyze_spectral](analyze_spectral.md),
+[hyperspectral.analyze_index](analyze_index.md), [landmark_reference_pt_dist](landmark_reference_pt_dist.md), 
+[morphology.check_cycles](check_cycles.md), [morphology.fill_segments](fill_segments.md), 
+[morphology.find_tips](find_tips.md), [morphology.find_branch_pts](find_branch_pts.md), 
+[morphology.segment_angle](segment_angle.md), [morphology.segment_curvature](segment_curvature.md), 
+[morphology.segment_euclidean_length](segment_euclidean_length.md),
+[morphology.segment_insertion_angle](segment_insertion_angle.md), 
+[morphology.segment_path_length](segment_pathlength.md), [morphology.segment_tangent_angle](segment_tangent_angle.md), 
+[report_size_marker_area](report_size_marker.md), [watershed_segmentation](watershed.md),
+[within_frame](within_frame.md), [x_axis_pseudolandmarks](x_axis_pseudolandmarks.md), and 
+[y_axis_pseudolandmarks](y_axis_pseudolandmarks.md). All of these functions include an optional `label` parameter 
 that allows users to append custom prefixes to the unique variable identifier. 
 
 For more detail about the traits measured by each function see the [Observation Traits Summary Table](https://docs.google.com/spreadsheets/d/1gk5VocBA-63gyF_vA6yPNvWreZ1R7-_z4vOfm37YBl8/edit?usp=sharing).
diff --git a/docs/photosynthesis_analyze_fvfm.md b/docs/photosynthesis_analyze_fvfm.md
diff --git a/docs/photosynthesis_analyze_npq.md b/docs/photosynthesis_analyze_npq.md
@@ -0,0 +1,58 @@
+## Analyze Nonphotochemical Quenching of Photosystem II
+
+Extract estimates of the nonphotochemical quenching (NPQ) of Photosystem II (PSII). 
+Calculates (Fm/Fm') - 1 data from a masked region. The photosynthesis subpackage is dependent on a PSII_Data instance file structure as created by photosynthesis.read_* files.
+
+**plantcv.photosynthesis.analyze_npq**(*ps_da_light, ps_da_dark, mask, bins=256, measurement_labels = None, label="default"*)
+
+**returns** Histogram of NPQ values and an NPQ image
+
+- **Parameters:**
+    - ps_da_light - photosynthesis xarray DataArray for which to compute npq
+    - ps_da_dark - photosynthesis xarray DataArray that contains frame_label `Fm`
+    - mask - binary mask of selected contours
+    - bins - number of grayscale bins (0-256 for 8-bit images and 0 to 65,536), if you would like to bin data, you 
+      would alter this number (default bins=256)
+    - measurement_labels - list of label(s) for each measurement in `ps_da_light`, modifies the variable name of observations recorded
+    - label - Optional label parameter, modifies the entity name of observations recorded. (default `label="default"`)
+- **Context:**
+    - Used to extract NPQ per identified plant pixel.
+    - Generates histogram of NPQ values.
+    - Generates an NPQ image.
+- **Example use:**
+    - [Use In PSII Tutorial](psII_tutorial.md)
+- **Output data stored:** Data ('npq_hist_{measurement_label}', 'npq_max_{measurement_label}', 'npq_median_{measurement_label}') are automatically stored to the 
+  [`Outputs` class](outputs.md) when this function is run. These data can be accessed during a workflow (example below). `{measurement_label}` is automatically created when importing the dataset, e.g. with `read_cropreporter()` but can be overwritten with `measurement_labels` argument.
+  [Summary of Output Observations](output_measurements.md#summary-of-output-observations)
+
+```python
+from plantcv import plantcv as pcv
+
+# Set global debug behavior to None (default), "print" (to file), 
+# or "plot" (Jupyter Notebooks or X11)
+pcv.params.debug = "print"
+
+# Analyze NPQ   
+npq, npq_hist = pcv.photosynthesis.analyze_npq(ps_da_light=ps.lightadapted, ps_da_dark=ps.darkadapted, mask=kept_mask, bins=256, label="fluor")
+
+# Access data stored out from fluor_NPQ
+# the default measurement label for cropreporter data is t1
+npq_median = pcv.outputs.observations['fluor']['npq_median_t1']['value']
+
+# Pseudocolor the NPQ image
+pseudo_img = pcv.visualize.pseudocolor(gray_img=npq, mask=kept_mask, min_value=0, max_value=1, title="NPQ")
+
+```
+
+**Histogram of NPQ values**
+
+![Screenshot](img/documentation_images/analyze_npq/npq_histogram.png)
+
+**Pseudocolored output image based on NPQ**
+
+![Screenshot](img/documentation_images/analyze_npq/npq_colormap.png)
+
+The grayscale NPQ image can be used with the [pcv.visualize.pseudocolor](visualize_pseudocolor.md) function
+which allows the user to pick a colormap for plotting.
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/photosynthesis/analyze_npq.py)
diff --git a/docs/photosynthesis_analyze_yii.md b/docs/photosynthesis_analyze_yii.md
@@ -0,0 +1,105 @@
+## Analyze the efficiency of Photosystem II
+
+Extract estimates of the efficiency (YII) of Photosystem II (PSII). The photosynthesis subpackage is dependent on a PSII_Data instance file structure as created by photosynthesis.read_* files.
+
+**plantcv.photosynthesis.analyze_yii**(*ps_da, mask, bins=256, measurement_labels=None, label="default"*)
+
+**returns** YII histogram, and YII image
+
+- **Parameters:**
+    - ps_da - photosynthesis xarray DataArray for which to compute yii. Can either have a pair of frames F0,Fm or pair(s) of Fp,Fmp
+    - mask - binary mask of plant
+    - bins - number of grayscale bins (0-256 for 8-bit images and 0 to 65,536), if you would like to bin data, you would alter this number (default bins=256)
+    - measurement_labels - list of label(s) for each measurement, modifies the default variable names of observations. must have same length as number of measurements in ps_da
+    - label - Optional label parameter, modifies the entity name of observations recorded. (default `label="default"`)
+- **Context:**
+    - Used to extract Fv/Fm, Fv'/Fm' or Fq'/Fm' per identified plant pixel.
+    - Generates histogram of Fv/Fm, Fv'/Fm' or Fq'/Fm' data.
+    - Generates an Fv/Fm, Fv'/Fm' or Fq'/Fm' image.
+- **Example use:**
+    - [Use In PSII Tutorial](psII_tutorial.md)
+- **Output data stored:** Data ('yii_hist_{measurement_label}', 'yii_max_{measurement_label}', 'yii_median_{measurement_label}' automatically gets stored to the 
+  [`Outputs` class](outputs.md) when this function is run. These data can always get accessed during a workflow 
+  (example below). [Summary of Output Observations](output_measurements.md#summary-of-output-observations)
+
+**Fluorescence images**
+
+![Screenshot](img/documentation_images/fluor_fvfm/fvfm_images.jpg)
+
+From top-left to bottom-right: Dark-adapted (Fdark, F0, Fm) and Light-adapted (Flight', F', and Fm')
+
+**Analyze Fv/Fm**
+
+```python
+from plantcv import plantcv as pcv
+
+# Set global debug behavior to None (default), "print" (to file), 
+# or "plot" (Jupyter Notebooks or X11)
+pcv.params.debug = "print"
+
+# photosynthesis read functions will read fluroescence data into predefined data format that includes at least attribute 'darkadapted'
+ps = pcv.photosynthesis.read_cropreporter(filename = "mydata.inf")
+
+# Analyze Fv/Fm    
+fvfm, fvfm_hist = pcv.photosynthesis.analyze_yii(ps_da=ps.darkadapted, 
+mask=kept_mask, 
+measurement_labels=["Fv/Fm"],
+bins=256, 
+label="fluor")
+
+# Access data stored out from fluor_fvfm
+fvfm_median = pcv.outputs.observations['fluor']['yii_median_Fv/Fm']['value']
+
+# Pseudocolor the Fv/Fm image
+fvfm_cmap= pcv.visualize.pseudocolor(gray_img=fvfm, mask=kept_mask, min_value=0, max_value=1, title="Fv/Fm")
+
+# or you can use xarray builtin plot methods (output not shown):
+fvfm.plot()
+```
+
+**Histogram of Fv/Fm values**
+
+![Screenshot](img/documentation_images/fluor_fvfm/fvfm_histogram.png)
+
+**Pseudocolored output image based on Fv/Fm**
+
+![Screenshot](img/documentation_images/fluor_fvfm/fvfm_colormap.png)
+
+**Analyze Fq'/Fm' (lightadapted mesaurements)**
+
+```python
+from plantcv import plantcv as pcv
+
+# Set global debug behavior to None (default), "print" (to file), 
+# or "plot" (Jupyter Notebooks or X11)
+pcv.params.debug = "print"
+
+# Analyze Fq'/Fm'    
+fqfm, fqfm_hist = pcv.photosynthesis.analyze_yii(ps=ps.lightadapted, mask=kept_mask,                                                         
+bins=256, 
+measurement_labels=["Fq'/Fm'"],
+label="fluor")
+
+# Access data stored out from fluor_fvfm
+fqfm_median = pcv.outputs.observations['fluor']["yii_median_Fq'/Fm'"]['value']
+
+fqfm_cmap= pcv.visualize.pseudocolor(gray_img=fqfm, mask=kept_mask, min_value=0, max_value=1, title="Fq'/Fm'")
+
+# or xarray plot method (output not shown)
+fqfm.plot(row = 'measurement', col_wrap = 3)
+# or
+fqfm.plot(col_wrap='measurement')
+```
+
+**Histogram of Fq'/Fm' values**
+
+![Screenshot](img/documentation_images/fluor_fvfm/fqfm_histogram.png)
+
+**Pseudocolored output image based on Fq'/Fm'**
+
+![Screenshot](img/documentation_images/fluor_fvfm/fqfm_colormap.png)
+
+The grayscale YII images can be used with the [pcv.visualize.pseudocolor](visualize_pseudocolor.md) function 
+which allows the user to pick a colormap for plotting.
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/photosynthesis/analyze_yii.py)
diff --git a/docs/photosynthesis_read_cropreporter.md b/docs/photosynthesis_read_cropreporter.md
@@ -1,20 +1,20 @@
 ## Read CropReporter Fluorescence Image Files
 
-Reads .DAT image data into numpy ndarray and reshapes the frames into a datacube before identifying and extracting `fdark`, `fmin`, and `fmax` as separate numpy ndarrays. 
+Reads .INF/.DAT image data into a PSII_data instance containing xarray DataArrays with labeled frames. 
 
 **plantcv.photosynthesis.read_cropreporter**(*filename*)
 
-**returns** fdark, fmin, fmax
+**returns** ps
 
 - **Parameters:**
-    - filename - image file to be read (possibly including a path)
+    - filename - INF metadata file to be read (possibly including a path). DAT files are automatically detected.
 
 - **Context:**
-    - Reads in file to be processed and does so using the metadata contained within a corresponding .INF file
+    - Reads in binary image files to be processed and does so using the metadata contained within a corresponding .INF file. Measurements from dark-adapted plant state are stored in the attribute `darkadapted`. Frames F0 and Fm are labeled according to the metadata in .inf. The default measurement label is 't0'. Measurements from light-adapted plant state are stored in the attribute `lightadapted`. Frames Fp and Fmp are labeled according to the metadata in .inf. The default measurement label is 't1'.
 - **Notes:**
-    - This function assumes a specific pattern between .DAT image files and their corresponding .INF file. 
-    We assume that for every image file `xx_PSD_xxx.DAT` there will be a corresponding metadata file with the same path
-    named `xx_HDR_xxx.INF` 
+    - This function assumes a specific pattern between .INF metadata file and their corresponding .DAT binary image filenames. 
+    We assume that for every metadata file `xx_HDR_xxx.INF` there will be a corresponding image files with the same path
+    named `xx_XXX_xxx.DAT` where XXX is the analysis protocol (e.g. PSD, PSL, etc.). Some crop reporter imaging protocols will results in multiple binary image .DAT files per .INF metadata file.  
 - **Example use:**
     - [Use In PSII Tutorial](psII_tutorial.md) 
 
@@ -27,8 +27,14 @@ from plantcv import plantcv as pcv
 pcv.params.debug = "print"
 
 #read in image
-fdark, fmin, fmax = pcv.photosynthesis.read_cropreporter(filename="PSII_PSD_20200826_22_rep6.DAT")
+ps = pcv.photosynthesis.read_cropreporter(filename="PSII_HDR_20200826_22_rep6.INF")
+
+# you can check which variables were imported at the prompt with:
+ps
+
+# to see the frames you imported use xarray plot methods e.g.
+ps.darkadapted.plot(col='frame_label', col_wrap=4)
 
 ```
 
-**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/photosynthesis/read_dat.py)
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/photosynthesis/read_cropreporter.py)
diff --git a/docs/print_image.md b/docs/print_image.md
@@ -4,7 +4,7 @@ Write image to the file specified. This is a wrapper for the OpenCV function [im
 for numpy arrays (like the images that get returned by most PlantCV functions), and can handle matplotlib Figures (like the one returned by [pcv.visualize.pseudocolor](visualize_pseudocolor.md)) 
 and plotnine ggplots (like the histograms returned in [pcv.analyze_nir_intensity](analyze_NIR_intensity.md), 
 [pcv.analyze_color](analyze_color.md), [pcv.visualize.histogram](visualize_histogram.md),
- and [pcv.photosynthesis.analyze_fvfm](photosynthesis_analyze_fvfm.md)).
+ and [pcv.photosynthesis.analyze_yii](photosynthesis_analyze_yii.md)).
 
 **plantcv.print_image**(*img, filename*)