Merge branch '4.x' into add_img_registration

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,3 +15,14 @@ Reference associated issue numbers. Does this pull request close any issues?
 
 **Additional context**
 Add any other context about the problem here.
+
+**For the reviewer**
+See [this page](https://plantcv.readthedocs.io/en/stable/pr_review_process/) for instructions on how to review the pull request.
+- [ ] PR functionality reviewed in a Jupyter Notebook
+- [ ] All tests pass
+- [ ] Test coverage remains 100%
+- [ ] Documentation tested
+- [ ] New documentation pages added to `plantcv/mkdocs.yml`
+- [ ] Changes to function input/output signatures added to `updating.md`
+- [ ] Code reviewed
+- [ ] PR approved

docs/hyperspectral_rot90.md

@@ -0,0 +1,38 @@
+## Rotate Hyperspectral Datacubes 
+
+This function rotates a hyperspectral datacube counterclockwise in increments of 90 degrees.  The input and output is a [`Spectral_data` class](Spectral_data.md) 
+instance created while reading in with [`pcv.readimage`](read_image.md) with `mode='envi'`. This function is similar to the [`pcv.rotate`](rotate2.md) functions
+but is specifically suitable for HSI image analysis. 
+
+**plantcv.hyperspectral.rot90**(*spectral_data, k*)
+
+**returns** rot_hsi (instance of the `Spectral_data` class)
+
+- **Parameters:**
+    - spectral_data      - Hyperspectral data instance
+    - k                  - Number of times the array is rotated by 90 degrees
+
+
+- **Example use:**
+    - Below
+
+
+
+```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 = "plot"
+
+# Rotate 90 degrees counterclockwise 
+rot_hsi = pcv.hyperspectral.rot90(spectral_data=spectral_array_obj, k=1)
+
+# Rotate 180 degrees
+upside_down_hsi = pcv.hyperspectral.rot90(spectral_data=spectral_array_obj, k=2)
+
+```
+
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/hyperspectral/rot90.py)

docs/params.md

@@ -25,15 +25,15 @@ Attributes are accessed as plantcv.params.*attribute*.
  [plantcv.morphology.find_tips](find_tips.md), [plantcv.morphology.segment_skeleton](segment_skeleton.md), [plantcv.morphology.segment_tangent_angle](segment_tangent_angle.md),
  [plantcv.morphology.segment_id](segment_id.md), and every region of interest function. Default = 5. 
 
-**dpi**: Dots per inch for plotting debugging images. 
+**dpi**: Dots per inch for plotting debugging images. Default = 100.
 
 **text_size**: Size of the text for labels in debugging plots created by [segment_angle](segment_angle.md), [segment_curvature](segment_curvature.md), [segment_euclidean_length](segment_euclidean_length.md),
 [segment_id](segment_id.md), [segment_insertion_angle](segment_insertion_angle.md), [segment_path_length](segment_pathlength.md), and [segment_tangent_angle](segment_tangent_angle.md) from
-the morphology sub-package. 
+the morphology sub-package. Default = 0.55.
 
 **text_thickness**: Thickness of the text for labels in debugging plots created by [segment_angle](segment_angle.md), [segment_curvature](segment_curvature.md), [segment_euclidean_length](segment_euclidean_length.md),
 [segment_id](segment_id.md), [segment_insertion_angle](segment_insertion_angle.md), [segment_path_length](segment_pathlength.md), and [segment_tangent_angle](segment_tangent_angle.md) from
-the morphology sub-package. 
+the morphology sub-package. Default = 2.
 
 **marker_size**: Size of markers in debugging plots created by [plantcv.transform.warp](transform_warp.md). Default = 60.
 

docs/pr_review_process.md

@@ -0,0 +1,83 @@
+# Pull Request Review Process
+
+### Pull Request Author Guidelines
+
+1. PRs (Pull Requests) should be modular and as targeted as possible.
+2. PRs for new features should focus on a minimum viable product. Embellishments can be added in additional PRs.
+3. PRs should not contain unrelated changes as much as possible. Open a new PR for unrelated changes.
+4. Commits for PRs should be succinct but descriptive. Try to avoid trivial “update file.py” type commit messages.
+5. When a PR is ready for review, apply the “ready to review” label. At this point, additional changes should only be made if necessary or as part of the review. Let the team know it’s ready so someone can volunteer to review it.
+
+### Overview
+
+!!! note
+    The steps below do not necessarily need to be followed precisely in this order. Not all PRs will require all steps and some will not require an in-depth review at all (e.g., minor documentation updates).
+
+### Step 0: Set up a local PlantCV environment for the branch being reviewed
+
+1. Read through the steps of the [contributing guide](CONTRIBUTING.md).
+2. Email [email protected] to get added as a contributor.
+3. [Install PlantCV from the source code](installation.md#installation-from-the-source-code)
+4. Activate the plantcv environment, then change the current directory to the location where plantcv is installed.  Then, run `git checkout <pull-request-branch>` to navigate to the branch to be reviewed.
+
+### Step 1: Familiarize yourself with the PR
+
+Before starting the review it is convenient to understand the type of update and/or the intended functionality.  
+
+1. Inspect the files changed. 
+2. Read the updated documentation. To compile the documentation locally, run: `mkdocs serve --theme readthedocs` in a local terminal with an activated PlantCV environment (Testing the documentation is done in step 4). 
+
+### Step 2: Prepare materials for the review
+
+1. Maintain a shared team directory for reviews (data and notebooks) in the PlantCV Google Drive. Email [email protected] from a Gmail account to have the team share access to this Google Drive.
+2. Find appropriate sample data (either already in the shared directory or new data), ideally not data used by the PR author.
+3. Update your local development environment to use the PR branch.
+4. Create a new Jupyter notebook named `pr<num>_<short description>.ipynb`
+
+### Step 3: Review the PR functionality
+
+Read the PR documentation and use your intuition to run relevant parts of PlantCV to test the PR code. For example, test upstream and downstream functionality to ensure the new function works well with other steps in a workflow. Try more than one data type if a function works on both RGB and grayscale. Potential findings to report to the PR author and/or to propose fixes for:
+
+1. **Errors**: the code does not work as written or does not function as intended (on new data for example).
+2. **Process**: in using the code, you think the process can be simplified or made clearer (e.g., fewer inputs, renamed arguments, etc.).
+3. **Documentation**: both the documentation and docstrings should match the code in terms of syntax and process.
+
+Iterate as needed.
+
+### Step 4: Review the tests
+
+1. Do all tests pass?
+    1. Running relevant tests locally: `py.test --cov=plantcv -k test_name_or_keywords` in a local terminal with an activated PlantCV environment
+2. Does coverage remain at 100%?
+3. Do any new or modified tests accurately test the PR code?
+
+Propose updates as needed.
+
+### Step 5: Test the documentation
+
+Reviewing the documentation code is important, but compiling the documentation locally ensures that the resulting pages are rendered correctly. The easiest way to view the documentation live on your local machine is to run: `mkdocs serve --theme readthedocs` in a local terminal with an activated PlantCV environment
+
+Some common oversights that are hard to see in the code but easy to detect in the compiled documentation:
+
+1. New pages are not added to the table of contents `plantcv/mkdocs.yml` (mkdocs will display a warning when you run the command above).
+2. Typos in page or image filenames (mkdocs will often display a warning, or the image may appear as a broken link).
+3. Typos in formatting markup lead to incorrectly displayed styling (e.g., not closing bold or italics, not having a blank line before a bulleted or numbered list, etc.).
+4. Changes to function input/output signatures or new functions should be added to updating.md.
+5. Link out to source code at the end of a documentation page.
+
+### Step 6: Review the code
+
+Once the PR is working as intended, review the code itself for potential improvements. Some common types of improvements to suggest:
+
+1. **Uniform style (linting)**: Most IDEs, including PyCharm and VScode, will indicate when the code does not match the community style guides laid out in PEP8. The command-line tool `flake8` can also be used if an IDE that supports these checks cannot be used. A report from deepsource.io is also generated automatically for each PR.
+2. **Code simplification**: Any reorganization that makes the code more succinct, readable, maintainable, etc. In particular, complex, nested logical blocks and for loops increase code complexity (and testing demand). The deepsource.io report may also included automated suggestions for code simplification. 
+3. **Algorithmic improvement**: Could potentially be an alternate approach that is significantly faster or more user-friendly.
+4. **Scope**: Check any new code and test data in the `plantcv/tests` module (no need to fix out-of-scope linting issues).
+5. **Documentation**: The documentation is more flexible, but try to avoid very long lines. Markdown will automatically connect consecutive lines that do not have a blank line between them. Crop down images in documentation. In general, resizing such that the image width is equal to 400px will result in a documentation page that is still mobile friendly.
+6. **Unnecessary New Test Data**: If new test data was added, check if an existing test data could be used to save memory.
+
+Communicate via GitHub with PR author(s) and directly contribute changes to the PR branch as appropriate until it is ready to merge.
+
+### Step 7: Approve the PR
+
+Once you and the PR author have refined the PR and it is ready to merge, the PR can be approved. It’s important that the PR not be approved until it is actually ready to merge. Please add the name of the Jupyter notebook used for review, in the shared directory (but not a link to it) to the PR approval.

docs/updating.md

@@ -385,6 +385,16 @@ pages for more details on the input and output variable types.
 * post v3.7: index_array = **plantcv.hyperspectral.extract_index**(*array, index="NDVI", distance=20*)
 * post v3.8: DEPRECATED see plantcv.spectral_index
 
+#### plantcv.hyperspectral.rot90
+
+* pre v4.x: NA
+* post v4.x: rot_hsi = **plantcv.hyperspectral.rot90**(*spectral_data, k*)
+
+#### plantcv.hyperspectral.write_data
+
+* pre v4.0: NA
+* post v4.0: **plantcv.hyperspectral.write_data**(*filename, spectral_data*)
+
 #### plantcv.image_add
 
 * pre v3.0dev2: device, added_img = **plantcv.image_add**(*img1, img2, device, debug=None*)
@@ -1034,7 +1044,7 @@ pages for more details on the input and output variable types.
 #### plantcv.visualize.colorspaces
 
 * pre v3.8: NA
-* post v3.8: plotting_img = pcv.visualize.colorspaces(rgb_img)
+* post v3.8: plotting_img = pcv.visualize.colorspaces(rgb_img, original_img=True)
 
 #### plantcv.visualize.histogram
 

docs/visualize_colorspace.md

@@ -2,12 +2,13 @@
 
 This is a plotting method used to examine all potential colorspaces from available PlantCV functions.
 
-**plantcv.visualize.colorspaces**(*rgb_img*)
+**plantcv.visualize.colorspaces**(*rgb_img, originial_img=True*)
 
 **returns** plotting_img
 
 - **Parameters:**
     - rgb_img - RGB image data, the original image for analysis.
+    - original_img - Whether or not to include the original image the the debugging plot (default original_img=True)
 
 - **Example use:**
     - Below

docs/write_data.md

@@ -0,0 +1,41 @@
+## Write data
+
+Write a hyperspectral image in ENVI format to the specified file.
+It creates a text header file with extension .hdr and a binary file with
+extension .raw.  This function only supports Band-Interleaved-by-Line (BIL)
+interleave.
+
+**plantcv.hyperspectral.write_data**(*filename, spectral_data*):
+
+
+- **Parameters:**
+    - filename- desired name of the hyperspectral image file. The extensions are ignored and .hdr and .raw are used.
+    - spectral_data- Hyperspectral data object
+
+- **Context:**
+    - Used to save a modified hyperspectral image
+
+- **Example use:**
+
+```python
+from plantcv import plantcv as pcv
+
+modified_spectral = pcv.Spectral_data(array_data=modified_array_data,
+                          max_wavelength=list(source_spectral.wavelength_dict.keys())[-1],
+                          min_wavelength=list(source_spectral.wavelength_dict.keys())[0],
+                          max_value=float(np.amax(modified_array_data)),
+                          min_value=float(np.amin(modified_array_data)),
+                          d_type=modified_array_data.dtype,
+                          wavelength_dict=source_spectral.wavelength_dict,
+                          samples=modified_array_data.shape[1],
+                          lines=modified_array_data.shape[0], interleave='bil',
+                          wavelength_units=source_spectral.wavelength_units,
+                          array_type="datacube",
+                          pseudo_rgb=None,
+                          filename=source_spectral.filename,
+                          default_bands=None)
+
+pcv.hyperspectral.write_data('test-hyperspectral', modified_spectral)
+```
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/hyperspectral/write_data.py)

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
     - 'Contributing to PlantCV': CONTRIBUTING.md
     - 'Code of Conduct': CODE_OF_CONDUCT.md
     - 'Adding/Editing Documentation': documentation.md
+    - 'Pull Request Review Process' : pr_review_process.md
   - "Tutorials": tutorials.md
   - 'Workflow Parallelization': pipeline_parallel.md
   - 'Exporting Data': db-exporter.md
@@ -69,7 +70,9 @@ nav:
           - 'Calibrate': calibrate.md
           - 'Spectral Index': spectral_index.md
           - 'Extract wavelength': extract_wavelength.md
+          - 'Rotate Hyperspectral Datacubes ': hyperspectral_rot90.md
           - 'Spectral data objects': Spectral_data.md
+          - 'Write data': write_data.md
       - 'Image Add': image_add.md
       - 'Image Subtract': image_subtract.md
       - 'Image Fusion': image_fusion.md