openjournals / joss-reviews

Reviews for the Journal of Open Source Software
Creative Commons Zero v1.0 Universal
707 stars 37 forks source link

[REVIEW]: scribl: A system for the semantic capture of relationships in biological literature #6645

Closed editorialbot closed 2 months ago

editorialbot commented 5 months ago

Submitting author: !--author-handle-->@alexlancaster<!--end-author-handle-- (Alexander Lancaster) Repository: https://github.com/amberbiology/scribl Branch with paper.md (empty if default branch): manuscript Version: v0.8.0 Editor: !--editor-->@atrisovic<!--end-editor-- Reviewers: @benlansdell, @mhucka Archive: 10.5281/zenodo.12728363

Status

status

Status badge code:

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

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) by leaving comments 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

@benlansdell & @mhucka, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @atrisovic know.

Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest

Checklists

📝 Checklist for @mhucka

📝 Checklist for @benlansdell

editorialbot commented 5 months ago

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

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

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf
editorialbot commented 5 months ago
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1007/3-540-45848-4_59 is OK
- 10.1016/j.febslet.2005.02.005 is OK
- 10.1145/3183713.3190657 is OK
- 10.1093/nar/gkab1028 is OK
- 10.15252/msb.20199110 is OK
- 10.1186/gb-2008-9-s2-s8 is OK
- 10.1186/s13742-015-0077-2 is OK
- 10.1093/bioinformatics/btm401 is OK

MISSING DOIs

- No DOI given, and none found for title: The Kappa Language and Kappa Tools
- No DOI given, and none found for title: Exploring network structure, dynamics, and functio...

INVALID DOIs

- None
editorialbot commented 5 months ago

Software report:

github.com/AlDanial/cloc v 1.90  T=0.03 s (1024.7 files/s, 126665.4 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          11            228            138           1556
Markdown                         3            164              0            475
CSV                              5              0              0            282
YAML                             6             20             55            273
TeX                              1              9              0            140
JSON                             1              0              0             64
TOML                             1             10              1             46
-------------------------------------------------------------------------------
SUM:                            28            431            194           2836
-------------------------------------------------------------------------------

Commit count by author:

    37  Alex Lancaster
     9  dependabot[bot]
     1  Gordon Webster
editorialbot commented 5 months ago

Paper file info:

📄 Wordcount for paper.md is 1090

✅ The paper includes a Statement of need section

editorialbot commented 5 months ago

License info:

🟡 License found: GNU Affero General Public License v3.0 (Check here for OSI approval)

editorialbot commented 5 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

alexlancaster commented 4 months ago

copying over my comment from the pre-review ticket, regarding DOIs

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

MISSING DOIs

- No DOI given, and none found for title: The Kappa Language and Kappa Tools

There is no DOI for this software, the official documentation: https://kappalanguage.org/documentation recommends citing using the following, which we did:

P. Boutillier, J. Feret, J. Krivine, and W. Fontana. The Kappa Language and Tools (version of <insert date on cover>), kappalanguage.org.

- No DOI given, and none found for title: Exploring network structure, dynamics, and functio...

It looks like this is part of a DOE conference series, and the official URL: https://www.osti.gov/biblio/960616 provides BibTeX reference, but does not provide a DOI.

alexlancaster commented 3 months ago

hi there, as one of the primary authors, let me know if there's anything I need to start to work on for the review. I already responded to the DOI report above.

mhucka commented 3 months ago

Apologies for my tardiness on this; I've been in emergency mode on a project since last month. I expect that to end in the middle of next week and I should get back to this then.

mhucka commented 3 months ago

Review checklist for @mhucka

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

mhucka commented 2 months ago

I have some comments for the authors, but I'm not sure what the protocol is for doing that. (I did read https://joss.readthedocs.io/ but didn't find instructions regarding this – perhaps I missed them.) So, I'm writing them here.

Summary

The paper describes a novel and interesting approach to creating a semantic network of relationships between entities, processes, and other concepts in literature about systems biology. The approach leverages a commonly used bibliographic database (Zotero) and enables groups of researchers to curate information and collaboratively build up the network of relationships. The paper reads well; the documentation accompanying the software (scribl) is extensive and detailed. I think the paper and software tick all the boxes for JOSS, and constitute a new and fresh idea.

Typos & such

Suggestions (optional)

alexlancaster commented 2 months ago

Hi @mhucka - thanks for the review. We'll get right on doing those suggested changes.

benlansdell commented 2 months ago

Review checklist for @benlansdell

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

alexlancaster commented 2 months ago

Thanks for the review, @mhucka! All responses are below and inline. I'm also generating a new version of the paper, in the comment after this one.

Typos & such

  • p. 1, line 16: I think the word "for" needs to be inserted after "suitable".

Good catch. Fixed.

  • p. 3, line 58: "celluar" → "cellular".

Fixed

Suggestions (optional)

  • In the section on related work ("What scribl is not"), I think it would enhance the paper to add a sentence or two contrasting scribl to Cytoscape. Although Cytoscape is indirectly referenced in the abstract by referencing the paper by Suderman & Hallett, I suspect that many readers working in this domain are likely to know about Cytoscape for graph visualization, and may wonder how scribl relates to it. IMHO, a direct explanation in the authors' own words would be preferable to making readers work it out for themselves.

Good point - I have added a sentence contextualizing the possible use of scribl Neo4j in conjunction with Cytoscape in the section about Reactome. In the same section I've also added a note that scribl could also be extended to generate models directly with enough annotations.

  • Although the paper shows examples of scribl syntax used in adding tags to Zotero entries, it's not immediately obvious to readers how to make use of this data. The README for the repository does include examples of how to actually run scribl; still, in reading this paper, I kept thinking "okay, but what do I do with this?" and had to go to the repository to find out. So I think another enhancement to the paper would be to add just one example of running scribl on the command line. It can be simply words to the effect of "After installing and configuring scribl, it can be simply invoked as a shell command, as shown in the following basic example", followed by a code block with a one-line scribl shell command. It would make the paper slightly more self-contained and help communicate to readers that usage is simple.

Agreed. I have added a command-line sample in the section about the generation of the graph using NetworkX.

  • In figure 2, the font size of the text inside the boxes of the figure is very small, verging on microscopically small. Yes, readers can zoom in to read it, but it looks like there's enough room to enlarge the text a little bit. It doesn't have to be made huge, but IMHO a small enlargement would help. Figure 1 could use the same treatment; figure 3 is okay.

I have tried increasing the Fig 1 & 2 sizes by trimming the whitespace in the originals and increasing the width. In the case of Fig 2, I think I'm at about the limit where it gets too wide for the page (JOSS doesn't like to use the full page width - it seems to lose about 1/3 of the page due to the left margin). So it's at about the limit I can do without going back to the original figures and increasing the font size. Hopefully it's sufficient now.

alexlancaster commented 2 months ago

@editorialbot generate pdf

editorialbot commented 2 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

alexlancaster commented 2 months ago
  • In figure 2, the font size of the text inside the boxes of the figure is very small, verging on microscopically small. Yes, readers can zoom in to read it, but it looks like there's enough room to enlarge the text a little bit. It doesn't have to be made huge, but IMHO a small enlargement would help. Figure 1 could use the same treatment; figure 3 is okay.

I have tried increasing the Fig 1 & 2 sizes by trimming the whitespace in the originals and increasing the width. In the case of Fig 2, I think I'm at about the limit where it gets too wide for the page (JOSS doesn't like to use the full page width - it seems to lose about 1/3 of the page due to the left margin). So it's at about the limit I can do without going back to the original figures and increasing the font size. Hopefully it's sufficient now.

@mhucka we went back to the source and have replaced Figs 1 & 2 with versions with larger font size that should be clearer now. I'll use editorialbot to generate new versions of the paper in the next comment.

alexlancaster commented 2 months ago

@editorialbot generate pdf

editorialbot commented 2 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

benlansdell commented 2 months ago

Hi @alexlancaster ,

Apologies for the delay in getting to this. I've gone over the code and repo -- looks like a useful package! In going through the review checklist two items stand out as needing some attention. One I made an issue for in the main repo, the other I'll just mention here.

The first is that I'm unable to run the unit tests locally myself. Many tests complain about files missing... (See issue https://github.com/amberbiology/scribl/issues/15)

The other is that I think the API documentation in the scribl.pdf (page 39 onwards) could benefit from some more standard formatting. The text description, I think, does consistently describe what the inputs and returns are, but I can't be certain. It would be useful to have standard argument lists/return types/etc for this.

alexlancaster commented 2 months ago

Hi @alexlancaster ,

Apologies for the delay in getting to this. I've gone over the code and repo -- looks like a useful package! In going through the review checklist two items stand out as needing some attention. One I made an issue for in the main repo, the other I'll just mention here.

The first is that I'm unable to run the unit tests locally myself. Many tests complain about files missing... (See issue https://github.com/amberbiology/scribl/issues/15)

Good catch, see my followup on the issue.

The other is that I think the API documentation in the scribl.pdf (page 39 onwards) could benefit from some more standard formatting. The text description, I think, does consistently describe what the inputs and returns are, but I can't be certain. It would be useful to have standard argument lists/return types/etc for this.

Good point. I'll take a look at this. (Tagging my coauthor @gwebster on this as well).

benlansdell commented 2 months ago

@alexlancaster Thanks for the quick response. I can confirm the PR you made fixes the testing issue. If the documentation is fixed up slightly, I'm happy with everything else

mhucka commented 2 months ago

@mhucka we went back to the source and have replaced Figs 1 & 2 with versions with larger font size that should be clearer now. I'll use editorialbot to generate new versions of the paper in the next comment.

The new figures and font sizes are great! Thanks for doing that.

alexlancaster commented 2 months ago

@alexlancaster Thanks for the quick response. I can confirm the PR you made fixes the testing issue. If the documentation is fixed up slightly, I'm happy with everything else

Great - @gwebster and I worked on the method docs, and the PDF is now updated.

benlansdell commented 2 months ago

@alexlancaster Thanks for the quick response. I can confirm the PR you made fixes the testing issue. If the documentation is fixed up slightly, I'm happy with everything else

Great - @gwebster and I worked on the method docs, and the PDF is now updated.

Looks good! Thanks for fixing that up quickly. That is all of my concerns addressed.

alexlancaster commented 2 months ago

@editorialbot generate preprint

editorialbot commented 2 months ago

:page_facing_up: Preprint file created: Find it here in the Artifacts list :page_facing_up:

alexlancaster commented 2 months ago

Thanks both @mhucka & @benlansdell ! it looks like both of your review checklists are now complete. Are there any other outstanding issues to fix?

Are there any next steps I need to take @atrisovic ?

mhucka commented 2 months ago

Thanks both @mhucka & @benlansdell ! it looks like both of your review checklists are now complete. Are there any other outstanding issues to fix?

Nothing from me.

benlansdell commented 2 months ago

Thanks both @mhucka & @benlansdell ! it looks like both of your review checklists are now complete. Are there any other outstanding issues to fix?

Are there any next steps I need to take @atrisovic ?

Nothing from me either.

atrisovic commented 2 months ago

Ok wonderful, we are almost there. Thank you both @mhucka & @benlansdell :) ! I will follow up shortly.

atrisovic commented 2 months ago

@editorialbot generate pdf

editorialbot commented 2 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

atrisovic commented 2 months ago

Post-Review Checklist for Editor and Authors

Additional Author Tasks After Review is Complete

Editor Tasks Prior to Acceptance

alexlancaster commented 2 months ago

Thank you @atrisovic !

Additional Author Tasks After Review is Complete

  • Double check authors and affiliations (including ORCIDs)

All correct

  • Make a release of the software with the latest changes from the review and post the version number here. This is the version that will be used in the JOSS paper.

Release made: v0.8.0:

https://github.com/amberbiology/scribl/releases/tag/v0.8.0

  • Archive the release on Zenodo/figshare/etc and post the DOI here.

v0.8.0 archived on Zenodo:

https://zenodo.org/records/12728363 / DOI: 10.5281/zenodo.12728363

The DOI for the "all versions": 10.5281/zenodo.12728362

  • Make sure that the title and author list (including ORCIDs) in the archive match those in the JOSS paper.

They match.

  • Make sure that the license listed for the archive is the same as the software license.

Matched: "GNU Affero General Public License v3.0 or later" (AGPLv3.0+)

atrisovic commented 2 months ago

@editorialbot check references

editorialbot commented 2 months ago
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1007/3-540-45848-4_59 is OK
- 10.1016/j.febslet.2005.02.005 is OK
- 10.1145/3183713.3190657 is OK
- 10.1093/nar/gkab1028 is OK
- 10.15252/msb.20199110 is OK
- 10.1186/gb-2008-9-s2-s8 is OK
- 10.1186/s13742-015-0077-2 is OK
- 10.1101/gr.1239303 is OK
- 10.1093/bioinformatics/btm401 is OK

MISSING DOIs

- No DOI given, and none found for title: The Kappa Language and Kappa Tools
- No DOI given, and none found for title: Exploring network structure, dynamics, and functio...

INVALID DOIs

- None
atrisovic commented 2 months ago

Hi @alexlancaster I have now created a pull request with a few edits https://github.com/amberbiology/scribl/pull/21.

alexlancaster commented 2 months ago

Hi @alexlancaster I have now created a pull request with a few edits amberbiology/scribl#21.

Thanks, now merged into my manuscript branch. I also went through the checklist above.

atrisovic commented 2 months ago

@editorialbot set 10.5281/zenodo.12728363 as archive

editorialbot commented 2 months ago

Done! archive is now 10.5281/zenodo.12728363

atrisovic commented 2 months ago

@editorialbot generate pdf

atrisovic commented 2 months ago

@editorialbot set v0.8.0 as version

editorialbot commented 2 months ago

Done! version is now v0.8.0

editorialbot commented 2 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

atrisovic commented 2 months ago

@editorialbot recommend-accept

editorialbot commented 2 months ago
Attempting dry run of processing paper acceptance...
editorialbot commented 2 months ago
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1007/3-540-45848-4_59 is OK
- 10.1016/j.febslet.2005.02.005 is OK
- 10.1145/3183713.3190657 is OK
- 10.1093/nar/gkab1028 is OK
- 10.15252/msb.20199110 is OK
- 10.1186/gb-2008-9-s2-s8 is OK
- 10.1186/s13742-015-0077-2 is OK
- 10.1101/gr.1239303 is OK
- 10.1093/bioinformatics/btm401 is OK

MISSING DOIs

- No DOI given, and none found for title: The Kappa Language and Kappa Tools
- No DOI given, and none found for title: Exploring network structure, dynamics, and functio...

INVALID DOIs

- None
editorialbot commented 2 months ago

:wave: @openjournals/bcm-eics, this paper is ready to be accepted and published.

Check final proof :point_right::page_facing_up: Download article

If the paper PDF and the deposit XML files look good in https://github.com/openjournals/joss-papers/pull/5606, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

alexlancaster commented 2 months ago

@editorialbot recommend-accept

Thanks @atrisovic ! Are there next steps we need to do for final acceptance?