Skip to content

Commit

Permalink
deploy: e7eb64c
Browse files Browse the repository at this point in the history
  • Loading branch information
@MichaelSNelson
MichaelSNelson committed Oct 7, 2024
1 parent 643a457 commit 229ed6c
Show file tree
Hide file tree
Showing 13 changed files with 333 additions and 103 deletions.
28 changes: 19 additions & 9 deletions _sources/analysis_workflows/1_established_workflows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ TODO
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_key_settings.svg" width="50px"> &nbsp; Key settings
````{tab-set}
```{tab-item} Description
Key settings are specific settings of variable parameters that largely affect the outcome of the workflow when the settings are changed, for a given program and version. For example, the spot diameter setting in Trackmate is a key setting that may largely change the tracking results with a slightly different setting. The choice of algorithm for particle linking is also a key setting. If the exact same settings are used as the referenced workflow, it is possible to omit them, but writers should be aware that readers will be more likely to use and cite their work if they can utilize their protocol!
WARNING Users should be careful that the overall defaults have not been changed by an administrator, for example a single installation of Fiji used by multiple users may have left over settings changes (like "Invert") that significantly impact the analysis workflow.
Key settings are specific settings of variable parameters that significantly affect the outcome of the workflow when those settings are changed, and can be unique for a given program and version. For example, the spot diameter setting in Trackmate is a key setting that may change the tracking results with a slightly different setting. The choice of algorithm for particle linking is also a key setting. If the exact same settings are used as the referenced workflow, it is possible to omit them, but writers should be aware that readers will be more likely to use and cite their work if they can utilize their protocol! WARNING: Users should be careful that the overall defaults have not been changed by an administrator, for example a single installation of Fiji accessed by multiple users may have left over settings changes (like "Invert") that significantly impact an analysis workflow.
```
```{tab-item} Links
[Reproducible image handling and analysis](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7849301/)
Expand All @@ -46,7 +45,7 @@ TODO
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_roi.svg" width="50px"> &nbsp; Manual ROIs
````{tab-set}
```{tab-item} Description
If manualy annotated ROIs are used in the workflow, those ROIs should be saved as a separate file and uploaded as part of the workflow package. In ImageJ, manualy created ROIs can be stored in ROI manager and saved as a file via the menu associated with ROI Manager.
If manually annotated ROIs are used in the workflow, those ROIs should be saved as a separate file and uploaded as part of the workflow package. Without these ROIs included, manually selected areas prevent others from reproducing the workflow on their own.
```
```{tab-item} Links
[Measurements & regions of interest · Analyzing fluorescence microscopy images with ImageJ](https://petebankhead.gitbooks.io/imagej-intro/content/chapters/rois/rois.html#saving-rois)
Expand All @@ -59,10 +58,18 @@ If manualy annotated ROIs are used in the workflow, those ROIs should be saved a
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_version.svg" width="50px"> &nbsp; Exact version
````{tab-set}
```{tab-item} Description
If the workflow used is published with version tracked code in a public repository e.g. GitHub, the release date or the exact verion of the code should be present in the methods section or supplementary material section. If the workflow is from a commertial software package, the version of the package and the name of the worlflow must appear in the manuscript. If the workflow is only published as a supplementary material, cite that publication.
If the workflow used is published as a version tracked code in a public repository (e.g. GitHub), the release date or the exact version of the code should be present in the Methods section or supplementary material section. If the workflow is from a commercial software package, the version of the package and the name of the workflow must appear in the manuscript. If the workflow is only published as a supplementary material, cite that publication.
```
```{tab-item} Links
TODO
For example:
https://imagej.net/plugins/trackmate/tutorials/getting-started
Example references:
Ershov, D., Phan, M.-S., Pylvänäinen, J. W., Rigaud, S. U., Le Blanc, L., Charles-Orszag, A., … Tinevez, J.-Y. (2022). TrackMate 7: integrating state-of-the-art segmentation algorithms into tracking pipelines. Nature Methods, 19(7), 829–832. doi:10.1038/s41592-022-01507-1
Tinevez, J.-Y., Perry, N., Schindelin, J., Hoopes, G. M., Reynolds, G. D., Laplantine, E., … Eliceiri, K. W. (2017). TrackMate: An open and extensible platform for single-particle tracking. Methods, 115, 80–90. doi:10.1016/j.ymeth.2016.09.016
```
````
`````
Expand All @@ -89,7 +96,7 @@ https://doi.org/10.1242/jcs.254151
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_public_example.svg" width="50px"> &nbsp; Public example
````{tab-set}
```{tab-item} Description
TODO
Example data is required for testing the workflow and the outcome, for peers to study the behavior of the workflow and evaluate its scientific adequacy. Best is to provide this example data on a public repository.
```
```{tab-item} Links
TODO
Expand All @@ -105,10 +112,13 @@ TODO
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_screen_recording.svg" width="50px"> &nbsp; Document usage (e.g. screen recording or tutorial)
````{tab-set}
```{tab-item} Description
Including screengrabs of key steps in a pipeline, or if the option is available, a whole video (which could be a link to a hosted video, for example on YouTube or Google Drive) can make it far easier to reproduce an experiment, even a purely digital one. There are frequently steps or intermediate results experienced users take for granted, that may not be obvious to newer users of a given software or pipeline - these things can be captured in a full video recording of use but might be missed in a writeup.
Including screengrabs of key steps in a pipeline, or if the option is available, a whole video (which could be a link to a hosted video, for example on YouTube or Google Drive) can make it far easier to reproduce an experiment, even a digital one. There are frequently steps or intermediate results experienced users take for granted, that may not be obvious to newer users of a given software or pipeline - these things can be captured in a full video recording of use but might be missed in a writeup.
```
```{tab-item} Links
TODO
How to Screen Record on Your Mac (4 Options)| The TechSmith Blog
https://www.techsmith.com/blog/screen-record-mac/
Screen recording in Windows - https://www.tomshardware.com/how-to/screen-record-in-windows
```
````
`````
Expand All @@ -117,7 +127,7 @@ TODO
`````
````{tab-set}
```{tab-item} Description
The method reproducibility is best ensured with a workflow code included in a container e.g. Docker container, that allows the exact reproduction of the environment for running the workflow code together with the example data. The image of that container can be shared as the reproducible workflow. Otherwise, a publicly accessible exexutable environment e.g cloud hosted server can be prepared to let others to run the workflow code.
The method reproducibility is best ensured with a workflow code included in a container (e.g. Docker container) that allows the exact reproduction of the environment for running the workflow code together with the example data. The image of that container can be shared as the reproducible workflow. Otherwise, a publicly accessible executable environment (e.g. cloud hosted server) can be prepared to let others run the workflow code.
```
```{tab-item} Links
[Tutorial - PDF](https://fox.cs.vt.edu/talks/2020/JCDL%202020%20Reproducibility%20Tutorial.pdf)
Expand Down
53 changes: 42 additions & 11 deletions _sources/analysis_workflows/2_new_workflows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_cite.svg" width="50px"> &nbsp; Cite components & platform
````{tab-set}
```{tab-item} Description
All components (plugins or packages used in the workflow) should be cited. If a publication does not exist, the download URL and the author of the component can be added in the Methods section. The specific platform used for running the workflow code should also be cited, especially in the case of Apple computers with varying chipset options.
All components (plugins or packages used in the workflow) should be cited with the corresponding version. If publication does not exist, the download URL and the author of the component can be added in the methods section. The platform (including version) used for running the workflow code should also be cited, especially in the case of Apple computers with varying chipset options.
```
```{tab-item} Links
TODO
Expand All @@ -18,7 +18,7 @@ TODO
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_describe_sequence.svg" width="50px"> &nbsp; Describe sequence
````{tab-set}
```{tab-item} Description
The outline of the workflow explaining the key processing steps helps readers to quickly understand the overall design of the workflow before examining the workflow in details. The best format is a flowchart, but it can also be a descriptive text. This description can be either in the methods section, supplementary material, or as a documentation associated with the code package.
The outline of the workflow explains the key processing steps, and it helps readers to quickly understand the overall design of the workflow. The best format is a flowchart, but it can also be a descriptive text. This description can be either in the methods section, supplementary material, or provided as a documentation associated with the code package (GitHub readme, for example).
```
```{tab-item} Links
[Reproducible image handling and analysis | The EMBO Journal](https://www.embopress.org/doi/full/10.15252/embj.2020105889)
Expand All @@ -33,7 +33,7 @@ The outline of the workflow explaining the key processing steps helps readers to
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_key_settings.svg" width="50px"> &nbsp; Key settings
````{tab-set}
```{tab-item} Description
Key settings, e.g. the sigma value used for Gaussian blur, auto threshold algorithm, or the link range used for tracking, can be included as a hard-coded part of the workflow code (minimal), but we recommend a separate list of key settings as a list to explicitly present the condition of the use of the component in the workflow. This list can appear as a part of supplementary material (minimal) or as a part of code package in public repository (recommended).
Key settings, e.g. the sigma value used for Gaussian blur, the auto threshold algorithm chosen, or the link range used for tracking, can be included as a hard-coded part of the workflow code (minimal), but we recommend a separate list of key settings as a table to explicitly present the condition of the use of the component in the workflow. This list can appear as a part of supplementary material (minimal) or as a part of code package in public repository (recommended).
```
```{tab-item} Links
Expand All @@ -50,21 +50,34 @@ https://doi.org/10.1242/jcs.254151
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_roi.svg" width="50px"> &nbsp; Manual ROIs
````{tab-set}
```{tab-item} Description
TODO
If manually annotated ROIs are used in the workflow, those ROIs should be saved as a separate file and uploaded as part of the workflow package. Without these ROIs included, manually selected areas prevent others from reproducing the workflow on their own.
```
```{tab-item} Links
TODO
Measurements & regions of interest · Analyzing fluorescence microscopy images with ImageJ
https://petebankhead.gitbooks.io/imagej-intro/content/chapters/rois/rois.html#saving-rois
Saving ROIs created by analyze particles plugin - Development - Image.sc Forum
https://forum.image.sc/t/saving-rois-created-by-analyze-particles-plugin/39209
```
````
`````
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_version.svg" width="50px"> &nbsp; Exact versions
````{tab-set}
```{tab-item} Description
TODO
If the workflow used is published as a version tracked code in a public repository (e.g. GitHub), the release date or the exact version of the code should be present in the Methods section or supplementary material section. If the workflow is from a commercial software package, the version of the package and the name of the workflow must appear in the manuscript. If the workflow is only published as a supplementary material, cite that publication.
```
```{tab-item} Links
TODO
For example:
https://imagej.net/plugins/trackmate/tutorials/getting-started
For example:
Ershov, D., Phan, M.-S., Pylvänäinen, J. W., Rigaud, S. U., Le Blanc, L., Charles-Orszag, A., … Tinevez, J.-Y. (2022). TrackMate 7: integrating state-of-the-art segmentation algorithms into tracking pipelines. Nature Methods, 19(7), 829–832. doi:10.1038/s41592-022-01507-1
and / or
Tinevez, J.-Y., Perry, N., Schindelin, J., Hoopes, G. M., Reynolds, G. D., Laplantine, E., … Eliceiri, K. W. (2017). TrackMate: An open and extensible platform for single-particle tracking. Methods, 115, 80–90. doi:10.1016/j.ymeth.2016.09.016
```
````
`````
Expand Down Expand Up @@ -92,7 +105,7 @@ Publish the workflow code and example data in public repository such as GitHub o
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_all_settings.svg" width="50px"> &nbsp; All settings
````{tab-set}
```{tab-item} Description
TODO
Sharing all settings is fairly straightforward in many cases - where a pipeline can be exported or a macro recorded - but can be tricky in others when certain impactful settings are "hidden" within Preferences or Settings sections of the software - for example Fiji has settings that change both the appearance (Invert LUT) and the values (Invert) of images, which may not be part of a given workflow but still can impact the results. Thus it is beneficial to list as much about the "state" of the program as possible, generally in the supplements as the lists can be quite long.
```
```{tab-item} Links
TODO
Expand Down Expand Up @@ -135,18 +148,36 @@ TODO
Including screengrabs of key steps in a pipeline, or if the option is available, a whole video (which could be a link to a hosted video, for example on YouTube or Google Drive) can make it far easier to reproduce an experiment, even a digital one. There are frequently steps or intermediate results experienced users take for granted, that may not be obvious to newer users of a given software or pipeline - these things can be captured in a full video recording of use but might be missed in a writeup.
```
```{tab-item} Links
TODO
How to Screen Record on Your Mac (4 Options)| The TechSmith Blog
https://www.techsmith.com/blog/screen-record-mac/
How to screen record in Windows10&11
https://www.tomshardware.com/how-to/screen-record-in-windows
Example: https://forum.image.sc/t/how-to-count-bees-pattern-recognition-and-segmentation/90115/9?u=mike_nelson
```
````
`````
`````{dropdown} <img src="/analysis_workflows/icons_analysis_workflows/icon_easy_install.svg" width="50px"> &nbsp; Easy install & usage, container
````{tab-set}
```{tab-item} Description
TODO
Installation of software and its dependencies can become a major hurdle for usage of scientific software and thus to the reproduction of any analysis. Creating easy installations and documenting them for users is therefore vital to increase accessibility and reproducibility.
To overcome the diversity of the computing environment and allow the execution of workflow by anyone, workflow and sample data packaged in a container together (e.g. FIJI version of ImageJ or Icy or Docker images), are ideal solutions for presenting new workflows.
```
```{tab-item} Links
TODO
see example of preparation of a Docker for DL4Mic:
https://github.com/HenriquesLab/DL4MicEverywhere/blob/main/docs/USER_GUIDE.md#run-dl4miceverywhere-for-the-first-time
References
Moreau, D., Wiebels, K. & Boettiger, C. Containers for computational reproducibility. Nat Rev Methods Primers 3, 50 (2023). https://doi.org/10.1038/s43586-023-00236-9
Ten simple rules for writing Dockerfiles for reproducible data science | PLOS Computational Biology
https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008316
https://github.com/HenriquesLab/DL4MicEverywhere/blob/main/docs/USER_GUIDE.md#run-dl4miceverywhere-for-the-first-time
```
````
`````
Expand Down
Loading

0 comments on commit 229ed6c

Please sign in to comment.