[REVIEW]: The pdb2sql Python Package: Parsing, Manipulation and Analysis of PDB Files Using SQL Queries #2077

whedon · 2020-02-06T18:11:01Z

Submitting author: @NicoRenaud (Nicolas Renaud)
Repository: https://github.com/DeepRank/pdb2sql
Version: 0.4.0
Editor: @lpantano
Reviewers: @i-mtz, @JoaoRodrigues, @joaomcteixeira
Archive: 10.5281/zenodo.3860329

Status

Status badge code:

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

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

@i-mtz & @JoaoRodrigues & @joaomcteixeira, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

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

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

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

Review checklist for @joaomcteixeira

Conflict of interest

I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

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?
Contribution and authorship: Has the submitting author (@NicoRenaud) 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 functionality 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

Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
State of the field: Do the authors describe how this software compares to other commonly-used packages?
Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @i-mtz

Conflict of interest

I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

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?
Contribution and authorship: Has the submitting author (@NicoRenaud) 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 functionality 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

Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
State of the field: Do the authors describe how this software compares to other commonly-used packages?
Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @JoaoRodrigues

Conflict of interest

I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

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?
Contribution and authorship: Has the submitting author (@NicoRenaud) 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 functionality 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

Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
State of the field: Do the authors describe how this software compares to other commonly-used packages?
Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

whedon · 2020-02-06T18:11:05Z

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @i-mtz, @JoaoRodrigues it looks like you're currently assigned to review 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:

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

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

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

@whedon generate pdf

whedon · 2020-02-06T18:11:24Z

Reference check summary:

OK DOIs

- 10.1093/bioinformatics/btp163 is OK
- 10.1093/bioinformatics/btg299 is OK
- 10.1002/(SICI)1096-987X(20000130)21:2<79::AID-JCC1>3.0.CO;2-B is OK
-  10.25080/Majora-629e541a-00e  is OK
- 10.1093/bioinformatics/btz496 is OK
- 10.1093/bioinformatics/btr168 is OK
- 10.1371/journal.pcbi.1006791 is OK
- 10.1371/journal.pone.0161879 is OK
- 10.1093/nar/gky949 is OK
- 10.1101/483305 is OK
- 10.1002/prot.10393 is OK

MISSING DOIs

- None

INVALID DOIs

- None

arfon · 2020-02-06T19:23:38Z

@whedon generate pdf

whedon · 2020-02-06T19:24:09Z

👉 Check article proof 📄 👈

lpantano · 2020-02-19T12:44:58Z

@JoaoRodrigues , @i-mtz, any update in the revision of this paper? thanks!

JoaoRodrigues · 2020-02-24T22:43:46Z

Hi @lpantano , sorry for the late reply but I was traveling+sick and away from my laptop for quite some time. Apologies to the authors for the delay.

JoaoRodrigues · 2020-02-24T23:22:00Z

Hey @NicoRenaud

The tool looks good but there are a few rough edges I'd polish before publishing it. I left a few issues on your repo that should be easy to fix. Here are a few more minor questions/issues I found when going over the paper and the code:

There is a consistent typo on the word 'structure' all over the documentation :) sed -e 's/strcture/structure/g' should fix it!
As a user, I would expect I could use the interface module on a PDB I already parsed, e.g. pdb = pdb2sql('myfile.pdb'); pdbint = interface(pdb). Right now I need to load it twice and this is a bit counter-intuitive. Maybe this is a simple fix?
I'd keep to one convention when naming variables and attributes. You use a lot of get_X methods, for example, but then there are attributes named nModels, chainID, altLoc. You should stick to one, e.g., n_models, chain_id, altloc for simplicity.
For convenience, you could add a fetch method to download files from the RCSB PDB directly. Makes it easier for new users to try the tool without having to find a PDB of their own first.
The paper states that pdb2sql tries to abstract SQL language for the end-user, and it generally does a pretty good job! However, having methods like db.close() and such in the documentation (and exposed in the public API) sort of defeats the purpose. I would make these private and, my preference here, would make them happen behind the scenes so that the end user never has to worry about db connections, cursors, etc.
On the topic of dependencies, I see that sqlalchemy is not necessary for the tool to run, but it provides a better OO interface. Maybe making it a runtime dependency then? Or explain the difference between the two interfaces and why you'd want (or not) to use sqlalchemy.

Finally, I would send the text of the paper through Grammarly (its free version works well enough) to fix some incorrect grammar here and there and make it read more clearly.

Overall, the tool does what it says it does and it's pretty quick too. As I said before, just some rough edges that need polishing! Good job @NicoRenaud and @CunliangGeng !

NicoRenaud · 2020-03-06T16:04:34Z

Dear @JoaoRodrigues, thanks for reviewing our code and for your comments and suggestions. We've addressed them all, merged the changes in the master and updated the paper accordingly. As a quick summary :

we fixed the consistent typos on the documentation, thanks for spotting that
You can directly use pdbint=interface('myfile.pdb') or if needed first create an sql db and pass it to the interface : pdb = pdb2sql('myfile.pdb) pdbint =interface(pdb)
The fetch function is a very good idea that is now implemented !
Indeed exposing the .close() method is not ideal. This is now fully done behind the scene as you suggested. (Note that we always use in memory db)
we realized that we never use sqlalchemy and that we do not want to maintain code that is never used. Therefore we have decided to entirely remove sqlalchemy support form pdb2sql. We kept it in a separate branch in case there is a demand for it. We have updated the documentation and the paper accordingly.
Thanks again for all your comments !

arfon · 2020-03-14T00:22:41Z

Dear authors and reviewers

We wanted to notify you that in light of the current COVID-19 pandemic, JOSS has decided to suspend submission of new manuscripts and to handle existing manuscripts (such as this one) on a "best efforts basis". We understand that you may need to attend to more pressing issues than completing a review or updating a repository in response to a review. If this is the case, a quick note indicating that you need to put a "pause" on your involvement with a review would be appreciated but is not required.

Thanks in advance for your understanding.

Arfon Smith, Editor in Chief, on behalf of the JOSS editorial team.

lpantano · 2020-03-18T22:34:47Z

Hey @i-mtz, I hope all is good. Do you have an update for this tool?

@JoaoRodrigues, were all your comments resolved?

Thanks

JoaoRodrigues · 2020-03-18T22:36:50Z

Hi @lpantano , I haven't had time to go over the changes in detail yet, but the message from @NicoRenaud seems to address most of my comments. I am a bit swamped today, but this is on my to-do list for this week. Is that OK? Sorry for the delay in reviewing

lpantano · 2020-03-18T22:40:05Z

All good, thank you!

arfon · 2020-04-13T15:18:43Z

👋 @i-mtz, @JoaoRodrigues, just a friendly check-in to see how things are going with your reviews?

JoaoRodrigues · 2020-04-13T18:01:13Z

Hi @arfon @lpantano @NicoRenaud @CunliangGeng , this completely fell off my radar, I'm terribly sorry. Will reply as soon as possible!

JoaoRodrigues · 2020-04-13T20:44:41Z

@whedon generate pdf

whedon · 2020-04-13T20:45:13Z

👉 Check article proof 📄 👈

JoaoRodrigues · 2020-04-13T20:46:08Z

Hi @NicoRenaud @CunliangGeng

Thank you for addressing my points! I'd only add somewhere in the documentation page a mention to the fetch function. It's good for me! Approved!! Great work!

lpantano · 2020-04-13T22:41:09Z

Sorry, I need to get a new reviewer since one of them couldn't make it under the current COVID-19 situation. @NicoRenaud , if you have a reviewer in mind, let me know. I will try to find another as soon as possible.

JoaoRodrigues · 2020-04-14T00:10:09Z

Not to overstep my boundaries as a reviewer, but if I can suggest people: @joaomcteixeira or @jgreener64. Both very skilled structural bioinformaticians and very active on Github.

NicoRenaud · 2020-05-22T10:26:08Z

@arfon we updated the instruction to manually run the test as pointed out by @joaomcteixeira. We could also follow his suggestion to change the exec path but I don't really have the time to do that at the moment. So from our side we are done I think

NicoRenaud · 2020-05-27T12:49:12Z

@arfon just to let you know that @joaomcteixeira has implemented his own suggestions for the test so we are officially done with the review on our side ! Thanks again @joaomcteixeira !!

lpantano · 2020-05-27T13:14:36Z

Perfect! @NicoRenaud can you confirm the latest version is 0.2.2? if that is right, can you work on a zenodo archive of this version and having the title and authors matching what is shown in the paper? Thanks!

lpantano · 2020-05-27T13:14:46Z

@whedon check references

whedon · 2020-05-27T13:15:09Z

Reference check summary:

OK DOIs

- 10.1093/bioinformatics/btp163 is OK
- 10.1093/bioinformatics/btg299 is OK
- 10.1002/(SICI)1096-987X(20000130)21:2<79::AID-JCC1>3.0.CO;2-B is OK
-  10.25080/Majora-629e541a-00e  is OK
- 10.1093/bioinformatics/btz496 is OK
- 10.1093/bioinformatics/btr168 is OK
- 10.1371/journal.pcbi.1006791 is OK
- 10.1371/journal.pone.0161879 is OK
- 10.1093/nar/gky949 is OK
- 10.1101/483305 is OK
- 10.1002/prot.10393 is OK

MISSING DOIs

- None

INVALID DOIs

- None

lpantano · 2020-05-27T13:15:28Z

@whedon generate pdf

whedon · 2020-05-27T13:15:57Z

👉 Check article proof 📄 👈

CunliangGeng · 2020-05-27T15:43:02Z

Perfect! @NicoRenaud can you confirm the latest version is 0.2.2? if that is right, can you work on a zenodo archive of this version and having the title and authors matching what is shown in the paper? Thanks!

Thanks @lpantano, the version now is 0.4.0, and zenodo archive has been updated with your suggestions, see https://doi.org/10.5281/zenodo.3860329.

lpantano · 2020-05-27T19:18:01Z

@whedon set version as 0.4.0

whedon · 2020-05-27T19:18:04Z

I'm sorry human, I don't understand that. You can see what commands I support by typing:

@whedon commands

lpantano · 2020-05-27T19:18:57Z

@whedon set 0.4.0 as version

whedon · 2020-05-27T19:19:02Z

OK. 0.4.0 is the version.

lpantano · 2020-05-27T19:19:25Z

@whedon set 10.5281/zenodo.3860329 as archive

whedon · 2020-05-27T19:19:30Z

OK. 10.5281/zenodo.3860329 is the archive.

lpantano · 2020-05-27T19:20:26Z

@whedon accept

whedon · 2020-05-27T19:20:29Z

Attempting dry run of processing paper acceptance...

whedon · 2020-05-27T19:20:52Z

Reference check summary:

OK DOIs

- 10.1093/bioinformatics/btp163 is OK
- 10.1093/bioinformatics/btg299 is OK
- 10.1002/(SICI)1096-987X(20000130)21:2<79::AID-JCC1>3.0.CO;2-B is OK
-  10.25080/Majora-629e541a-00e  is OK
- 10.1093/bioinformatics/btz496 is OK
- 10.1093/bioinformatics/btr168 is OK
- 10.1371/journal.pcbi.1006791 is OK
- 10.1371/journal.pone.0161879 is OK
- 10.1093/nar/gky949 is OK
- 10.1101/483305 is OK
- 10.1002/prot.10393 is OK

MISSING DOIs

- None

INVALID DOIs

- None

whedon · 2020-05-27T19:21:20Z

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#1460

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

@whedon accept deposit=true

danielskatz · 2020-05-27T19:57:18Z

👋 @NicoRenaud - please merge the minor changes in DeepRank/pdb2sql#54 or let me know what you disagree with in it

CunliangGeng · 2020-05-28T11:44:52Z

@danielskatz Many thanks for the changes, it's merged.

danielskatz · 2020-05-28T12:24:18Z

@whedon accept deposit=true

whedon · 2020-05-28T12:24:21Z

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

whedon · 2020-05-28T12:25:53Z

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

whedon · 2020-05-28T12:25:54Z

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

Here's what you must now do:

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

Any issues? notify your editorial technical team...

danielskatz · 2020-05-28T12:31:38Z

Thanks to @i-mtz, @JoaoRodrigues, @joaomcteixeira for reviewing, and to @lpantano for editing!

And congratulations to @NicoRenaud and co-author!!

whedon · 2020-05-28T12:31:42Z

🎉🎉🎉 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](https://joss.theoj.org/papers/10.21105/joss.02077/status.svg)](https://doi.org/10.21105/joss.02077)

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

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

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: https://joss.theoj.org/reviewer-signup.html
Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

whedon added the review label Feb 6, 2020

whedon assigned lpantano Feb 6, 2020

whedon mentioned this issue Feb 6, 2020

[PRE REVIEW]: The pdb2sql Python Package: Parsing, Manipulation and Analysis of PDB Files Using SQL Queries #2052

Closed

openjournals deleted a comment from whedon Feb 6, 2020

whedon assigned i-mtz Feb 7, 2020

JoaoRodrigues self-assigned this Feb 24, 2020

CunliangGeng mentioned this issue Feb 28, 2020

Solve issue 21-24 and related ones #25

Merged

8 of 8 tasks complete

whedon added the recommend-accept label May 27, 2020

whedon added accepted published labels May 28, 2020

danielskatz closed this May 28, 2020

openjournals / joss-reviews

Sponsor openjournals/joss-reviews

Join GitHub today

[REVIEW]: The pdb2sql Python Package: Parsing, Manipulation and Analysis of PDB Files Using SQL Queries #2077

[REVIEW]: The pdb2sql Python Package: Parsing, Manipulation and Analysis of PDB Files Using SQL Queries #2077

Comments

whedon commented Feb 6, 2020 • edited

Status

Reviewer instructions & questions

Review checklist for @joaomcteixeira

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review checklist for @i-mtz

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review checklist for @JoaoRodrigues

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

whedon commented Feb 6, 2020

whedon commented Feb 6, 2020

arfon commented Feb 6, 2020

whedon commented Feb 6, 2020

lpantano commented Feb 19, 2020

JoaoRodrigues commented Feb 24, 2020

JoaoRodrigues commented Feb 24, 2020 • edited

NicoRenaud commented Mar 6, 2020 • edited

arfon commented Mar 14, 2020

lpantano commented Mar 18, 2020

JoaoRodrigues commented Mar 18, 2020

lpantano commented Mar 18, 2020

arfon commented Apr 13, 2020

JoaoRodrigues commented Apr 13, 2020 • edited

JoaoRodrigues commented Apr 13, 2020

whedon commented Apr 13, 2020

JoaoRodrigues commented Apr 13, 2020

lpantano commented Apr 13, 2020

JoaoRodrigues commented Apr 14, 2020

NicoRenaud commented May 22, 2020

NicoRenaud commented May 27, 2020

lpantano commented May 27, 2020

lpantano commented May 27, 2020

whedon commented May 27, 2020

lpantano commented May 27, 2020

whedon commented May 27, 2020

CunliangGeng commented May 27, 2020 • edited

lpantano commented May 27, 2020

whedon commented May 27, 2020

lpantano commented May 27, 2020

whedon commented May 27, 2020

lpantano commented May 27, 2020

whedon commented May 27, 2020

lpantano commented May 27, 2020

whedon commented May 27, 2020

whedon commented May 27, 2020

whedon commented May 27, 2020

danielskatz commented May 27, 2020

CunliangGeng commented May 28, 2020

danielskatz commented May 28, 2020

whedon commented May 28, 2020

whedon commented May 28, 2020

whedon commented May 28, 2020

danielskatz commented May 28, 2020

whedon commented May 28, 2020

whedon commented Feb 6, 2020 •

edited

JoaoRodrigues commented Feb 24, 2020 •

edited

NicoRenaud commented Mar 6, 2020 •

edited

JoaoRodrigues commented Apr 13, 2020 •

edited

CunliangGeng commented May 27, 2020 •

edited