[RE: JoSS Review] Potential cstag-cli installation issues

[betteridiot]

For the JoSS review at openjournals/joss-reviews/issues/6066

Installation of cstag-cli from cstag-cli/pyproject.toml did not work as intended.

Please see full notes at betteridiot/joss_reviews/blob/master/cstag/joss_review.md

• The issue comes from the requirement of pysam which requires htslib which requires zlib.h. These dependencies are managed well by conda through Bioconda, but cannot be installed as an editable
  repository. While not documented as an intended installation option, I believe that it is important to note. This dependency issue was one of the principal reasons that I wrote bamnostic. It isn't a
  wrapper for htslib, so it has no requirements for it. This also allows it to be installed on any system that can have Python. This isn't a sales pitch though and, by no means, an indictment on htslib
  or pysam. These are terrific packages that serve the community/field in an essential way. But, as of htslib v1.18 on Bioconda, Windows support is still missing.
• More importantly, when regarding this review, cstag-cli's dependencies to pysam (and htslib by assocation) prevent editable installs or installs on systems whereas the user does not have sudo privileges or access
  to conda/mamba since they cannot install zlib.h (easily) without them. Just something to consider.

[betteridiot]

It appears the direct pip install from PyPI has the same issue as above regarding installation dependencies (not surprising). By installing zlib through conda-forge on a system that does not have zlib.h available,
one can overcome this issue and successfully install cstag-cli.

This dependency issue does not rest with your program in any way. It is a product of pysam/htslib dependencies. I also acknowledge that most people in bioinformatics don't often has as sterile of an environment as I do.
I just suspect that there might be some graduate student out there that has only lightly used conda, pip, or any other package manager could potentially be stumped by this.

My suggestion is to make the pysam (and, by extension, htslib) dependencies more explicitly documented on your repo/README.md since these dependencies cannot be address by pip alone. However, they are properly managed
by conda/mamba. While an edge case, it is still a case.

[betteridiot]

I think just documenting the potential issues with the other install pathways may be fully appropriate.

[akikuno]

@betteridiot

Thank you very much for your guidance and instructions regarding installation issues centered around pysam.

I have added to the documentation as follows, and I would be grateful if you could confirm whether this content is sufficient.

README.md

I have made the following additions to the README.md:

• Specified a Unix-like environment (Linux, macOS, WSL, etc.) under Prerequisites
• Added a recommendation for installation via conda instead of pip
• Included a link to troubleshooting.md in case of installation errors

11dd2ca#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5

docs/troubleshooting.md

I have added a troubleshooting.md to the docs:

• Described htslib (zlib.h) as potential causes of installation errors and included notes for when using pip

https://github.com/akikuno/cstag-cli/blob/add-pysam-installation-issue/docs/troubleshooting.md

I would be grateful if you could kindly review them.

[betteridiot]

This satisfies my request. Thank you @akikuno