Adding more detailed protocols section #60
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
*Not finished yet* Added a new qmd for the section on protocols and began to flesh out the text. Also added the assets for this new document. Will continue to draft this tomorrow.
Added additional examples and figures, while writing out the walk through of how the data was moved from text to tables. Still not quite finished as I need to add the final "tying it all together" section.
Final edits for the complete first draft of the protocols documentation, includes adding all the illustrative figures and tables, also updated the yaml to reference the protocols.qmd chapter.
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| The structure we have adopted also ensures that protocols can be mapped and replicated across different laboratory environments, and that modifications and version differences can be parsimoniously recorded. It can also be recorded such that it can be referenced by measures that all use an identical protocol, or can be used to record unique protocols that depend on external factors or the attributes of a sample. | ||
|
|
||
| The protocols structure within the ODM is one of the more complicated aspects of the model, and joins (other approaches)[https://bioprotocols.github.io/labop/] for parsimonious and succinct protocol data storage that are out there. Where the ODM approach is different is that our approach allows you to store protocol data in csv or excel files in the same place as you store all your other surveillance data. Furthermore, there is no need to understand and additional ontologies or write in any additional markup languages, hopefully simplifying the use of our model. |
There was a problem hiding this comment.
there is no need to understand [any] additional ontologies
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Suggested minimum Reporting | ||
|
|
||
| As mentioned above, we know that protocols can be very complicated, and taking the time to record every detail of a protocol can be time consuming, and potentially tedious. While having such a granular level of data can be rewarding in its own right, establishing minimum standards for what should be reported in a protocol can free up valuable time. Building on the work of (McClary-Gutierrez, et al. 2021)[https://pubs.rsc.org/en/content/articlehtml/2021/ew/d1ew00235j], we recommend that the minimum protocol information follow what is laid out in the table below (adapted from McClary-Gutierrez, et al., 2021). |
There was a problem hiding this comment.
Brackets and parentheses are inverted in the link markup
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Example Protocol: Methods Text to ODM Data - Sample Fractioning | ||
|
|
||
| To show how protocol data can be reported in practice, we will use a portion of the methods section from (a paper from the Delatolla Research Group)[https://www.sciencedirect.com/science/article/pii/S0043135420310952?via%3Dihub] at the University of Ottawa. This group is among our closest collaborators, and have supported and worked substantially on the ODM. |
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| Lets start by looking at a chunk from the methods section of the paper. This section (Figure B) specifically is talking about different approaches of fractionating wastewater that were tested out while developing their protocol. | ||
|
|
||
|  |
There was a problem hiding this comment.
The ellipses make it hard to understand what is being grouped as separate methods. Could you instead use differently-colored highlighting?
jeandavidt
reviewed
Sep 7, 2023
|
|
||
|  | ||
|
|
||
| You can see in the paragraph, there are actually three protocls being described: one for the solid fraction of the post-grit wastewater sample (PGS), one for the liquid fraction of the PGS, and one for the eluate fraction of the PGS. Now that we have these three protocols separated out, we can start breaking each of them down into their constituent protocol steps. |
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| You can see how each of these separate protocols have been broken down into protocol steps in shortened protocol steps tables in Figure C. You can see here that each step is made up of either a method part or a measure part. For measure-type protocol steps, a numeric value is recorded along with the units and aggregations. For method-type protocols, the value is usually categorical for which units and aggregations are not required. Note that each protocol step also has a user-generated unique identifier (`stepID`). | ||
|
|
||
|  |
There was a problem hiding this comment.
- The arrows on the left could be removed and replace with a text note describing hat the sub-tables contain (i.e., Solid fraction steps, Liquid fraction steps, eluate steps)
- The relationship arrows need to be read along ith the method/measure, so it would be easier for the reader if the arrows were on the left side
- Maybe the stepID could be greyed out or italicized since it has no semantic meaning? Otherwise, as a reader, you are tempted to spend a lot of time decoding them even though they don,t really matter for interpreting the table
- The bracket on top could end closer to the table on the right side.
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Example Protocol: Methods Text to ODM Data - PEG Concentration | ||
|
|
||
| Lets continue the above example from the (Delatolla Research Group paper)[https://www.sciencedirect.com/science/article/pii/S0043135420310952?via%3Dihub], this time looking at the next part of the protocol: concentrating the sample with Polyethylene Glycol (PEG). First, lets look at the description in the methods section of the paper (Figure G). |
jeandavidt
reviewed
Sep 7, 2023
|  | ||
| From the text, we can glean that all the described steps fit into one protocol. So we can begin to break the paragraph down into protocol steps, and populate the protocol steps table (Figure H). Again, each step is made up of either a method part or a measure part. The measure-type protocol steps have a recorded numeric value with units and aggregations. The method-type protocols record a categorical value for which units and aggregations are not required. Each protocol step also has a user-generated unique identifier (`stepID`). As with the above example in Figure C, the right side of the tables in Figure H has added coloured vectors connecting rows of the tables with a specified relationship. | ||
|
|
||
|  |
There was a problem hiding this comment.
Typo in blue arrow label
jeandavidt
reviewed
Sep 7, 2023
|
|
||
|  | ||
|
|
||
| Taking these relationships, as defined in the text, and moving them into a protocol relationships table, we see again that many steps are duplicated across the protocols. Thinking through this protocol, the repeated centrifugation step is recorded somewhat ambiguously, because the same step is used twice but specified differently (Figure I). |
There was a problem hiding this comment.
Text sizes vary, possibly to add emphasis? Maybe the repeated labels can be in bold instead
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Example Protocol: Methods Text to ODM Data - RNA Extraction | ||
|
|
||
| Continuing with this example from the (Delatolla Research Group paper)[https://www.sciencedirect.com/science/article/pii/S0043135420310952?via%3Dihub], we will now look at how the RNA Extraction protocol was described in the methods section of the paper (Figure L). |
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Example Protocol: Methods Text to ODM Data - PCR Quantification | ||
|
|
||
| Still using the methods section from the (Delatolla Research Group paper)[https://www.sciencedirect.com/science/article/pii/S0043135420310952?via%3Dihub], we will now look at how to record the PCR quantification protocol data. As with the other examples, we will start with the methods section of the paper (Figure N). |
jeandavidt
reviewed
Sep 7, 2023
|  | ||
| The text describes a single protocol for all samples, however it's clear that the process is quite complicated and will likely need sub-protocols. We can start by breaking this section down into protocol steps and populating the protocol steps table (Figure O). | ||
|
|
||
|  |
There was a problem hiding this comment.
- The ends of the arrows around "Primer mix protocol" are a bit wonky.
- Great job breaking down such a complex protocol! Glad to see that the structure seems to hold up.
- The Primer mix protocol specifies the PCR method and is before the PCR Thermocycling protocol. But doesn't the PCR thermocycling protocol also specify the PCR method?
- There are a lot of arrows, and they don't all represent the same thing. To lighten the visual burden, could this figure be broken down into 2? One with only the relationships between steps, and another with the step groups (sub-protocols)?
jeandavidt
reviewed
Sep 7, 2023
|
|
||
|  | ||
|
|
||
| Each pictured part of this flowchart has already been added as an ODM protocol in the above examples, but not we can try to tie them all together at the top level. The steps and protocols have already been generated, so we can go right to the protocol relationships table in Figure S where the processes from Figure R are summarized in the ODM format. |
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| ## Example Protocol: Methods Text to ODM Data - Tying it all Together | ||
|
|
||
| the previous examples have pulled together ODM protocol data from various pieces of the methods section of a paper. For measures of viral presence in wastewater, however, all of these steps are used to arrive at the final reported result. Let's examine the flow chart diagram from the same (Delatolla Research Group paper)[https://www.sciencedirect.com/science/article/pii/S0043135420310952?via%3Dihub] in Figure R. |
jeandavidt
reviewed
Sep 7, 2023
|
|
||
| The complete flow chart for all this data can also be found below in Figure U. | ||
|
|
||
|  |
There was a problem hiding this comment.
Maybe add a note to make sure the reader too intimidated by the final figure.
- Maybe note that the level of detail one chooses to record is at the discretion of the user
- maybe add a version of the same protocol that only has high-level details (i.e., only Figure U, but with more info in the summary)
jeandavidt
reviewed
Sep 7, 2023
|
Thanks, JD! Will go through and fix this up more concretely once I'm back. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Not finished yet Added a new qmd for the section on protocols and began to flesh out the text. Also added the assets for this new document. Will continue to draft this tomorrow.