Figure 1: analysis/manuscript workflow overview panel + panel for potential path of analytical PR

[jaclyn-taroni]

Purpose/implementation Section

Addresses https://github.com/AlexsLemonade/OpenPBTA-manuscript/issues/83. Adding the following panels:

• figures/pdfs/fig1/panels/analysis-manuscript-workflow-overview.pdf, which illustrates the flow from proposing an analysis, filing a request to add an analysis, and writing up the results. There is a "row" at the bottom that indicates what underlying technology is required for each step (with some caveats, see below).
• figures/pdfs/fig1/panels/analytical-pr-journey.pdf, which illustrates a potential path for an individual analytical pull request. It is intended to make it easy to talk about features like Docker and CI in more detail.

Directions for reviewers. Tell potential reviewers what kind of feedback you are soliciting.

Notes on icon/logo usage

• All the icons were obtained as part of a subscription to the Noun Project. They cleared usage in this manner via email correspondence with Stephanie.
• GitHub logo should be fine by my read: https://github.com/logos
• Manubot logo is CC0: https://github.com/manubot/resources#license
• We’re using a generic icon to show that we’re using a container and a CI service because of these guidelines:
  • CircleCI Trademark Guidelines
  • Docker Trademark Guidelines

But those guidelines both mention contacting for permission if that’s a route we want to go.

Is the analysis in a mature enough form that the resulting figure(s) and/or table(s) are ready for review?

Yes

⚠️ filing as a draft for now because there’s no docs yet, but I'll still take feedback on the panels themselves.

[jharenza]

Hi @jaclyn-taroni! This looks really nice!

I have a few comments.

For workflow overview:

• Since in column 1, you mention GitHub issue, should we add in column 2, instead of "and requests to add to repository" --> "via GitHub Pull Request (PR)". It is more technical jargon, but it may be easier to put the longer explanation in text "requests to add to repository via GitHub Pull Request (PR)". Thoughts on that?
• Same comment as above for column 3 for manuscript
• For column 2 "request undergoes analytical code review" - I might suggest changing to something like "scientific, analytical, and code review" to demonstrate the rigor of each analysis/PR. OR, leave it as "undergoes review" (though I favor that less) with an explanation of all of the review in the text.

For analytical PR review:

• It is written linearly, but the process can be very different each time, and I feel like there is sometimes some back and forth, so this might be hard to capture generally. I might have to see some description text to better judge the actual path here. While we want to describe the process, I also think we don't want to make it too complicated, so would you be able to write this out a bit?

[sjspielman]

The docker icon being used is a little confusing because it looks so much like a real software of some kind, instead of a "container stub." I wonder if something like a simple "box" would look less that way, but then again anything can be a minimalist icon.. Something like these is what I'm thinking. https://thenounproject.com/icon/box-3820378/ or https://thenounproject.com/icon/box-713425/ (searched "box").

I think it's worthwhile to reach out to docker and CI to see if we can use. We have time before we need the final submission version!

[jharenza]

I think it's worthwhile to reach out to docker and CI to see if we can use.

Agree and also meant to say that!

[jaclyn-taroni]

With https://github.com/AlexsLemonade/OpenPBTA-analysis/pull/1292/commits/18ab6ab854eb46227d976877e9eb6714bead05d0, I've:

• Removed the reference to GitHub issues (just "issue" now) so we're at the same level of specificity and don't add more text to the other parts of the panel
• "Scientific and analytical code review" - to me "analytical code review" means you're reviewing analysis and code that performs the analysis
• Made the container icon black. If we think the CI and container icons might be placeholders, then this seems fine to me for now!

It is written linearly, but the process can be very different each time, and I feel like there is sometimes some back and forth, so this might be hard to capture generally. I might have to see some description text to better judge the actual path here. While we want to describe the process, I also think we don't want to make it too complicated, so would you be able to write this out a bit?

Personally, I don't think making it as complicated as it sometimes is in reality is helpful to our readers. So we could add this as is for now, write up some text in the manuscript and revisit.

[sjspielman]

So we could add this as is for now, write up some text in the manuscript and revisit.

I agree with this approach.

[jharenza]

Personally, I don't think making it as complicated as it sometimes is in reality is helpful to our readers. So we could add this as is for now, write up some text in the manuscript and revisit.

Agreed! I meant this seems complicated now, and making it more like reality is going to be even more complicated. Maybe we can simplify this example some more? Although I meant maybe you have a clear description in mind that would make this less complicated to say a clinician reading this.

[jharenza]

Removed the reference to GitHub issues (just "issue" now) so we're at the same level of specificity and don't add more text to the other parts of the panel "Scientific and analytical code review" - to me "analytical code review" means you're reviewing analysis and code that performs the analysis Made the container icon black. If we think the CI and container icons might be placeholders, then this seems fine to me for now!

This looks good!

[jaclyn-taroni]

Only adding docs and figure panels that are not programmatically generated here, so merging without CI!