[REVIEW]: ssdtools: An R package to fit Species Sensitivity Distributions (SSDs)

[whedon]

Submitting author: @joethorley (Joseph Thorley)
Repository: https://github.com/bcgov/ssdtools
Version: v0.0.3
Editor: @arfon
Reviewer: @ibarraespinosa, @nanhung
Archive: 10.5281/zenodo.1651641

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/522da410296b2caefd8a23500ff62611"><img src="http://joss.theoj.org/papers/522da410296b2caefd8a23500ff62611/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/522da410296b2caefd8a23500ff62611/status.svg)](http://joss.theoj.org/papers/522da410296b2caefd8a23500ff62611)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@ibarraespinosa & @nanhung, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @arfon know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @ibarraespinosa

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: Does the release version given match the GitHub release (v0.0.3)?
• Authorship: Has the submitting author (@joethorley) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @nanhung

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: Does the release version given match the GitHub release (v0.0.3)?
• Authorship: Has the submitting author (@joethorley) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @ibarraespinosa, it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[arfon]

@ibarraespinosa, @nanhung - please carry out your review in this issue by updating the checklist above and giving feedback in this issue. The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html

Any questions/concerns please let me know.

[nanhung]

Overall, the package and paper look great. Just a few couples of questions and suggestions:

• For the title, I suggest removing the abbreviation SSDs.
• Does Carl Schwarz make any significant contributions to this paper or software?
• I find that there're only ssdfit_dist and ssdfit_dists rather than ssdfit in your package. Why not combine these two functions to one and named it ssdfit?
• I try to use ggplot with geom_xribbon and geom_hcintercept that you mentioned in summary. However, I don't know how to use geom_xribbon. Perhaps you can provide an example in the reference manual.
• Is it possible to use lower case "g" for ggplot2 in reference?
• Does any of the references have doi? If so, please provide them?
• I can only find one reference in the reference manual. Is there some reference that you can add?

[joethorley]

Thanks @nanhung

My responses are as follows

• done
• yes he wrote the original R scripts on which ssdtools is based
• I decided to provide two functions so that the class of the returned object would not depend on the number of distributions used ie ssd_fit_dist returns a object of class fitdist while ssd_fit_dists returns a object of class fitdists which is a list of objects of class fitdist
• I've added a simple example of the use of each geom to the manual
• done
• I could only find a doi for two of the references (which I have added)
• The manual now has 5 references

The updated manual is at https://bcgov.github.io/ssdtools/articles/ssdtools-manual.html

Let me know if you require anymore information.

[joethorley]

@whedon commands

[whedon]

Here are some things you can ask me to do:

# List Whedon's capabilities
@whedon commands

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

# Compile the paper
@whedon generate pdf

🚧 🚧 🚧 Experimental Whedon features 🚧 🚧 🚧

# Compile the paper from a custom git branch
@whedon generate pdf from branch custom-branch-name

[joethorley]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[nanhung]

My concern is since you can use ssd_fit_dists to generate the same result as ssd_fit_dist such as,

data <- ssdtools::boron_data
ssd_fit_dist(data, dist = c("lnorm"))
ssd_fit_dists(data, dists = c("lnorm"))

Why users need to use ssd_fit_dist in their analysis?

[nanhung]

Is it possible to use mutiple hc line in ssd_plot, such as,

ssd_plot(boron_data, boron_pred, color = "Group", label = "Species", hc = c(5L, 50L),
         xlab = "Concentration (mg/L)", ribbon = TRUE)

The current function only support 1 element.

[joethorley]

@nanhung ssd_fit_dist() is no longer exported to eliminate redundancy

[joethorley]

@nanhung geom_hcintersect() now takes multiple values

[nanhung]

Just a suggestion. Can you add an assigment (like "group_by") in ssd_fit_dists and predict that can simplify the approach if the user wants to apply the grouping method.

Here is an example code. I haven't use the ssd_hc in this case.

library(ssdtools)
library(tidyverse)
library(scales)

boron_dists_Fish <-  boron_data %>% filter(Group == "Fish") %>% ssd_fit_dists()
boron_dists_Amphibian <-  boron_data %>% filter(Group == "Amphibian") %>% ssd_fit_dists()
boron_dists_Invertebrate <- boron_data %>% filter(Group == "Invertebrate") %>% ssd_fit_dists()
boron_dists_Plant <-  boron_data %>% filter(Group == "Plant") %>% ssd_fit_dists()

boron_pred_Fish <- predict(boron_dists_Fish)
boron_pred_Amphibian <- predict(boron_dists_Amphibian)
boron_pred_Invertebrate <- predict(boron_dists_Invertebrate)
boron_pred_Plant <- predict(boron_dists_Plant)

boron_pred_Fish$Group <- "Fish"
boron_pred_Amphibian$Group <- "Amphibian"
boron_pred_Invertebrate$Group <- "Invertebrate"
boron_pred_Plant$Group <- "Plant"

x <- do.call(rbind, list(boron_pred_Fish, boron_pred_Amphibian, boron_pred_Invertebrate, boron_pred_Plant))

gp <- ggplot(x, aes_string(x = "est")) + 
  geom_xribbon(aes_string(xmin = "lcl", xmax = "ucl", y = "percent/100"), alpha = 0.2) +
  geom_ssd(data = boron_data, aes_string(x = "Conc")) +
  facet_wrap(~Group) + 
  scale_y_continuous("Species Affected (%)", labels = percent) +
  expand_limits(y = c(0, 1)) +
  xlab("Concentration (mg/L)") + 
  coord_trans(x = "log10") +
  geom_line(aes_string(y = "percent/100")) +
  scale_x_continuous(breaks = scales::trans_breaks("log10", function(x) 10^x),
                     labels = comma_signif)

print(gp)

[joethorley]

@nanhung It's a frequent request. I've added an example to the manual demonstrating a more elegant approach to grouping ie

library(ssdtools)
library(tidyverse)

boron_datas <- nest(boron_data, -Group)
boron_datas <- mutate(boron_datas, 
                      Fit = map(data, ssd_fit_dists, dists = "lnorm"), 
                      Prediction = map(Fit, predict))
boron_datas <- unnest(boron_datas, Prediction)

[joethorley]

@nanhung I've also added to the manual a demonstration of how to plot HC5s for different groups

boron_hc5s <- filter(boron_datas, percent == 5)
gp %+% boron_datas + 
  facet_wrap(~Group) + 
  geom_hcintersect(data = boron_hc5s, aes(xintercept = est, yintercept = percent/100))

[nanhung]

I'm trying to create the same plot in the example of ssd_plot by geom_ssd function. However, it seems that the geom_ssd doesn't support the different color by groups.

# Defind single color
ggplot(boron_data, aes(x = Conc)) +
  geom_ssd(colour = "red")
 
# Defind color by groups
ggplot(boron_data, aes(x = Conc)) +
  geom_ssd(colour = Group)

[joethorley]

try

ggplot(boron_data, aes(x = Conc)) +
  geom_ssd(aes(colour = Group))

[ibarraespinosa]

Hi @joethorley Interesting package. Demo is not running on line 42, consider adding ggplot2::autoplot(fits) or library(ggplto2) on ssdtools.R
Issue: bcgov/ssdtools#31

[joethorley]

@ibarraespinosa thanks - fixed

[joethorley]

ahh - I just saw your pull request - I would have accepted had I seen it earlier

[joethorley]

@ibarraespinosa I accepted your pull request because it is more elegant than what I did

[ibarraespinosa]

Hi @joethorley. I found de package very interesting and also well documented with examples, tests and CI. I like that you added images in the help page. However, I found the paper hard to follow and the problem is not clearly stated. Also, there is a missing doi in the reference section.

The classes work very well with ggplot2 producing nice plots, however, it would be more gentle to the reader to see the code that generates the Figure 1: 'Species sensitivity distributions for sample species concentration values'.

In general, well done. After fixing that, it would be OK to accept the paper.

[joethorley]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[kyleniemeyer]

Hi @joethorley, I just noticed that the affiliation info in the paper is slightly incomplete—could you extend it for both authors, e.g. with city and country info? (The way it would appear in a traditional article.)

Regarding the software DOI, it works ok here. The article DOI in the PDF will not be generated until the paper is actually published, though.

[joethorley]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[joethorley]

@kyleniemeyer I've fixed the affiliations but note that although the Review and Repository links work the Archive link does not - can you confirm this specific link works at your end as the archive DOI is already live (unlike the paper DOI). The full address is https://doi.org/10.5281/zenodo.1651641

[kyleniemeyer]

@joethorley I see what you mean. Hmm.

[kyleniemeyer]

@whedon set 10.5281/zenodo.1651641 as archive

[whedon]

OK. 10.5281/zenodo.1651641 is the archive.

[kyleniemeyer]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[kyleniemeyer]

@arfon when you get a chance, could you check out the PDF generation? The archive link is not working in the PDF—seems like something is going wrong.

[joethorley]

@kyleniemeyer - still no joy!

[arfon]

@arfon when you get a chance, could you check out the PDF generation? The archive link is not working in the PDF—seems like something is going wrong.

The archive link only gets compiled in once we're ready to accept.

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof 👉 openjournals/joss-papers#88

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#88, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[arfon]

...archive link is working in the final proofs here:
openjournals/joss-papers#88

[kyleniemeyer]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.01082 joss-papers#89
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01082
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

[kyleniemeyer]

@joethorley congrats on your paper acceptance into JOSS!

@ibarraespinosa & @nanhung thank you for your reviews, and thanks to @arfon for handling this submission.

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](http://joss.theoj.org/papers/10.21105/joss.01082/status.svg)](https://doi.org/10.21105/joss.01082)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.01082">
  <img src="http://joss.theoj.org/papers/10.21105/joss.01082/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: http://joss.theoj.org/papers/10.21105/joss.01082/status.svg
   :target: https://doi.org/10.21105/joss.01082

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3Nzk=