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

[Robaina]

Submitting Author: Semidán Robaina (@Robaina)
All current maintainers: @Robaina
Package Name: Pynteny
One-Line Description of Package: Query sequence database by HMMs arranged in predefined synteny structure
Repository Link: https://github.com/Robaina/Pynteny
Version submitted: v0.0.5
Editor: @arianesasso
Reviewer 1: @Batalex
Reviewer 2: @c-thoben
Archive:
JOSS DOI:
Version accepted: 1.0.0
Date accepted (month-day-year): 03-10-2023

---

Description

• Include a brief paragraph describing what your package does:j

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)

Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see notes on categories of our guidebook.

• For all submissions, explain how and why the package falls under the categories you indicated above. In your explanation, please address the following points (briefly, 1-2 sentences for each):

• 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.

• 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 the extent of my knowledge, there isn't any Python package that provides the functionality provided by Pynteny.

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussions or @tag the editor you contacted: Pynteny: a Python package to perform synteny-aware, profile HMM-based searches in sequence databases #65

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has an OSI approved license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others: GitHub Action

Publication options

I had submitted this package for publication at JOSS prior to pyOpenSci. The submission is currently under consideration for scope in this issue: openjournals/joss-reviews#4978

• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI:

Note: Do not submit your package separately to JOSS

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text-based review. It will also allow you to demonstrate addressing the issue via PR links.

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Code of conduct

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

Please fill out our survey

• Last but not least, please fill out our pre-review survey. This helps us track
  submissions and improve our peer review process. We will also ask our reviewers
  and editors to fill this out.

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

Editor and Review Templates

[Editor and review templates can be found here]: https://www.pyopensci.org/software-peer-review/how-to/editors-guide.html and https://www.pyopensci.org/software-peer-review/how-to/reviewer-guide.html

[NickleDave]

Thank you @Robaina for submitting Pynteny to pyOpenSci. As you noted, we have already discussed on #65 and you have done extensive development to prepare for submission.

Here are the initial editor checks:

• Fit: The package meets criteria for fit and overlap.
  • As discussed in Pynteny: a Python package to perform synteny-aware, profile HMM-based searches in sequence databases #65 scope here includes data extraction and I think also data retrieval, and the package can and has been used for educational purposes. I additionally checked "retrieval" and "education" above
• Documentation The package has sufficient documentation available online (README, sphinx docs) to allow us to evaluate package function and scope without installing the package. This includes:
  • tutorials or vignettes that help a user understand how to use the package and what it can do for them (often these have a name like "Getting started")
    • see e.g. https://robaina.github.io/Pynteny/examples/example_cli/
  • API documentation - this includes clearly written doc strings with variables defined using a standard docstring format
  • README that clearly articulates the function of the package
  • Contributing documentation that details how to install a development environment and how to contribute to the package
    • there is not a separate contributing page yet but there is a section in the README: environment
• Issue Submission Documentation: All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
  • Will need to update version, editor, reviewers
• Automated tests: Package has a testing suite and is tested via GitHub actions or another Continuous Integration service.
• License: The package has an OSI approved license
  • Uses Apache license
• Repository: The repository link resolves correctly
• README: The package has a README with clear explanation of what the package does and instructions on how to install it along with development instructions.
• Contributing statement: The package has a contributing.md file that details how to contribute to the package.
  • Not yet, see above
• Package overlap: That package doesn't fully overlap with functionality of other packages that have already been submitted to pyOpenSci
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)? JOSS in version 1.1.0

---

• Initial onboarding survey was filled out
  We appreciate each maintainer of the package filling out this survey individually. 🙌
  Thank you authors in advance for setting aside five to ten minutes to do this. It truly helps our organization. 🙌

---

---

Editor comments

The author has done a ton of work to get ready for submission. Pynteny is looking really good. We will need a contributing.md before the review finishes but that's the only thing I really see missing right now.

Thank you again @Robaina.
We will get an editor and reviewers as soon as possible.
I need to confirm timelines with @lwasser but I would expect it might take a bit longer because of the holidays, my guess is two weeks.
Will let you know for sure by the end of this week, but wanted to make sure you knew we have seen your submission and we are beginning the review.

[Robaina]

Hi @NickleDave,

thanks for accepting the submission! I have included a "CONTRIBUTING.md" in the root directory of the repo, also moved instructions on how to set a developer environment to that file. Looking forward to the review process -- Btw, I think I did fill out the initial onboarding survey, please confirm.

Best,
Semidán

[NickleDave]

Perfect, thank you Semidán!

Following up on my last message: we do expect to get review started within the next two weeks. People are off-line because of the holidays but we will get the ball rolling now.

[arianesasso]

Dear @Robaina, nice to meet you!

I just wanted to say hi 👋🏼 and inform you that I am pleased to be the editor for this review.
I see that you and @NickleDave already did great work during the pre-submission phase!
We are recruiting the reviewers now, and I will update you once they are onboard.

[Robaina]

Hi @arianesasso, nice to meet you too!

Awesome. Thanks for letting me know and for being the editor. Looking forward to the review! (und guten Rutsch ins neue Jahr)

[arianesasso]

Dear Robaina,

I hope you had a great start to the year as well! I am sorry for the delay. We are still looking for our second reviewer.

However, I would like to introduce you to @Batalex, who is already on the job as the first reviewer 😄 . We have previously talked about the package, and he already has access to the reviewer's guide, the reviewer template, and the Python packaging standards detailed in the packaging guide. So, we will be able to continue moving 🚀 .

And please feel free to ping me at any time if you need help or have questions!

[Robaina]

Hi @arianesasso,

no problem, thanks for the update :) Hi @Batalex, thanks the review!

[Batalex]

Hey there! I am almost done with my review. No promises, but I think I can deliver this weekend.
Looking forward to discussing it with you! 🙌

[Batalex]

Here comes a big one! @Robaina @arianesasso

Foreword

I want to thank both the author and the editors from pyOpenSci for the opportunity to tackle this package review. The following comments reflect my experience as I maintain private packages, and all remarks come with pynteny's best interest at heart.

Some comments are regrouped at a "general" level if they concern the project structure or several files. If I encountered a situation that I had already pointed out on another file, I did not comment again. However, I encourage taking into account the remarks from one file to the others.

Several comments I made are only valid for the submitted version (0.0.5) and were fixed in the meantime. Nonetheless, I will mark off what has been done later.

With that being said, let us get started!

I used the black cat🐈‍⬛ to highlight my personal thoughts in the review template below.

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README.
• Installation instructions: for the development version of the package and any non-standard dependencies in README.

🐈‍⬛ The submitted version uses a personal conda channel in README, which is something I would not recommend. However, it uses bioconda in the main branch, so it is all good.

• Vignette(s) demonstrating major functionality that runs successfully locally.

🐈‍⬛ There are some improvements to be made regarding running the examples locally, see below.

• Function Documentation: for all user-facing functions.
• Examples for all user-facing functions.
• Community guidelines including contribution guidelines in the README or CONTRIBUTING.

🐈‍⬛ In Pynteny 0.0.5, contributions guidelines are included in the README file. A more detailed CONTRIBUTING file has been added since then.

• Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a pyproject.toml file or elsewhere.

🐈‍⬛ I noticed that two of the three links to the Pynteny repo use the HTTP scheme, and the third uses HTTPS.

Readme file requirements
The package meets the readme requirements below:

• Package has a README.md file in the root directory.

The README should include, from top to bottom:

• The package name
• Badges for:
• Continuous integration and test coverage,
• Docs building (if you have a documentation website),
• A repostatus.org badge,
• Python versions supported,
• Current package version (on PyPI / Conda).

🐈‍⬛ Additional badges have been added since the 0.0.5 release.

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the a badge for pyOpenSci peer-review will be provided upon acceptance.)

• Short description of package goals.
• Package installation instructions
• Any additional setup required to use the package (authentication tokens, etc.)
• Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.
• Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)
• Link to your documentation website.
• If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.
• Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
Package structure should follow general community best-practices. In general please consider whether:

• Package documentation is clear and easy to find and use.
• The need for the package is clear
• All functions have documentation and associated examples for use
• The package is easy to install

🐈‍⬛ I ran the package in WSL since Apple silicon is not supported. The installation went smoothly, except for the really long resolution time. I am glad to see that the main branch encourages to use mamba.

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.

🐈‍⬛ As far as I can tell, it seems to do what it claims.

• Performance: Any performance claims of the software been confirmed.

🐈‍⬛ NA, no performance claim to be found in the documentation.

• Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.

🐈‍⬛ Tests covers 45% of pynteny. The coverage is heterogenous: the application and CLI parts of the package are less tested than the rest.

• Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)

🐈‍⬛ Unit tests did not run on CI as of 0.0.5. This has changed since then. The documentation website is built and deployed using CI, nice!

• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.
  A few notable highlights to look at:
• Package supports modern versions of Python and not End of life versions.
• Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

🐈‍⬛ The code base does not fully follow PEP 8. See below for more information.

For packages also submitting to JOSS

• The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: ~8 hours

---

Review Comments 🐈‍⬛

General comments:

• The package is very well laid out and easy to navigate.
• I would encourage the author to follow the stylistic style guide defined by the PEP8. The most immediate benefit this would provide to the code base is consistency with the rest of the Python ecosystem and a lower entry bar for potential contributors. Two easy fixes to apply in this code base are:
• Using a code formater such as black.
• Using snake_case to name functions and methods rather than camelCase
• Another suggestion would be to use a .editorconfig file. There again, this is a simple way to enforce consistency in the code base by defining a few options to control the files’ format. This is especially true for Python projects since mixing tabs and spaces would crash the program. There are other benefits as well, e.g., removing trailing spaces and adding new lines at the end of files.
• There are a few discrepancies in types, some of them could be fixed by converting argparse.ArgumentParser instances to CommandArgs before using them
• Empty parentheses in class definitions without inheritance are not necessary.
• “magic values” (such as lists of columns) could be defined at the module level rather than in the class/function definition, but I am nitpicking.
• My personal recommendation is to define the text encoding whenever a text file descriptor is opened. Even if this is not feasible at the moment, this is a tiny step toward Windows compatibility, and it removes a little bit of uncertainty.
• There are a lot of places where the author uses classes with only static methods and no attributes. This adds an unnecessary layer of complexity to the code base, where one could simply define functions in their dedicated file if keeping the namespace clean is important.
• With the author's permission, I would be glad to provide a simple, sensitive configuration to get started with a few quality code tools.

CLI

• The defaults paths are quite inconvenient if I run the cli from the installed package rather than the source directory, the config file as well as the downloaded database ends up in /home/<user>/miniconda3/envs/Pynteny/lib/python3.10/site-packages/

  Documentation

  • I recommend adding "Installation" & "Getting Started" sections in the documentation. The rationale is as follows: any part of the project may be a potential user's first contact. This includes the README file, the package description on Pypi (not applicable here) / a conda channel, and the documentation.

  • I would advise adding instructions on how to locally build the documentation in CONTRIBUTING.md in the section 3

  • The following mention is incorrect in the example notebook:

  To follow this example, you don't need to download _E. coli's_ genome, since it has been already downloaded during Pynteny's installation.

  The MG1655.gb file is stored in the tests folder, which is not included in the package. Therefore, when the package is installed using conda, it is not downloaded.

  pynteny/init.py

  • import * are usually frowned upon in Python, but IMO this is ok in this case

  pynteny/api.py

  • importlib.metadata is only available in the standard library from 3.8 and onwards (3.7 is technically allowed in 0.0.5). This is partially fixed in the main branch. For good measure, I would increase the minimum Python version in the pyproject.toml file as well, even if poetry is only used as a build backend.
  • The author could use a simple type hint in the Command class to avoid a linter warning in the update method:

  class Command():
  """Parent class for Pynteny command
  """
  _args: CommandArgs

  • Empty __init__ methods are not necessary, the smaller the code base the better!
  • 🔥There are really nice uses of the package’s metadata in _repr_html_ and cite
  • I am pleased to see that arguments with None default value are correctly typed as optional
  • There is no need to wrap Path(__file__).parent in another Path() in the getTestDataPath method since it returns a Path object as well. This comment applies to utils.py as well.

  pynteny/cli.py

  • args is not used in the Pynteny.app method, so there is no need to parse it.
  • I believe getHelpStr could be simpler by writing to an io.StringIO instead of a temp file.
  • f-strings without placeholder are considered code smells
  • Overall, this is a really nice example of a cli with subcommands, congrats!
  • I saw a few unused required and pynteny assignment

  pynteny/filter.py

  • typo L40 specified
  • As far as I can tell, the hmm_order_dict is not needed in SyntenyPatternFilters init method.
  • The lambda expr + map is quite difficult to read. A simpler alternative could be:

  strand_map = dict(neg=-1, pos=1) # could be set as a module-wide constant
  self.strand_order_pattern = [strand_map.get(strand, 0) for strand in parsed_structure["strands"]]

  • contains_hmm_pattern, contains_distance_pattern, and contains_strand_pattern could use Python’s idioms and return boolean values instead of integers, this is not an issue with their use in pandas rolling method. Boolean values can be aggregated numerically in pandas. This would simplify those methods. In contains_strand_pattern, there is a True equality comparison.
  • Using inplace=True in pandas operation is not recommended and could be deprecated: API/DEPR: Deprecate inplace parameter pandas-dev/pandas#16529.
  • The author could use the size method instead of a filter with a lambda in getAllHMMhits, but this is a matter of preference.
  • There again, preferences, but the loop in filterHitsBySyntenyStructure could be made on a pandas’ groupby object. This is not a prominent feature, but one may do the following:

  for group_key, group_df in df.groupby(key):
  pass

  • the form len(contig_hits.hmm.unique()) could be simplified to contig_hits.hmm.nunique()
  • Using iterrows is quite inefficient if one only need to loop over the index. The author may use for i in matched_rows.index
  • Idiomatic Python does not usually use getter methods such as getSyntenyHits, a public attribute would work just fine.
  • I have not profiled the code to see if there is a performance bottleneck there, but I would use itertuples instead of iterrows in addHMMmetaInfoToHits. itertuples is much faster if you need to iterate over data frames one row at a time
  • I suggest using isinstance rather than type equality in filterFASTAbySyntenyStructure. isinstance is a more robust (and marginally faster) solution because it allows nominal subtyping: any subtype of str or list would pass the test conditions. Using isinstance is therefore considered more pythonic than type equality.

  pynteny/hmm.py

  • Nice use of properties
  • Since the author is using pathlib, they might use / or Path.joinpath instead of os.path.join
  • The author may use the usecols argument for pd.read_csv
  • Why is thetry-except block needed in getHMMnamesByGeneSymbol? (+ bare except is considered a code smell). The code would work without this. The same goes for getHMMgeneID, with a little twist to return None, and for getMetaInfoForHMM

  pynteny/parser.py

  • The two classes in this file only use static methods and do not hold any attribute. Is there a reason for not replacing all those methods with simple functions?
    Edit: even preprocessing.py does isLegitSequence = RecordSequence.isLegitPeptideSequence
  • There are too many statements in the try-except block in LabelParser.parse. I do not know what could be failing (a split, an int cast?), and the exception caught is too broad. Tip: I suggest extracting meta.split("_") in a variable since it appears in four lines in a row
  • Typing tuples is quite unintuitive: tuple[str] means “a tuple of exactly one str.” This means that splitStrandFromLocus is incorrectly typed

  pynteny/preprocessing.py

  • In FASTA class, we could replace the getter/setter with a property, which is more “pythonic”. Moreover, we could also make _input_file_str a read-only property.
  • I would prefer if the inner function unique_records was defined outside the removeDuplicates method. I understand that the purpose is to generate the records lazily, which could still work as intended.
  • number_prodigal_record_fields could be a global constant
  • There again with fromGenBankData, I think the three inner functions would be better off defined outside the method. Contrary to the previous time, they do not use self and are even easier to extract. This change would reduce fromGenBankData complexity and make it even easier to debug.
  • If pynteny targets python ≥3.10 as the main branch suggests, then it may use https://docs.python.org/3/whatsnew/3.10.html#parenthesized-context-managers in GeneAnnotator

  pynteny/subcommands.py

  • There is a piece of code duplicated four times. The following could be extracted in its own function.

  if args.logfile is None:
  args.logfile = Path(os.devnull)
  elif not Path(args.logfile.parent).exists():
  Path(args.logfile.parent).mkdir(parents=True)
  logging.basicConfig(format='%(asctime)s | %(levelname)s: %(message)s',
  handlers=[
  logging.FileHandler(args.logfile),
  logging.StreamHandler(sys.stdout)
  ],
  level=logging.NOTSET)
  logger = logging.getLogger(__name__)

  In addition, this would limit the complexity of synteny_search

  • wget is quite old and does not seem to be active. How about replacing it with a more maintained alternative? e.g. httpx, requests
  • As I said in the general comments, I would prefer if the default dirs were not relative to the package files. When installing pynteny inside a virtual env, this means that the database could be downloaded inside the venv, in a totally different place from the current working dir. I suggest using ~/.pynteny

  pynteny/utils.py

  • As I said in the comments above, using the file location is quite inconvenient because when installed by conda it ends up in the venv directory
  • Is there a reason for not using https://docs.python.org/3/library/tarfile.html?highlight=tar#tarfile.is_tarfile?

  pynteny/wrappers.py

  • ✅

  pynteny/app

  • The embedded streamlit app is really cool 🔥
  • There again, it seems a bit odd to have classes with only static methods

Edits

• crossed items to mark progression toward completion, then uncrossed for ease of read once everything was addressed