From 07b9201260fadfcbdea439135bdcaf318778a677 Mon Sep 17 00:00:00 2001 From: Beth Cimini Date: Sat, 22 Aug 2020 20:49:54 +0000 Subject: [PATCH] Update the manual for 4.0.0 (#4160) * Add new modules, remove outdated one * Update objectprocessing.rst * Update CONTRIBUTING.md * add core, misc fixes * use new help file locations * indent * only image errors left * add CellProfiler3 paper * Remove outdated material * Remove outdated info * New texture stuff --- CONTRIBUTING.md | 13 +++++++++++++ cellprofiler/data/help/legacy_matlab_image.rst | 14 +++++++------- cellprofiler/data/help/other_batch.rst | 11 ++++------- cellprofiler/data/help/output_measurements.rst | 12 ++++++++---- cellprofiler/data/help/pipelines_building.rst | 3 +-- cellprofiler/modules/closing.py | 4 +--- cellprofiler/modules/dilateimage.py | 4 +--- cellprofiler/modules/erodeimage.py | 6 ++---- cellprofiler/modules/medialaxis.py | 3 +-- cellprofiler/modules/morphologicalskeleton.py | 4 +--- cellprofiler/modules/opening.py | 4 +--- cellprofiler/modules/reducenoise.py | 3 +-- docs/source/conf.py | 1 + docs/source/index.rst | 18 +++++++++++++++++- docs/source/modules/advanced.rst | 18 ++++++++---------- docs/source/modules/imageprocessing.rst | 2 +- docs/source/modules/objectprocessing.rst | 10 +++++++++- 17 files changed, 77 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a5ed7c42a..d2ea90e8c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,9 @@ This document provides guidelines for contributing to CellProfiler. You'll find We'd like to ensure this document is always accurate and understandable. Please [file an issue](https://github.com/CellProfiler/CellProfiler/issues/new) if any information is missing, unclear, or incorrect. +You may also check out our [YouTube tutorial](https://youtu.be/fgF_YueM1b8) for a discussion of many of these issues and demonstration of editing and creating +modules. + ## Creating an Issue The CellProfiler team uses [GitHub issues](https://github.com/CellProfiler/CellProfiler/issues) to track upcoming and ongoing work. Examples of issues are: @@ -146,6 +149,16 @@ In this section we provide a general outline of the process for submitting chang ``` Your master branch now includes your change. Congratulations on a successful contribution! + +## Creating entirely new modules + +We love when our users create entirely new functionalities that have never existed in CellProfiler before! If you think your new module is useful to the +community, we invite you to contribute it as a plugin to the [CellProfiler-plugins](https://github.com/CellProfiler/CellProfiler-plugins) repository. +Contributed plugins may be moved into the main CellProfiler program (with author permission), depending on a number of factors including (but not limited to) +1. Additional complexity and/or package dependencies added to the code +1. Broad usefulness to the community +1. Conflicts or overlap with other modules +1. Our team's bandwidth to commit to maintaining your module in the future ## Style Guide diff --git a/cellprofiler/data/help/legacy_matlab_image.rst b/cellprofiler/data/help/legacy_matlab_image.rst index 8289cf24ba..45cee6ad56 100644 --- a/cellprofiler/data/help/legacy_matlab_image.rst +++ b/cellprofiler/data/help/legacy_matlab_image.rst @@ -7,11 +7,11 @@ illumination correction functions generated by **CorrectIlluminationCalculate**. These images could be loaded and applied to other pipelines using **CorrectIlluminationApply**. -This version of CellProfiler no longer supports exporting MATLAB format -images. Instead, the recommended image format for illumination correction -functions is NumPy (.npy). Loading MATLAB format images is deprecated and -will be removed in a future version of CellProfiler. To ensure compatibility -with future versions of CellProfiler you can convert your .mat files to .npy -files via **SaveImages** using this version of CellProfiler. +This version of CellProfiler no longer supports reading or exporting +MATLAB format images. Instead, the recommended image format for illumination +correction functions is NumPy (.npy). Loading MATLAB format images can only be +done in CellProfiler versions through 3.1.9. To ensure compatibility with future +versions of CellProfiler you can convert your .mat files to .npy +files via **SaveImages** using any 3.X build of CellProfiler. -See **SaveImages** for more details on saving NumPy format images. +See **SaveImages** for more details on saving NumPy format images. \ No newline at end of file diff --git a/cellprofiler/data/help/other_batch.rst b/cellprofiler/data/help/other_batch.rst index 4d2afd7f64..6027400a35 100644 --- a/cellprofiler/data/help/other_batch.rst +++ b/cellprofiler/data/help/other_batch.rst @@ -68,10 +68,9 @@ cluster. processing large batches of images, you may also consider adding **ExportToDatabase** to your pipeline, after your measurement modules but before the CreateBatchFiles module. This module will export your - data either directly to a MySQL/SQLite database or into a set of - comma-separated files (CSV) along with a script to import your data - into a MySQL database. Please refer to the help for these modules in - order learn more about which settings are appropriate. + data either directly to a MySQL or SQLite database. Please refer to + the help for these modules in order learn more about which settings + are appropriate. #. *Run the pipeline to create a batch file.* Click the *Analyze images* button and the analysis will begin processing locally. Do not be surprised if this initial step takes a while: CellProfiler must @@ -94,7 +93,7 @@ cluster. :: ./python -m cellprofiler -p /Batch_data.h5 \\ - -c -r -b \\ + -c -r \\ -f \\ -l @@ -109,8 +108,6 @@ cluster. - ``-c``: Run “headless”, i.e., without the GUI - ``-r``: Run the pipeline specified on startup, which is contained in the batch file. - - ``-b``: Do not build extensions, since by this point, they should - already be built. - ``-f ``: Start processing with the image set specified, - ``-l ``: Finish processing with the image diff --git a/cellprofiler/data/help/output_measurements.rst b/cellprofiler/data/help/output_measurements.rst index 6e5f45033a..c0219be214 100644 --- a/cellprofiler/data/help/output_measurements.rst +++ b/cellprofiler/data/help/output_measurements.rst @@ -51,14 +51,16 @@ Below is the description for each of the terms: - Measurements from *Intensity*, *Granularity*, *Children*, *RadialDistribution*, *Parent* and *AreaOccupied* categories will have an associated image as the Parameter. - - *Measurements from the *Neighbors* and *Texture* category will - have a spatial scale ``Parameter``.* + - Measurements from the *Neighbors* and *Texture* category will + have a spatial scale ``Parameter``. - Measurements from the *Texture* and *RadialDistribution* categories will have both a spatial scale and an image ``Parameter``. + - Measurements from the *Texture* category will have a spacial + scale, image, and grayscale count ``Parameter``. As an example, consider a measurement specified as -``Nuclei_Texture_DifferenceVariance_ER_3``: +``Nuclei_Texture_DifferenceVariance_ER_3_256``: - ``MeasurementType`` is “Nuclei,” the name given to the detected objects by the user. @@ -66,12 +68,14 @@ As an example, consider a measurement specified as **MeasureTexture** produced the measurements. - ``SpecificFeatureName`` is “DifferenceVariance,” which is one of the many texture measurements made by the **MeasureTexture** module. -- There are two ``Parameters``, the first of which is “ER”. “ER” is the +- There are three ``Parameters``, the first of which is “ER”. “ER” is the user-provided name of the image in which this texture measurement was made. - The second ``Parameter`` is “3”, which is the spatial scale at which this texture measurement was made, according to the user-provided settings for the module. +- The final ``Parameter`` is "256", which is the number of gray levels + used in calculating the texture. See also the *Available measurements* heading under the main help for many of the modules, as well as **ExportToSpreadsheet** and diff --git a/cellprofiler/data/help/pipelines_building.rst b/cellprofiler/data/help/pipelines_building.rst index 4a1f3cd569..6b434c2f2d 100644 --- a/cellprofiler/data/help/pipelines_building.rst +++ b/cellprofiler/data/help/pipelines_building.rst @@ -111,8 +111,7 @@ panel* (located on the left-hand side of the CellProfiler window). time remaining to process the full image set. At the end of each cycle: - - - If you are creating a MATLAB or HDF5 output file, CellProfiler saves the measurements in the output file. + - If you are using the **ExportToDatabase** module, CellProfiler saves the measurements in the output database. - If you are using the **ExportToSpreadsheet** module, CellProfiler saves the measurements *into a diff --git a/cellprofiler/modules/closing.py b/cellprofiler/modules/closing.py index d8e11332c1..0ccbd22056 100644 --- a/cellprofiler/modules/closing.py +++ b/cellprofiler/modules/closing.py @@ -4,7 +4,7 @@ **Closing** is the erosion of the dilation of an image. It’s used to remove pepper noise (small dark spots) and connect small bright cracks. -See `this tutorial`_ for more information. +See `this tutorial `__ for more information. | @@ -14,8 +14,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: https://scikit-image.org/docs/dev/auto_examples/applications/plot_morphology.html#closing - """ import numpy diff --git a/cellprofiler/modules/dilateimage.py b/cellprofiler/modules/dilateimage.py index 110b208a79..90a9cbe739 100644 --- a/cellprofiler/modules/dilateimage.py +++ b/cellprofiler/modules/dilateimage.py @@ -2,7 +2,7 @@ DilateImage =========== -**DilateImage** expands bright shapes in an image. See `this tutorial`_ for more information. +**DilateImage** expands bright shapes in an image. See `this tutorial `__ for more information. | @@ -12,8 +12,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: https://scikit-image.org/docs/dev/auto_examples/applications/plot_morphology.html#dilation - """ from cellprofiler_core.module import ImageProcessing diff --git a/cellprofiler/modules/erodeimage.py b/cellprofiler/modules/erodeimage.py index 74635dd313..66daad7370 100644 --- a/cellprofiler/modules/erodeimage.py +++ b/cellprofiler/modules/erodeimage.py @@ -2,9 +2,9 @@ """ ErodeImage -======= +========== -**ErodeImage** shrinks bright shapes in an image. See `this tutorial`_ for more information. +**ErodeImage** shrinks bright shapes in an image. See `this tutorial `__ for more information. | @@ -14,8 +14,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: https://scikit-image.org/docs/stable/auto_examples/applications/plot_morphology.html#erosion - """ from cellprofiler_core.module import ImageProcessing diff --git a/cellprofiler/modules/medialaxis.py b/cellprofiler/modules/medialaxis.py index e980861a70..3e673d87f3 100644 --- a/cellprofiler/modules/medialaxis.py +++ b/cellprofiler/modules/medialaxis.py @@ -5,7 +5,7 @@ **MedialAxis** computes the medial axis or topological skeleton of a binary image. Rather than by sequentially removing pixels as in **MorphologicalSkeleton**, the medial axis is computed based on the distance transform of the thresholded image (i.e., the distance each foreground pixel is -from a background pixel). See `this tutorial`_ for more information. +from a background pixel). See `this tutorial `__ for more information. | @@ -15,7 +15,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: http://scikit-image.org/docs/dev/auto_examples/edges/plot_skeleton.html """ import numpy diff --git a/cellprofiler/modules/morphologicalskeleton.py b/cellprofiler/modules/morphologicalskeleton.py index d92c78c13c..add7d0a207 100644 --- a/cellprofiler/modules/morphologicalskeleton.py +++ b/cellprofiler/modules/morphologicalskeleton.py @@ -2,7 +2,7 @@ MorphologicalSkeleton ===================== -**MorphologicalSkeleton** thins an image into a single-pixel wide skeleton. See `this tutorial`_ for more information. +**MorphologicalSkeleton** thins an image into a single-pixel wide skeleton. See `this tutorial `__ for more information. | @@ -12,8 +12,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: https://scikit-image.org/docs/0.14.x/auto_examples/xx_applications/plot_morphology.html#skeletonize - """ import skimage.morphology diff --git a/cellprofiler/modules/opening.py b/cellprofiler/modules/opening.py index 3bf98502b2..e74fe3a1b4 100644 --- a/cellprofiler/modules/opening.py +++ b/cellprofiler/modules/opening.py @@ -4,7 +4,7 @@ **Opening** is the dilation of the erosion of an image. It’s used to remove salt noise (small bright spots) and connect small dark cracks. -See `this tutorial`_ for more information. +See `this tutorial `__ for more information. | @@ -14,8 +14,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: https://scikit-image.org/docs/dev/auto_examples/applications/plot_morphology.html#opening - """ import numpy diff --git a/cellprofiler/modules/reducenoise.py b/cellprofiler/modules/reducenoise.py index 92415ce639..0f19cf1954 100644 --- a/cellprofiler/modules/reducenoise.py +++ b/cellprofiler/modules/reducenoise.py @@ -7,7 +7,7 @@ as in **GaussianFilter**, multiple neighborhoods are pooled together. The neighborhood pool is determined by scanning the image for regions similar to the area around the central pixel using a correlation metric and a cutoff value. -See `this tutorial`_ for more information. +See `this tutorial `__ for more information. | @@ -17,7 +17,6 @@ YES YES NO ============ ============ =============== -.. _this tutorial: http://scikit-image.org/docs/dev/auto_examples/filters/plot_nonlocal_means.html """ import skimage.restoration diff --git a/docs/source/conf.py b/docs/source/conf.py index 74b11369a3..c3cbad4b7a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,6 +22,7 @@ import sphinx_rtd_theme sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) +sys.path.insert(0,os.path.abspath(os.path.join("..","..","..","core"))) # -- General configuration ------------------------------------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index d3f81aeef8..15243e5c8b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -65,6 +65,11 @@ References For a full list of references, visit our `citation`_ page. +- McQuin C, Goodman A, Chernyshev V, Kamentsky L, Cimini BA, Karhohs KW, + Doan M, Ding L, Rafelski SM, Thirstrup D, Wiegraebe W. (2018) + "CellProfiler 3.0: Next-generation image processing for biology." + *PLoS biology* 16(7), e2005970 + (`link `__) - Carpenter AE, Jones TR, Lamprecht MR, Clarke C, Kang IH, Friman O, Guertin DA, Chang JH, Lindquist RA, Moffat J, Golland P, Sabatini DM (2006) “CellProfiler: image analysis software for identifying and @@ -212,7 +217,6 @@ in a future version of CellProfiler. :caption: Legacy Features :titlesonly: - help/legacy_load_modules help/legacy_matlab_image `(Jump to top)`_ @@ -220,3 +224,15 @@ in a future version of CellProfiler. :ref:`search` .. _(Jump to top): index.html# + +License +======= + +.. toctree:: + :caption: License + + modules/license + +:ref:`search` + +.. _(Jump to top): index.html# \ No newline at end of file diff --git a/docs/source/modules/advanced.rst b/docs/source/modules/advanced.rst index 06419ab1f8..3c4cb8fe5d 100644 --- a/docs/source/modules/advanced.rst +++ b/docs/source/modules/advanced.rst @@ -16,31 +16,33 @@ Advanced modules include computer vision algorithms. `(Jump to top)`_ -.. automodule:: cellprofiler.modules.erosion +.. automodule:: cellprofiler.modules.erodeimage `(Jump to top)`_ -.. automodule:: cellprofiler.modules.fillobjects +.. automodule:: cellprofiler.modules.erodeobjects `(Jump to top)`_ -.. automodule:: cellprofiler.modules.gaussianfilter + +.. automodule:: cellprofiler.modules.fillobjects `(Jump to top)`_ -.. automodule:: cellprofiler.modules.label +.. automodule:: cellprofiler.modules.gaussianfilter `(Jump to top)`_ + .. automodule:: cellprofiler.modules.matchtemplate `(Jump to top)`_ -.. automodule:: cellprofiler.modules.medianfilter +.. automodule:: cellprofiler.modules.medialaxis `(Jump to top)`_ -.. automodule:: cellprofiler.modules.medialaxis +.. automodule:: cellprofiler.modules.medianfilter `(Jump to top)`_ @@ -60,10 +62,6 @@ Advanced modules include computer vision algorithms. `(Jump to top)`_ -.. automodule:: cellprofiler.modules.removeobjectsbysize - -`(Jump to top)`_ - .. automodule:: cellprofiler.modules.shrinktoobjectcenters `(Jump to top)`_ diff --git a/docs/source/modules/imageprocessing.rst b/docs/source/modules/imageprocessing.rst index 396ca601d6..9c1b1be34d 100644 --- a/docs/source/modules/imageprocessing.rst +++ b/docs/source/modules/imageprocessing.rst @@ -4,7 +4,7 @@ Image Processing ---------------- Image Processing modules apply an operation to an image and output a new image. -.. automodule:: cellprofiler.modules.align +.. automodule:: cellprofiler_core.modules.align `(Jump to top)`_ diff --git a/docs/source/modules/objectprocessing.rst b/docs/source/modules/objectprocessing.rst index 3445857aa5..c0cc199846 100644 --- a/docs/source/modules/objectprocessing.rst +++ b/docs/source/modules/objectprocessing.rst @@ -9,6 +9,14 @@ have been identified in an image. `(Jump to top)`_ +.. automodule:: cellprofiler.modules.combineobjects + +`(Jump to top)`_ + +.. automodule:: cellprofiler.modules.convertimagetoobjects + +`(Jump to top)`_ + .. automodule:: cellprofiler.modules.convertobjectstoimage `(Jump to top)`_ @@ -65,4 +73,4 @@ have been identified in an image. `(Jump to top)`_ -.. _(Jump to top): objectprocessing.html# \ No newline at end of file +.. _(Jump to top): objectprocessing.html#