Merge branch 'release-4.0' into release-4.0-mean-max-val

docs/analysis_approach.md

@@ -119,7 +119,7 @@ These are the general categories of object analysis that are available in PlantC
 and [analyze.bound_vertical](analyze_bound_vertical2.md) functions.
 * Object color or other signal intensity values: see the [analyze.color](analyze_color2.md), 
 [analyze.grayscale](analyze_grayscale.md), [analyze.thermal](analyze_thermal.md),
-and [analyze FvFm](photosynthesis_analyze_yii.md) functions.
+and [analyze.yii](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.spectral_index](analyze_spectral_index.md) functions.

docs/photosynthesis_analyze_npq.md → docs/analyze_npq.md

@@ -1,16 +1,20 @@
 ## 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.
+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, min_bin=0, max_bin="auto", measurement_labels=None, label="default"*)
+**plantcv.analyze.npq**(*ps_da_light, ps_da_dark, labeled_mask, n_labels=1, auto_fm=False, min_bin=0, max_bin="auto",
+measurement_labels=None, label="default"*)
 
-**returns** Histogram of NPQ values and an NPQ image
+**returns** NPQ DataArray and Histograms of NPQ values
 
 - **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
+ - labeled_mask - Labeled mask of objects (32-bit).
+ - n_labels - Total number expected individual objects (default = 1).
+ - auto_fm - Automatically calculate the frame with maximum fluorescence per label, otherwise use a fixed frame for all labels (default = False).
  - min_bin - minimum bin value ("auto" or user input minimum value - must be an integer). (default `min_bin=0`)
  - max_bin - maximum bin value ("auto" or user input maximum value - must be an integer). (default `max_bin="auto"`)
  - measurement_labels - list of label(s) for each measurement in `ps_da_light`, modifies the variable name of observations recorded
@@ -30,14 +34,14 @@ 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"
+pcv.params.debug = "plot"
 
 # Analyze NPQ 
-npq, npq_hist = pcv.photosynthesis.analyze_npq(ps_da_light=ps.lightadapted, ps_da_dark=ps.darkadapted, mask=kept_mask)
+npq, npq_hist = pcv.analyze.npq(ps_da_light=ps.lightadapted, ps_da_dark=ps.darkadapted, labeled_mask=kept_mask, label="plant")
 
 # Access the NPQ median value
 # the default measurement label for cropreporter data is t1
-npq_median = pcv.outputs.observations['fluor']['npq_median_t1']['value']
+npq_median = pcv.outputs.observations['plant1']['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")
@@ -55,4 +59,4 @@ pseudo_img = pcv.visualize.pseudocolor(gray_img=npq, mask=kept_mask, min_value=0
 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)
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/analyze/npq.py)

docs/photosynthesis_analyze_yii.md → docs/analyze_yii.md

@@ -1,20 +1,23 @@
 ## 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.
+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, measurement_labels=None, label="default"*)
+**plantcv.analyze.yii**(*ps_da, labeled_mask, n_labels=1, auto_fm=False, measurement_labels=None, label="default"*)
 
-**returns** YII histogram, and YII image
+**returns** YII DataArray, YII histograms
 
 - **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
+ - ps_da - Photosynthesis xarray DataArray (either darkadapted or lightadapted). Can either have a pair of frames F0,Fm or pair(s) of Fp,Fmp.
+ - labeled_mask - Labeled mask of objects (32-bit).
+ - n_labels - Total number expected individual objects (default = 1).
+ - auto_fm - Automatically calculate the frame with maximum fluorescence per label, otherwise use a fixed frame for all labels (default = False).
  - 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.
+ - Generates histograms of Fv/Fm, Fv'/Fm' or Fq'/Fm' data.
+ - Generates an Fv/Fm, Fv'/Fm' or Fq'/Fm' DataArray.
 - **Example use:**
  - [Use In PSII Tutorial](tutorials/psII_tutorial.md)
 - **Output data stored:** Data ('yii_hist_{measurement_label}', 'yii_max_{measurement_label}', 'yii_median_{measurement_label}' automatically gets stored to the 
@@ -23,7 +26,7 @@ Extract estimates of the efficiency (YII) of Photosystem II (PSII). The photosyn
 
 **Fluorescence images**
 
-![Screenshot](img/documentation_images/fluor_fvfm/fvfm_images.jpg)
+![Screenshot](img/documentation_images/analyze_yii/fvfm_images.jpg)
 
 From top-left to bottom-right: Dark-adapted (F-dark, F0, Fm) and Light-adapted (F-light', F', and Fm')
 
@@ -34,16 +37,16 @@ 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"
+pcv.params.debug = "plot"
 
 # 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, label="fluor")
+fvfm, fvfm_hist = pcv.analyze.yii(ps_da=ps.darkadapted, labeled_mask=kept_mask, label="plant")
 
 # Access Fv/Fm median value
-fvfm_median = pcv.outputs.observations['fluor']['yii_median_t0']['value']
+fvfm_median = pcv.outputs.observations['plant1']['yii_median_t0']['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")
@@ -54,11 +57,11 @@ fvfm.plot()
 
 **Histogram of Fv/Fm values**
 
-![Screenshot](img/documentation_images/fluor_fvfm/fvfm_histogram.png)
+![Screenshot](img/documentation_images/analyze_yii/fvfm_histogram.png)
 
 **Pseudocolored output image based on Fv/Fm**
 
-![Screenshot](img/documentation_images/fluor_fvfm/fvfm_colormap.png)
+![Screenshot](img/documentation_images/analyze_yii/fvfm_colormap.png)
 
 **Analyze Fq'/Fm' (lightadapted mesaurements)**
 
@@ -67,13 +70,13 @@ 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"
+pcv.params.debug = "plot"
 
 # Analyze Fq'/Fm' 
-fqfm, fqfm_hist = pcv.photosynthesis.analyze_yii(ps=ps.lightadapted, mask=kept_mask, label="fluor")
+fqfm, fqfm_hist = pcv.analyze.yii(ps=ps.lightadapted, labeled_mask=kept_mask, label="plant")
 
 # Access Fq'/Fm' median value
-fqfm_median = pcv.outputs.observations['fluor']["yii_median_t1"]['value']
+fqfm_median = pcv.outputs.observations['plant1']["yii_median_t1"]['value']
 
 fqfm_cmap = pcv.visualize.pseudocolor(gray_img=fqfm, mask=kept_mask, min_value=0, max_value=1, title="Fq'/Fm'")
 
@@ -85,13 +88,13 @@ fqfm.plot(col_wrap='measurement')
 
 **Histogram of Fq'/Fm' values**
 
-![Screenshot](img/documentation_images/fluor_fvfm/fqfm_histogram.png)
+![Screenshot](img/documentation_images/analyze_yii/fqfm_histogram.png)
 
 **Pseudocolored output image based on Fq'/Fm'**
 
-![Screenshot](img/documentation_images/fluor_fvfm/fqfm_colormap.png)
+![Screenshot](img/documentation_images/analyze_yii/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)
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/analyze/yii.py)

docs/binary_threshold.md

@@ -3,14 +3,13 @@
 Creates a binary image from a gray image based on the threshold values. 
 The object target can be specified as dark or light.
 
-**plantcv.threshold.binary**(*gray_img, threshold, max_value, object_type="light"*)
+**plantcv.threshold.binary**(*gray_img, threshold, object_type="light"*)
 
 **returns** thresholded/binary image
 
 - **Parameters:**
  - gray_img - Grayscale image data
  - threshold - Threshold value (0-255)
- - max_value - Value to apply above threshold (255 = white)
  - object_type - "light" or "dark" (default: "light"). If object is lighter than the background then standard 
  thresholding is done. If object is darker than the background then inverse thresholding is done.
 - **Context:**
@@ -39,7 +38,7 @@ pcv.params.debug = "plot"
 
 # Create binary image from a gray image based on threshold values, 
 # targeting light objects in the image.
-threshold_light = pcv.threshold.binary(gray_img=gray_img, threshold=36, max_value=255, object_type='light')
+threshold_light = pcv.threshold.binary(gray_img=gray_img, threshold=36, object_type='light')
 
 ```
 
@@ -51,7 +50,7 @@ threshold_light = pcv.threshold.binary(gray_img=gray_img, threshold=36, max_valu
 
 # Create binary image from a gray image based on threshold values, 
 # targeting dark objects in the image.
-threshold_dark = pcv.threshold.binary(gray_img=gray_img, threshold=36, max_value=255, object_type='dark')
+threshold_dark = pcv.threshold.binary(gray_img=gray_img, threshold=36, object_type='dark')
 
 ```
 

docs/output_measurements.md

@@ -154,6 +154,8 @@ Functions that automatically store data to the [`Outputs` class](outputs.md) are
 [analyze.spectral_index](analyze_spectral_index.md),
 [analyze.spectral_reflectance](analyze_spectral_reflectance.md),
 [analyze.thermal](analyze_thermal.md),
+[analyze.yii](analyze_yii.md), 
+[analyze.npq](analyze_npq.md),
 [homology.landmark_reference_pt_dist](homology_landmark_reference_pt_dist.md),
 [homology.x_axis_pseudolandmarks](homology_x_axis_pseudolandmarks.md), 
 [homology.y_axis_pseudolandmarks](homology_y_axis_pseudolandmarks.md),
@@ -166,9 +168,7 @@ Functions that automatically store data to the [`Outputs` class](outputs.md) are
 [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), 
-[photosynthesis.analyze_fvfm](photosynthesis_analyze_yii.md), 
-[photosynthesis.analyze_npq](photosynthesis_analyze_npq.md),
+[morphology.segment_tangent_angle](segment_tangent_angle.md),
 [report_size_marker_area](report_size_marker.md),
 [transform.find_color_card](find_color_card.md),
 [watershed_segmentation](watershed.md), and

docs/photosynthesis_reassign_frame_labels.md

@@ -1,21 +1,22 @@
 ## Reassign Frame Labels
 
 Relabel Fm and Fm' in PSII CropReporter datasets. The photosynthesis subpackage is dependent on a PSII_Data instance
-file structure as created by photosynthesis.read_cropreporter.
+file structure as created by `photosynthesis.read_cropreporter`.
 Some systems (e.g. CropReporter) output a timeseries of fluorescence images that can be used to calculate a fluorescence
 induction curve following a saturating light pulse. This function calculates the frame where maximum fluorescence is
-observed and relabels the Fm or Fm' frame, if needed.
+observed and relabels the Fm or Fm' frame, if needed. This can only be done globally, not on a per-plant basis in a
+multi-plant image. However, `pcv.analyze.yii` and `pcv.analyze.npq` can use this function to identify the optimal frame
+for each plant in a multi-plant image.
 
 **plantcv.photosynthesis.reassign_frame_labels**(*ps_da, mask*)
 
-**returns** xarray DataArray with updated frame labels, Fluorescence induction curve plot and corresponding dataframe
+**returns** xarray DataArray with updated frame labels
 
 - **Parameters:**
  - ps_da - photosynthesis xarray DataArray containing multiple post-saturating light pulse fluorescence images
  - mask - binary mask of plant
 - **Context:**
  - Used to assign Fm or Fm' based on observed plant fluorescence.
- - Generates a plot of fluorescence induction over a timeseries.
 - **Example use:**
  - [Use In PSII Tutorial](tutorials/psII_tutorial.md)
 
@@ -26,31 +27,23 @@ 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"
+pcv.params.debug = "plot"
 
-psd, psd_ind, psd_df = pcv.photosynthesis.reassign_frame_labels(ps_da=ps.darkadapted, mask=mask)
+psd = pcv.photosynthesis.reassign_frame_labels(ps_da=ps.darkadapted, mask=mask)
 
 ```
 
-**Fluorescence induction curve for Fm**
-
-![Screenshot](img/documentation_images/photosynthesis_reassign_frame_labels/da_induction.png)
-
 **Assign 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"
+pcv.params.debug = "plot"
 
-psl, psl_ind, psl_df = pcv.photosynthesis.reassign_frame_labels(ps_da=ps.lightadapted, mask=mask)
+psl = pcv.photosynthesis.reassign_frame_labels(ps_da=ps.lightadapted, mask=mask)
 
 ```
 
-**Fluorescence induction curve for Fm**
-
-![Screenshot](img/documentation_images/photosynthesis_reassign_frame_labels/la_induction.png)
-
 **Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/photosynthesis/reassign_frame_labels.py)

docs/print_image.md

@@ -2,9 +2,9 @@
 
 Write image to the file specified. This is a wrapper for the OpenCV function [imwrite](http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html)
 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.grayscale](analyze_grayscale.md), 
+and plotnine ggplots and altair charts (like the histograms returned in [pcv.analyze.grayscale](analyze_grayscale.md), 
 [pcv.analyze.color](analyze_color2.md), [pcv.visualize.histogram](visualize_histogram.md),
- and [pcv.photosynthesis.analyze_yii](photosynthesis_analyze_yii.md)).
+ and [pcv.analyze.yii](analyze_yii.md)).
 
 **plantcv.print_image**(*img, filename*)