Update of README. #170

mikerobeson · 2024-01-12T21:50:48Z

It's been a while since we've updated the README. My proposed changes are in this PR. This was motivated by this forum thread.

nbokulich

Thanks @mikerobeson ! Indeed, this readme needs a good dusting off 😁

I have a few minor comments in-line, but overall my primary thoughts are about the install instructions. It would be nice to simplify the install instructions, as installation is not as complicated now as it was before.

RESCRIPt is already included in the shotgun distro, so a very easy installation instruction could just be to install that distro. We could drop the alternative options and just redirect to the install instructions for that distro.

I think RESCRIPt is also going to be added to the amplicon distro in the next release — is that correct, @lizgehret? Or in a future release.

nbokulich · 2024-01-13T07:43:07Z

README.md

@@ -20,7 +20,7 @@ First create a conda environment and install relevant dependencies:
 conda create -y -n rescript
 conda activate rescript
 conda install \
- -c conda-forge -c bioconda -c qiime2 -c https://packages.qiime2.org/qiime2/2023.5/tested/ -c defaults \
+ -c conda-forge -c bioconda -c qiime2 -c https://packages.qiime2.org/qiime2/2023.7/tested/ -c defaults \


you install 2023.7 here, but then mention 2023.9 below. Why not just use the latest?

I wanted to highlight two ways to install RESCRIPt, as many of the recent versions can be installed as we've been doing. But not so with 2023.9...

I also figured, we'd not merge this PR until just before the next release anyway. This will serves as our scratch space. :-)

okay good point, and I like the idea of keeping install instructions for pre-2023.9, but maybe we should change the header line accordingly

README.md

nbokulich · 2024-01-13T07:54:04Z

README.md

+qiime rescript --help
+```
+
+#### NOTE on installing RESCRIPt within `qiime2-amplicon-2023.9`: 


I think this will already change in the next release...

Yeah, but will this work for 2023.9 though? If not, we'll have to keep this note for that version right?

nbokulich

Thanks @mikerobeson !

See my two comments inline. I like your idea to include install instructions for 2023 releases. But I still find it a little confusing to show instructions for both 2023.7 and 2023.9.

Maybe starting 2023.9 as the primary installation instructions we recommend that people install the shotgun distro to use RESCRIPt? And they can also switch environments if they want to use this with amplicon data. That will change in the next release anyway, when I think that it will also be in the amplicon distro. So per your comment about merging this PR shortly before the next release I suggest that you already update the README to reflect the situtation in 2024.2. Does that sound okay?

nbokulich · 2024-01-15T11:30:18Z

README.md

@@ -20,7 +20,7 @@ First create a conda environment and install relevant dependencies:
 conda create -y -n rescript
 conda activate rescript
 conda install \
- -c conda-forge -c bioconda -c qiime2 -c https://packages.qiime2.org/qiime2/2023.5/tested/ -c defaults \
+ -c conda-forge -c bioconda -c qiime2 -c https://packages.qiime2.org/qiime2/2023.7/tested/ -c defaults \


okay good point, and I like the idea of keeping install instructions for pre-2023.9, but maybe we should change the header line accordingly

nbokulich · 2024-01-15T11:30:38Z

README.md

@@ -31,17 +31,36 @@ pip install git+https://github.com/bokulich-lab/RESCRIPt.git
 ```

 ### Option 2: Install within QIIME 2 environment


say "before version 2023.9"?

I assume the install instructions for 2024.2 are going to be largely similar to 2023.2 - 2023.7 right? That is pointing to a .../202X.Y/tested/ folder? If so, I think labelling as 'before' or 'after' 2023.9 might be confusing, as that is the only odd ball. Which is why I set it up as a note for 2023.9. 🤷 I can add the note about installing the shotgun distro too.

Also, this makes me think... should we add instructions for older versions, 2022.8 and earlier? Or would that just make things more confusing? I figure no, as folks can ask for help with older versions.

Oh wait I forgot, pre- 2023.9 the tested folders will be https://packages.qiime2.org/qiime2/2023.7/tested/ whereas 2024.2 will be: https://packages.qiime2.org/qiime2/2024.2/amplicon/released/. So, the pre- post labeling will work. :-)

lizgehret · 2024-01-16T17:19:45Z

Thanks @mikerobeson ! Indeed, this readme needs a good dusting off 😁

I have a few minor comments in-line, but overall my primary thoughts are about the install instructions. It would be nice to simplify the install instructions, as installation is not as complicated now as it was before.

RESCRIPt is already included in the shotgun distro, so a very easy installation instruction could just be to install that distro. We could drop the alternative options and just redirect to the install instructions for that distro.

I think RESCRIPt is also going to be added to the amplicon distro in the next release — is that correct, @lizgehret? Or in a future release.

Sorry for the delayed response @nbokulich! Yes, we're aiming to get RESCRIPt in the amplicon distro in this upcoming release - which I think should be doable because @hagenjp will be working on moving all of the types/formats/etc from q2-types-genomics over to q2-types.

mikerobeson · 2024-01-18T16:26:03Z

I just put up another draft of the README. Still a work in progress, but wanted to put forth some ideas on how to clarify installation, etc. :-)

lizgehret · 2024-01-18T18:57:40Z

README.md

- xmltodict 'q2-types-genomics>2023.2' ncbi-datasets-pylib
+conda activate qiime2-amplicon-2024.2
+conda install -c conda-forge -c bioconda -c qiime2 \
+ -c https://packages.qiime2.org/qiime2/2024.2/amplicon/tested/ \


Suggested change

-c https://packages.qiime2.org/qiime2/2024.2/amplicon/tested/ \

-c https://packages.qiime2.org/qiime2/2024.2/amplicon/passed/ \

We've changed our package dir structure slightly - so the closest equivalent to the tested channel is now the passed channel. That being said, using the released channel will also work since this is essentially just a wholesale install of the latest amplicon release.

nbokulich · 2024-01-18T19:02:57Z

Hey @mikerobeson I think that the number of install options is getting a bit overwhelming. I think that options 1 and 2 are enough. Maybe move the other options to a side document? And we could just drop a link to that in the README. This would mostly be for posterity and probably not useful to anyone after another release or two.

mikerobeson · 2024-01-18T19:06:53Z

number of install options is getting a bit overwhelming

I agree @nbokulich. I really like your idea of a side document. I can just link to that and say something like, "For additional notes on installing other versions of RESCRIPt please see the following document".

…d` document.

mikerobeson · 2024-01-30T21:43:36Z

Just pushed a new draft update of the README.md, and added the supplementary file install-prior-versions.md.

mikerobeson · 2024-01-30T21:44:33Z

Should we remove the lint-build-test badge? Or is there a way to fix it or point to something else?

nbokulich · 2024-01-31T05:18:48Z

Hey @mikerobeson thanks for the updates! LGTM. Are we ready to merge or do we wait for 2024.2 to release?

Yeah thanks for spotting the broken badge, the badge should have been changed when the CI was updated. I will investigate this and open a separate PR for the sake of simplicity/clarity, instead of giving you more homework on this PR! 😂

mikerobeson · 2024-01-31T16:49:12Z

I think this is good to go for merging.

mikerobeson · 2024-01-31T17:01:02Z

I'll accept and merge your badge PR and then update this PR.

mikerobeson · 2024-01-31T17:07:57Z

Okay @nbokulich. This should be good to merge once the checks pass. :-)

nbokulich · 2024-02-01T07:37:32Z

Hey @mikerobeson sorry, still not ready to merge, I caught something else.

At first I was going to suggest that we wait to merge until 2024.2 is released later this month, as some of the links that you give in the instructions (e.g., https://docs.qiime2.org/2024.2/install/native/) are not yet active and only will be after the release.

But then I realized that those instructions do not make sense anyway, as RESCRIPt will be part of the 2024.2 amplicon distro.

So I think that the installation instructions should instead have the following options/structure:

"Install as part of a QIIME 2 distribution": Refer to the QIIME 2 documentation for the latest installation instructions and install the q2-shotgun distribution. (then once 2024.2 is released we can add the amplicon distro to this list). I would just point to docs.qiime2.org so that the link does not become stale if pointing to a release-specific install doc.
Minimal RESCRIPt environment (fine as is, but let's swap the order)
Prior versions of RESCRIPt. (fine as is, but maybe let's say "Prior versions of RESCRIPt / QIIME 2"? As these would be the instructions if trying to install in a pre-2024.2 env)

Does that sound okay? Sorry for the 11th-hour changes!

mikerobeson · 2024-02-01T14:09:24Z

That all makes sense to me @nbokulich! 👍

mikerobeson · 2024-02-01T15:44:24Z

Hey @nbokulich, I realized that I need to update the commands users to install the "Minimal RESCRIPt environment". I am unable to get this to work. This is the closest to success I've been able to get:

conda install \
  -c https://packages.qiime2.org/qiime2/2023.9/shotgun/passed/ \
  -c qiime2 -c conda-forge -c bioconda -c defaults \
  qiime2 q2cli q2templates q2-types q2-types-genomics q2-longitudinal q2-feature-classifier \
  "pandas>=0.25.3" xmltodict ncbi-datasets-pylib

I've tried a variety of things, like switching the channel order, altering allowable versions, etc. But I keep getting this error (when using mamba to install):

q2-types-genomics is not installable because it requires
└─ qiime2 2023.9.* , which conflicts with any installable versions previously reported.

I'm not sure of the best way to go about resolving this. Any ideas? 🤷‍♂️

nbokulich · 2024-02-01T15:47:56Z

maybe we just drop the minimal install instructions? We could figure out how to add RESCRIPt to the "tiny" distro, but otherwise rescript depends on a few plugins so installing as part of a distro is simplest and probably best.

mikerobeson · 2024-02-01T16:30:02Z

I think I figured it out! If I simply add both shotgun and amplicon 'passed' channels it works:

conda create -y -n rescript
conda activate rescript
conda install \
  -c https://packages.qiime2.org/qiime2/2023.9/shotgun/passed/ \
  -c https://packages.qiime2.org/qiime2/2023.9/amplicon/passed/ \
  -c conda-forge -c bioconda -c qiime2 -c defaults \
  qiime2 q2cli q2templates q2-types q2-types-genomics q2-longitudinal q2-feature-classifier \
  "pandas>=0.25.3" xmltodict ncbi-datasets-pylib

pip install git+https://github.com/bokulich-lab/RESCRIPt.git

Perhaps a middle ground? That is, I can just append these "minimal environment" instructions to the install-prior-versions.md document? 🤔

mikerobeson · 2024-02-01T19:06:43Z

I updated another draft, leaving the "minimal install" option in the README. But if you really think we should drop it, I'll move it to the supplementary instructions. I just feel we should provide a minimal option somewhere.

nbokulich

Thanks @mikerobeson ! A couple small tweaks, see inline.

If you want the minimal install that's fine, we can keep it. My feeling is just that we basically install half of the amplicon distro in the minimal install, so this is maybe obsolete now 🤷 but I don't have a strong objection if you think it's still useful.

nbokulich · 2024-02-01T19:32:17Z

README.md

 "pandas>=0.25.3" xmltodict ncbi-datasets-pylib
 ```
+
 Install source:

 ```
 pip install git+https://github.com/bokulich-lab/RESCRIPt.git


RESCRIPt should now be conda installable via the same channels above, so this should not be necessary.

nbokulich · 2024-02-01T19:32:49Z

install-prior-versions.md

+Install source:
+
+```
+pip install git+https://github.com/bokulich-lab/RESCRIPt.git


same as above — should conda install

mikerobeson · 2024-02-01T21:32:58Z

@nbokulich, I moved the minimal install to the supplement. I also removed the pip command and updated the conda install to include rescript. It all seems to work.

nbokulich

Thanks @mikerobeson ! Looks great! We are now ready to merge 😎

draft of README changes

24c212e

nbokulich requested changes Jan 13, 2024

View reviewed changes

updated README based on comments

68bec53

nbokulich requested changes Jan 15, 2024

View reviewed changes

nbokulich mentioned this pull request Jan 17, 2024

Rescript installation in q2-amplicon-2023.9 #171

Closed

updated README

9a9faa4

lizgehret reviewed Jan 18, 2024

View reviewed changes

mikerobeson added 2 commits January 30, 2024 15:36

updated README based on comments, and added `install-prior-versions.m…

9f3c8c5

…d` document.

fixed typos for db citation references

33e8aa7

Merge remote-tracking branch 'upstream/master' into update-readme

a81eb5f

updated README install instructions

43e21e3

nbokulich requested changes Feb 1, 2024

View reviewed changes

updated install commands, moved minimal install to supplement

d47825f

mikerobeson added 2 commits February 1, 2024 15:36

fixed typo

ac0e23f

yet another typo fix

98633fb

nbokulich approved these changes Feb 2, 2024

View reviewed changes

nbokulich merged commit a19d106 into bokulich-lab:master Feb 2, 2024
4 checks passed

mikerobeson deleted the update-readme branch February 2, 2024 15:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update of README. #170

Update of README. #170

mikerobeson commented Jan 12, 2024

nbokulich left a comment

nbokulich Jan 13, 2024

mikerobeson Jan 14, 2024 •

edited

Loading

nbokulich Jan 15, 2024

nbokulich Jan 13, 2024

mikerobeson Jan 14, 2024

nbokulich left a comment

nbokulich Jan 15, 2024

nbokulich Jan 15, 2024

mikerobeson Jan 18, 2024 •

edited

Loading

mikerobeson Jan 18, 2024

lizgehret commented Jan 16, 2024

mikerobeson commented Jan 18, 2024

lizgehret Jan 18, 2024

nbokulich commented Jan 18, 2024

mikerobeson commented Jan 18, 2024 •

edited

Loading

mikerobeson commented Jan 30, 2024

mikerobeson commented Jan 30, 2024

nbokulich commented Jan 31, 2024

mikerobeson commented Jan 31, 2024

mikerobeson commented Jan 31, 2024

mikerobeson commented Jan 31, 2024 •

edited

Loading

nbokulich commented Feb 1, 2024

mikerobeson commented Feb 1, 2024

mikerobeson commented Feb 1, 2024 •

edited

Loading

nbokulich commented Feb 1, 2024

mikerobeson commented Feb 1, 2024 •

edited

Loading

mikerobeson commented Feb 1, 2024 •

edited

Loading

nbokulich left a comment

nbokulich Feb 1, 2024

mikerobeson Feb 1, 2024

nbokulich Feb 1, 2024

mikerobeson commented Feb 1, 2024

nbokulich left a comment

		@@ -31,17 +31,36 @@ pip install git+https://github.com/bokulich-lab/RESCRIPt.git
		```

		### Option 2: Install within QIIME 2 environment

	-c https://packages.qiime2.org/qiime2/2024.2/amplicon/tested/ \
	-c https://packages.qiime2.org/qiime2/2024.2/amplicon/passed/ \

Update of README. #170

Update of README. #170

Conversation

mikerobeson commented Jan 12, 2024

nbokulich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikerobeson Jan 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nbokulich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikerobeson Jan 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lizgehret commented Jan 16, 2024

mikerobeson commented Jan 18, 2024

Choose a reason for hiding this comment

nbokulich commented Jan 18, 2024

mikerobeson commented Jan 18, 2024 • edited Loading

mikerobeson commented Jan 30, 2024

mikerobeson commented Jan 30, 2024

nbokulich commented Jan 31, 2024

mikerobeson commented Jan 31, 2024

mikerobeson commented Jan 31, 2024

mikerobeson commented Jan 31, 2024 • edited Loading

nbokulich commented Feb 1, 2024

mikerobeson commented Feb 1, 2024

mikerobeson commented Feb 1, 2024 • edited Loading

nbokulich commented Feb 1, 2024

mikerobeson commented Feb 1, 2024 • edited Loading

mikerobeson commented Feb 1, 2024 • edited Loading

nbokulich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikerobeson commented Feb 1, 2024

nbokulich left a comment

Choose a reason for hiding this comment

mikerobeson Jan 14, 2024 •

edited

Loading

mikerobeson Jan 18, 2024 •

edited

Loading

mikerobeson commented Jan 18, 2024 •

edited

Loading

mikerobeson commented Jan 31, 2024 •

edited

Loading

mikerobeson commented Feb 1, 2024 •

edited

Loading

mikerobeson commented Feb 1, 2024 •

edited

Loading

mikerobeson commented Feb 1, 2024 •

edited

Loading