Pynteny: a Python package to perform synteny-aware, profile HMM-based searches in sequence databases

[Robaina]

Submitting Author: Semidán Robaina (@Robaina)
Package Name: Pynteny: a Python package to perform synteny-aware, profile HMM-based searches in sequence databases
One-Line Description of Package: Query sequence database by HMMs arranged in predefined synteny structure
Repository Link (if existing): https://github.com/Robaina/Pynteny

---

Description

• Include a brief paragraph describing what your package does:

Pynteny is Python tool to search for synteny blocks in (prokaryotic) sequence data through HMMs of the ORFs of interest and HMMER. By leveraging genomic context information, Pynteny can be employed to decrease the uncertainty of functional annotation of unlabelled sequence data due to the effect of paralogs. Pynteny can be accessed (i) through the command line, (ii) as a Python module or (iii) as a (locally served) web application.

Scope

• Please indicate which category or categories this package falls under:

  • Data retrieval
  • Data extraction
  • Data munging
  • Data deposition
  • Data visualization
  • Reproducibility
  • Geospatial
  • Education
  • Unsure/Other (explain below)

• Explain how and why the package falls under these categories (briefly, 1-2 sentences). Please note any areas you are unsure of:

Pynteny's main objective is to provide a means to query NGS (unannotated) sequence databases, such as metagenomic/metatranscriptomic datasets using syntenic blocks (i.e. spatial arrangements of genes) rather than single target genes/protein domains. In this sense, I would classify Pynteny within Data Extraction.

On the other hand, Pynteny can also be employed in microbiology / genetic courses. To this end, it provides a web graphical interface (Streamlit app) to facilitate interaction. We have successfully employed Pynteny in some of our microbiology courses at the University of La Laguna. Hence, I think tagging Pynteny within "Education" may be appropriate.

• Who is the target audience and what are the scientific applications of this package?

Pynteny was designed to be used by researchers working with large, unannotated sequence databases, such as those typically encountered in metagenomic analyses. It can be accessed through a command line interface or easily integrated into pipelines as a Python package. Pynteny can also be used through a graphical interface running locally in the browser, which is more suitable for educational purposes.

• Are there other Python packages that accomplish similar things? If so, how does yours differ?

To extent of my knowledge, there isn't any Python package that provides the functionality provided by Pynteny.

• Any other questions or issues we should be aware of:

I submitted this package for publication at JOSS a few days back. The submission is currently under consideration for scope.

P.S. *Have feedback/comments about our review process? Leave a comment here

[Robaina]

Hello, I would like to submit the package described above to pyOpenSci. Not sure if it fits your scope. Thanks!

[NickleDave]

Hi @Robaina and welcome to pyOpenSci!

Thank you for filling out the submission in a detailed thoughtful way.
My initial impression is that, yes, Pynteny is in scope for pyOpenSci.
I agree that it falls under the heading of the "data extraction" in the sense that Pynteny allows users to query a database with HMMs.

I submitted this package for publication at JOSS a few days back.

We should coordinate with them. Our review processes are complementary. So far we've usually done the pyOS review first and then we pass off to JOSS. For example, see discussion on the pyGMT review here: #43 or the completed devicely review: #37

If that makes sense, please let me know, and please reference this issue on the open JOSS review issue.

I will need to do more detailed editor checks but I wanted to welcome you and give you an initial answer as soon as possible. I will follow up tomorrow. Thank you @Robaina!

[Robaina]

Hi @NickleDave ,

thank you! I'm looking forward to being part of the pyOpenSci community :)

We should coordinate with them. Our review processes are complementary. So far we've usually done the pyOS review first and then we pass off to JOSS. For example, see discussion on the pyGMT review here: #43 or the completed devicely review: #37

Excellent. Yes, that makes sense, I'll reference this issue in the open JOSS review issue.

I will need to do more detailed editor checks but I wanted to welcome you and give you an initial answer as soon as possible. I will follow up tomorrow. Thank you @Robaina!

Thank you. I recently learned about pyOpenSci and JOSS and feel very aligned with your values regarding open source and scientific development. Would be happy to help.

[NickleDave]

I'm looking forward to being part of the pyOpenSci community :)

Glad to hear it 🙌

I'll reference this issue in the open JOSS review issue.

I saw you commented there, thank you. I should have made it more clear, typically we review first so you do not need to go through two reviews. @lwasser asked me to clarify. I will comment on that review and link for the editor so they're aware.

On my to-do list to do more thorough checks later!

[NickleDave]

Hi again @Robaina I am familiarizing myself with the project a little more before I ask you to make a full submission; I want to make sure I understand how it works.

Good things:

• the README looks good overall, it has all the sections we would expect, and the badges and images are both helpful and make the README attractive and interesting
• Your docs look great and so do the examples.

Some feedback:

• We would want the docs to be a Sphinx site, not a wiki, as stated in our editor checks here although overall the docs are very readable. I would also recommend copying example snippets of using the cli so they are one of the very first things a potential user sees on your README; they should know immediately what the interface actually looks like
• We would definitely want you to use a pyproject.toml that declares your dependencies as metadata, instead of the deprecated setup.py approach. Ideally with new-style metadata as described in the flit docs: https://flit.pypa.io/en/stable/pyproject_toml.html#new-style-metadata. For more on why we require a pyproject.toml, see this post from Titus Brown, and this much more detailed post from Paul Anzel.
• Part of the purpose of pyOpenSci is to standardize project structure; there's no right answer but it is definitely uncommon to see a directory with the package name that then has a src/ directory inside of it. Usually you would either just have your source code in pynteny or you would have src/pynteny. See this post: https://hynek.me/articles/testing-packaging/. Similarly, while people do sometimes have tests along code, it's often preferable to completely isolate your tests so you know they are testing installed code. I would suggest switching to src/pyntenty or pynteny and moving your tests to the project root.
• Right now if I'm not mistaken it looks like you are limited to conda because that's the only way you can inspire HMMER? Is that correct? More about this below

Questions:

• Can you explain how pynteny compares to PyHMMER? Is there overlap in functionality there?
  https://pyhmmer.readthedocs.io/en/stable/
  Partly I ask because the developers of HMMER and PyHMMER are potential reviewers.
• I'm also asking about PyHMMER because it looks like you might be able to declare it as a dependency, so that your package would not be limited to only conda and Linux users; PyHMMER is pip installable so Pynteny would be pip installable as well. They appear to have some docs for developers here: https://pyhmmer.readthedocs.io/en/stable/examples/index.html

[Robaina]

Hi @NickleDave,

thank you for your careful first review of the project, here are my thoughts:

• We would want the docs to be a Sphinx site, not a wiki, as stated in our editor checks here although overall the docs are very readable. I would also recommend copying example snippets of using the cli so they are one of the very first things a potential user sees on your README; they should know immediately what the interface actually looks like

That makes sense. Will port the wiki to a Sphinx site. I agree on including cli snippets!

• We would definitely want you to use a pyproject.toml that declares your dependencies as metadata, instead of the deprecated setup.py approach. Ideally with new-style metadata as described in the flit docs: https://flit.pypa.io/en/stable/pyproject_toml.html#new-style-metadata. For more on why we require a pyproject.toml, see this post from Titus Brown, and this much more detailed post from Paul Anzel.

Will do. A good opportunity to finally get rid of the deprecated setup.py.

• Part of the purpose of pyOpenSci is to standardize project structure; there's no right answer but it is definitely uncommon to see a directory with the package name that then has a src/ directory inside of it. Usually you would either just have your source code in pynteny or you would have src/pynteny. See this post: https://hynek.me/articles/testing-packaging/. Similarly, while people do sometimes have tests along code, it's often preferable to completely isolate your tests so you know they are testing installed code. I would suggest switching to src/pyntenty or pynteny and moving your tests to the project root.

Yeah, actually I wasn't following any standard structure in the project. Seems reasonable to change it to what you suggest.

• Right now if I'm not mistaken it looks like you are limited to conda because that's the only way you can inspire HMMER? Is that correct? More about this below

It started like that, yes. Pynteny also depends on Prodigal, which is available in bioconda. I made wrappers for both to be run within Pynteny. Although providing a wrapper was more of a necessity rather than a designed functionality back then.

However, I have checked and there is a python binding to prodigal, which is pip installable: Pyrodigal. All other dependencies are also both pip and conda installable, so I could make Pynteny also pip installable by switching from using HMMER and Prodigal to using PyHMMER and Pyrodigal. I would have to delve into it since I believe that PyHMMER and HMMER output formats are structured differently.

I plan to submit Pynteny to the bioconda channel since it is dedicated to software within the biological sciences. Bioconda would make Pynteny available for MacOS as well as Linux, but not for Windows (that is, outside using WSL). However, I think that it is worth trying PyHMMER and Pyrodigal so I can make Pynteny also pip installable and potentially usable also in Windows without WSL

Questions:

• Can you explain how pynteny compares to PyHMMER? Is there overlap in functionality there?
  https://pyhmmer.readthedocs.io/en/stable/
  Partly I ask because the developers of HMMER and PyHMMER are potential reviewers.

Currently, Pynteny provides a simple CLI wrapper to HMMER (contrary to the sophisticated interface provided by PyHMMER). This is not the main functionality of Pynteny (and could be entirely removed by using PyHMMER instead of HMMER).

Pynteny uses HMMER (potentially PyHMMER) as a tool to run sequence profile HMM searches, which is a step required to then filter those searches by the syntenic structure provided by the user. So, to clarify, these would be the main functionalities provided by Pynteny:

1. Construct a peptide database from DNA assembly data in which peptide labels contain positional information (gene number within contig / chromosome, and contig name). DNA translation to peptide sequences is carried out by Prodigal / Pyrodigal.

2. Search the peptide database by a predefined syntenic structure (i.e., gene spatial arrangement) using profile HMMs. Here, HMMER / PyHMMER is employed to search the peptide database for every gene/HMM in the provided syntenic structure. Pynteny would then take into account the positional information and the syntenic structure (including additional optional constraints like DNA strand specificity and alternative HMMs for the same gene) to filter HMMER results and retain only those sequence hits that are aligned with the provided syntenic structure.

3. Additionally, Pynteny facilitates downloading a large profile HMM database (PGAP) as well as "translating" a syntenic structure defined with gene symbols to another one containing matching profile HMMs from the PGAP database.

• I'm also asking about PyHMMER because it looks like you might be able to declare it as a dependency, so that your package would not be limited to only conda and Linux users; PyHMMER is pip installable so Pynteny would be pip installable as well. They appear to have some docs for developers here: https://pyhmmer.readthedocs.io/en/stable/examples/index.html

See my answers above.

---

Hope my comments help clarify Pynteny's functionality. Please, don't hesitate to ask any further questions.
Thanks!

[Robaina]

I'm looking forward to being part of the pyOpenSci community :)

Glad to hear it raised_hands

I'll reference this issue in the open JOSS review issue.

I saw you commented there, thank you. I should have made it more clear, typically we review first so you do not need to go through two reviews. @lwasser asked me to clarify. I will comment on that review and link for the editor so they're aware.

On my to-do list to do more thorough checks later!

Yes, that was clear to me. Sorry, I should have explicitly stated this in the referenced issue at JOSS like you did.

[lwasser]

@Robaina so so psyched to have you here. Just a note that if you need help with any of the above items we are happy to support you. you can post questions here in this issue OR on discourse if you wish. I just went through updating a package with docs and pyproject.toml and found that the online documentation was a bit confusing so just reach out if you have questions!

in the future we will have better documentation to support making changes like the ones discussed above!

[Robaina]

Hi @lwasser,

thanks! You and @NickleDave have been very supportive. Alright, I'll try discourse as it may help future developers.

[Robaina]

Hi @NickleDave,

I have thought about relocating the tests directory to root as you suggested. While I see the advantages you listed by locating tests there, I'm not entirely convinced that this is the best option in this case. This is because currently tests are installed (as a subpackage) alongside pynteny and can be run with the subcommand Pynteny tests, which I think it's a nice functionality for users to check that installation went fine. I am not sure I want to get rid of this functionality to favor locating tests outside of the installation. Does this make sense to you?

[NickleDave]

Hi @Robaina thank you so much for your clear answers and for being open to feedback.

Your response makes me more confident Pynteny is in scope, since it also includes data retrieval, and my understand that it leverages functionality from both HMMER and Prodigal to provide a unique ability to query a peptide database with HMMs. Aside: do you have a sort of workflow diagram in your docs that captures this description, including which dependency does what? Might be helpful

Before we make a final decision, I just want to get a little feedback from devs in bioinformatics and genomics--I have asked in our Slack--but I am 90% sure we will ask you to go ahead with a submission. (I should have asked them before, I am sorry for not doing so in the first place.)

In the meantime, could I ask you to track any changes you are making as a result of this presubmission as issues, and then reference those issues on any submission? @lwasser may modify our survey as well to make sure we capture that (we are still figuring out process as we come back on line).

So far we have (correct me if I'm wrong):

• switch docs to Sphinx (I highly highly suggesting using myst, by the way, if you weren't already)
• restructure project: make docs/, src/ and tests/ folders (more on this below, I did see your question)
• test whether you can depend on PyHMMER and Pyrodigal to enable a pip-only build (that probably makes it easier and more reliable in the long run to generate packages for bioconda and conda-forge e.g. with grayskull)

[NickleDave]

re: keeping tests in docs

This does not affect our decision on a submission; we don't have any hard and fast rules right now about where test should be. As a developer I totally understand why you want to keep them there. The reasons I would suggest moving them out are
(1) you want to ideally isolate tests from source and run on an installed build (even if you don't do so during day-to-day development),
(2) it's great that you care about your users but most of them won't be developers and won't care about running tests, and the ones that do care will know how to clone your repo and run tests the usual way
(3) I'm not sure what running tests gives users unless you have a lot of edge cases that you need them to report to you about, and even in that case it might be better to add a helper function that dumps out env info to the terminal that they can paste into issues with an error message. I did look at your tests but nothing jumps out at me that makes me think you are often needing it to be in with the code

Most recent updated guides I know suggest putting tests in a separate directory:
https://docs.python-guide.org/writing/structure/
https://py-pkgs.org/05-testing
https://packaging.python.org/en/latest/tutorials/packaging-projects/#a-simple-project
https://cjolowicz.github.io/posts/hypermodern-python-02-testing/
https://doc.pytest.org/en/latest/explanation/goodpractices.html#tests-outside-application-code
https://github.com/pypa/sampleproject

Does that help?

[Robaina]

Hi @NickleDave ,

Your response makes me more confident Pynteny is in scope, since it also includes data retrieval, and my understand that it leverages functionality from both HMMER and Prodigal to provide a unique ability to query a peptide database with HMMs. Aside: do you have a sort of workflow diagram in your docs that captures this description, including which dependency does what? Might be helpful

Excellent! Regarding the diagram: I could do a simple one and include it in the index page of the docs.

Before we make a final decision, I just want to get a little feedback from devs in bioinformatics and genomics--I have asked in our Slack--but I am 90% sure we will ask you to go ahead with a submission. (I should have asked them before, I am sorry for not doing so in the first place.)

Alright, no problem. I'll wait for the final decision.

In the meantime, could I ask you to track any changes you are making as a result of this presubmission as issues, and then reference those issues on any submission? @lwasser may modify our survey as well to make sure we capture that (we are still figuring out process as we come back on line).

I already made some changes, but I can do that from now on.

So far we have (correct me if I'm wrong):

• switch docs to Sphinx (I highly highly suggesting using myst, by the way, if you weren't already)

Yeah, so I'll try myst as per your suggestion. Ideally, I want to use the same markdown files I already made but I think that shouldn't be a problem.

• restructure project: make docs/, src/ and tests/ folders (more on this below, I did see your question)

This is already been taken care of. Thanks for your comments about tests. Makes sense. I have relocated "tests" outside the package and removed "Pynteny tests" subcommand.

• test whether you can depend on PyHMMER and Pyrodigal to enable a pip-only build (that probably makes it easier and more reliable in the long run to generate packages for bioconda and conda-forge e.g. with grayskull)

I have this in mind and will definitely test those packages. However, I do have a question: would making Pynteny pip-installable be a requisite for consideration at pySciOpen? Or rather a desirable change that I could do later on?

Thank you for all your suggestions. They have definitely been very helpful