Merge pull request #1346 from danforthcenter/release-4.0

Release 4.0
danforthcenter · Aug 21, 2023 · e3ccc42 · e3ccc42
2 parents ce8c0fa + aec06bc
commit e3ccc42
Show file tree

Hide file tree

Showing 544 changed files with 12,790 additions and 7,584 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -513,6 +513,17 @@
         "doc",
         "test"
       ]
+    },
+    {
+      "login": "dhiraj-ms",
+      "name": "Dhiraj Srivastava",
+      "avatar_url": "https://avatars.githubusercontent.com/u/39856917?v=4",
+      "profile": "https://github.com/dhiraj-ms",
+      "contributions": [
+        "code",
+        "doc",
+        "test"
+      ]
     }
   ],
   "contributorsPerLine": 7,

diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
@@ -31,7 +31,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest pytest-cov
+        pip install flake8 pytest pytest-cov ipython
         pip install -r requirements.txt
     - name: Lint with flake8
       run: |
@@ -42,7 +42,7 @@ jobs:
     - name: Test and generate coverage report
       # Run coverage analysis on pytest tests
       run: |
-        python setup.py install
+        pip install .
         py.test --cov-report=xml --cov=plantcv tests/
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3

diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml
@@ -23,7 +23,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest
+        pip install pytest pytest-cov ipython
         pip install -r requirements.txt
     - name: Cross-platform tests
       run: |

diff --git a/LICENSE b/LICENSE
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -2,6 +2,3 @@ include versioneer.py
 include plantcv/plantcv/_version.py
 include requirements.txt
 include LICENSE
-include plantcv-train.py
-include plantcv-utils.py
-include plantcv-workflow.py
diff --git a/README.md b/README.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,4 +1,21 @@
-# How to contribute
+# Table of Contents for Contibution
+1. [Overview of Contribution](#overview)
+2. [Creating Issues](#creatingissues)
+3. [Contributing Text or Code](#textcode)
+    * [Set-Up Development Environment](#devenvironmment)
+    * [Clone the Source Code](#clone)
+    * [Install PlantCV dependencies](#install)
+    * [Create a Branch](#branch)
+    * [Work and Commit](#commit)
+    * [Testing and documenting your code](#testdoc)
+    * [Publish and Create Pull Request](#publish)
+4. [Guidelines for New Features](#newfeatures)
+    * [New Function Style Guide](#style)
+5. [Instructions for Adding A New Tutorial](#tutorial)
+    * [Create Your Tutorial Repository](#repo)
+    * [Add Your Tutorial to the Gallery Wall](#gallery)
+
+## Overview Of What To Contribute <a name="overview"></a>
 
 This document aims to give an overview of how to contribute to PlantCV.
 We encourage contributions in a variety of forms. There are
@@ -14,10 +31,11 @@ There are many ways to contribute:
 * Add unit tests
 * Revise existing code
 * Add or revise documentation
+* Add, update, or revise a use-case tutorial
 
 If you need any help, please contact us. 
 
-## Creating Issues
+## Creating Issues <a name="creatingissues"></a>
 
 - Make sure you have a GitHub account.
 - Search GitHub and Google to see if your issue has already been reported
@@ -27,21 +45,19 @@ If you need any help, please contact us.
 	- Make sure you fill in the earliest version that you know has the issue.
 	- Where applicable, provide the full workflow prior to the error and the image getting analyzed. 
 
-## Contributing Text or Code
-
-### Overview
+## Contributing Text Or Code <a name="textcode"></a>
 
 When you add a significant **new feature**, please create an issue
 first, to allow others to comment and give feedback. 
 
-When you have created a new feature or other changes to existing
+**Adding Or Changing Code** When you have created a new feature or other changes to existing
 code, create a 'pull request'.
 
-**Branching and Pull Requests**: All contributors to PlantCV code or documentation are required to use the 
+**Branching And Pull Requests**: All contributors to PlantCV code or documentation are required to use the 
 *feature branch workflow* (below) in order to allow pull
 requests, automated testing, and code review.
 
-### Setting up a development environment
+### Setting Up A Development Environment <a name="devenvironmment"></a>
 
 !!! note
     Before setting up a development environment, choose between one of two methods for working with the PlantCV
@@ -50,18 +66,18 @@ requests, automated testing, and code review.
     request to be added as a collaborator on the PlantCV repository so that you can work with it directly instead of
     having to manage a separate repository.
 
-#### Clone the source code from GitHub
+#### Clone The Source Code From GitHub <a name="clone"></a>
 
 After choosing a method above for accessing PlantCV source code, create a clone of the source code GitHub repository
 using one of the methods described in the 
 [GitHub cloning a repository guide](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository).
 
-#### Install PlantCV dependencies
+#### Install PlantCV Dependencies <a name="install"></a>
 
 We recommend using `conda` to set up a virtual environment for developing PlantCV. Instructions can be found in the
 [installation documentation](installation.md#installation-from-the-source-code).
 
-#### Create a branch to do your work
+#### Create A Branch To Do Your Work <a name="branch"></a>
 
 The PlantCV default branch is protected and does not allow direct modification. A better practice is to 
 [create a branch](https://docs.github.com/en/free-pro-team@latest/desktop/contributing-and-collaborating-using-github-desktop/managing-branches)
@@ -70,12 +86,12 @@ number. This makes it easier to find out the issue you are trying to solve and h
 the branch. Calling a branch my-work is confusing. Names of branch can not have a space, and should be replaced with 
 a hyphen.
 
-#### Work and commit
+#### Work And Commit <a name="commit"></a>
 
 Do your work and commit as you see fit to check your work into your branch. Descriptive commit messages and 
 descriptions are helpful for understanding the purpose of changes.
 
-#### Testing and documenting your code
+#### Testing And Documenting Your Code <a name="testdoc"></a>
 
 In addition to adding a new feature, test your code thoroughly:
 
@@ -87,18 +103,18 @@ the coverage the more likely we are to catch problematic pull requests). To incl
 tests (to make sure they aren't broken by future pull requests) we need a 'unit test' or set of 'unit tests' (if you 
 need more than one test to cover function options).
 
-Existing unit tests can be found in `tests/tests.py` as examples.
-The data to support unit tests can be found in the `tests/*data/` directories.
+Existing unit tests can be found in `tests/` as examples.
+The data to support unit tests can be found in the `tests/testdata/` directory.
 
-If you are updating existing code, make sure that the `test.py`
-script passes on the function you modified. Testing locally can be done with pytest:
+If you are updating existing code, make sure that the test(s) pass on the function you modified.
+Testing locally can be done with pytest:
 
 ```bash
-pytest tests/tests.py
+py.test --cov=plantcv
 
 # Or you can just run a subset of tests to save time
 # This will run all tests with "analyze" in the test name 
-pytest tests/tests.py -k analyze
+py.test --cov=plantcv -k analyze
 
 ```
 
@@ -108,11 +124,11 @@ be added to the `mkdocs.yml` file. You can test that your new documentation can
 mkdocs from the root of your local plantcv repository.
 
 ```bash
-mkdocs build --theme readthedocs --site-dir _site
+mkdocs serve --theme readthedocs
 
 ```
 
-#### Publish your branch to GitHub and create a Pull Request
+#### Publish Your Branch To GitHub And Create A Pull Request <a name="publish"></a>
 
 [Publishing your branch](https://docs.github.com/en/free-pro-team@latest/desktop/contributing-and-collaborating-using-github-desktop/managing-branches#publishing-a-branch)
 to GitHub will make it available for creating a pull request between the updates and the default branch of PlantCV.
@@ -128,7 +144,7 @@ will automatically update when the branch is updated. Once tests pass, coverage
 review is approved, the branch will be merged with the default branch and the updates are now part of the latest
 version of PlantCV!
 
-### Guidelines for adding new features
+### Guidelines For Adding New Features <a name="newfeatures"></a>
 
 In general, new contributions to PlantCV should benefit multiple users
 and extend the image processing or trait analysis power of PlantCV. 
@@ -147,7 +163,7 @@ We do hope that if you are contributing new methods to PlantCV, you are also con
 tests for your functions (described below), because you understand your code/functionality best. If you have questions 
 or need help don't hesitate to ask [here](https://github.com/danforthcenter/plantcv/issues).
 
-#### New function style guide
+#### New function Style Guide <a name="styleguide"></a>
 
 Include commenting whenever possible.
 
@@ -263,6 +279,44 @@ def new_function_calling_plantcv(img):
 
 ```
 
+### Instructions for Adding A New Tutorial <a name="tutorial"></a>
+
+We are always looking for new examples of how people are applying 
+PlantCV to their research. You can send us a Jupyter Notebook and any required sample data or
+you can directly contrubute your tutorial. These instructions also apply to updating existing tutorials
+that might break wth new versions of PlantCV.
+
+#### Create Your Tutorial Repository <a name="repo"></a>
+
+1. Create a new repository on GitHub (Please consider creating your repo within an instituional account rather than a personal account e.g. Danforth Center). The name should start with plantcv-tutorial. When you make this repo you can use the option to import the tutorial template from `https://github.com/danforthcenter/plantcv-tutorial-template`
+
+2. If you don't import the tutorial template when you make your repo intitally you can clone the [tutorial template repository](https://github.com/danforthcenter/plantcv-tutorial-template) and copy the files and folders from the template repository to your tutorial repository
+
+3. Update the `README` and `index.ipynb` files with your tutorial content, including data (make sure you are updating or using the correct documentation branch, e.g. release-4.0)
+
+4. Add an image called `tutorial_card.png` to the repo, this will be used on the gallery webpage. The image should be approximately square and have a width of 200px.
+
+5. Follow the instructions to create a Binder button in the readme
+
+6. Commit the changes to your tutorial github repository
+
+7. Go to your repo online and test the 'Launch Binder' button for your repo
+
+#### Add Your Tutorial To the PlantCV Tutorial Gallery <a name="gallery"></a>
+
+1. In your PlantCV repo make a new branch (make sure your branch is based off the version you are working on e.g. release-4.0)
+
+2. Go to `/plantcv/docs/tutorials.md`, add a section for your new tutorial or update the binder links and link to your tutorial wall image
+
+3. Either go to `/plantcv/docs/tutorials/'yourtutorialname'` and update the binder links and nb viewer links for your tutorial or go to `/plantcv/docs/tutorials/`
+and add a doc with your tutorial name (use an exisiting tutorial as an example)
+
+4. While in your plantcv directory check the build of the documentation on the command line by the command: 
+ ```
+ mkdocs serve --theme readthedocs
+```
+5. If everything looks okay then commit changes and make a pull request (make sure that pull request is for the for version you are working on).
+
 ### Thanks
 
 Parts of this contribution guide are based on the

diff --git a/docs/Points.md b/docs/Points.md
@@ -0,0 +1,47 @@
+## Interactive Point Annotation Tool
+
+Using [Jupyter Notebooks](jupyter.md) it is possible to interactively click to collect coordinates from an image, which can be used in various downstream applications. Left click on the image to collect a point. Right click removes the
+closest collected point.
+
+**plantcv.Points**(*img, figsize=(12, 6)*)
+
+**returns** interactive image class
+
+- **Parameters:**
+    - img - Image data
+    - figsize - Interactive plot figure size (default = (12,6))
+
+- **Attributes:**
+    - points - Coordinates (x,y) of the collected points as a list of tuples
+
+- **Context:**
+    - Used to define a list of coordinates of interest.
+    - For example the [`pcv.roi.custom`](roi_custom.md) function defines a polygon Region of Interest based on a list of vertices, which can be labor intensive to define but is streamlined with the ability to click for point collection.
+    - The list of vertices output has also shown to be helpful while using [pcv.roi.multi](roi_multi.md) in cases where centers are defined with a custom list of vertices.    
+- **Example use:**
+    - Below
+
+
+```python
+from plantcv import plantcv as pcv
+
+# Create an instance of the Points class
+marker = pcv.Points(img=img, figsize=(12,6))
+
+# Click on the plotted image to collect coordinates
+
+# Use the identified coordinates to create a custom polygon ROI
+roi_contour, roi_hierarchy = pcv.roi.custom(img=img, vertices=marker.points)
+
+```
+
+**Selecting Coordinates**
+
+![screen-gif](img/documentation_images/annotate_Points/custom_roi.gif)
+
+**Resulting ROI**
+
+![Screenshot](img/documentation_images/annotate_Points/custom_roi.jpg)
+
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/classes.py)
diff --git a/docs/acute_vertex.md b/docs/acute_vertex.md
diff --git a/docs/analysis_approach.md b/docs/analysis_approach.md
@@ -42,7 +42,7 @@ to demonstrate how modules can be used. Keep in mind that modules can be linked
 configurations to meet image processing goals so the tutorials simply examples of a few approaches:
 
 *  [VIS Image Workflow](tutorials/vis_tutorial.md)
-*  [NIR Image Workflow](tutorials/nir_tutorial.md)
+*  [Grayscale Image processing](tutorials/grayscale_tutorial.md)
 *  [PSII Workflow](tutorials/psII_tutorial.md)
 *  [VIS / NIR Dual Workflow](tutorials/vis_nir_tutorial.md)
 *  [Multi Plant Tutorial](tutorials/multi-plant_tutorial.md)
@@ -97,16 +97,13 @@ likely be some 'noise' (non-target-object spots) in the image. Those can be fill
 #####Region of Interest
 
 *  To further isolate an object from surrounding background a region of interest can be used to select the region of 
-the image that contains the target object. To do this you first [detect all the objects](find_objects.md) in the image, 
-then define the [region of interest](roi_rectangle.md), then determine if the objects are  within, touching, or outside of 
-the region of interest with the [`roi_objects` function](roi_objects.md).
+the image that contains the target object. To do this you first define the [region of interest](roi_rectangle.md), then filter 
+the objects that are  within, touching, or outside of the region of interest with the [`roi.filter` function](roi_filter.md).
 
 #####Connecting Objects or Splitting Objects
 
 *  Once the target object or objects are segmented you then need to decide if it is desirable to connect or split the 
 objects.
-*  Even if there is a single plant in an image it may be detected as multiple objects, in which case it may need to be
-joined or composed together using the [object composition function](object_composition.md).
 *  If there are multiple plants in an object and you would like to analyze them individually (get shape parameters for 
 each plant for example) then there are functions in PlantCV to split the image apart so there is a single target object 
 in each sub-image. For more information on this process see the [Multi Plant Tutorial](tutorials/multi-plant_tutorial.md). 
@@ -115,13 +112,14 @@ in each sub-image. For more information on this process see the [Multi Plant Tut
 
 These are the general categories of object analysis that are available in PlantCV  
 
-*  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.
+*  Object shape parameters: see the [analyze.size](analyze_size.md), [analyze.bound_horizontal](analyze_bound_horizontal2.md),
+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.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 index](analyze_index.md) functions.
+*  Object hyperspectral parameters: see the [analyze.spectral_reflectance](analyze_spectral_reflectance.md) and [analyze.spectral_index](analyze_spectral_index.md) functions.
 *  Morphological parameters: see the [morphology tutorial](tutorials/morphology_tutorial.md) for examples of characteristics such as stem height,
 leaf length, and leaf angle.