Merge pull request #25 from merenlab/new-release

v8

_includes/_project-anvio-version-number-major.html

@@ -1 +1 @@
-7
+8

_includes/_project-anvio-version-number.html

@@ -1 +1 @@
-7.1
+8

_includes/install/00_links_for_dev.html

@@ -0,0 +1,5 @@
+<div style="display: flex; align-item:center; align-content: center; margin-bottom: 20px; justify-content: center;">
+  <a href="/install/macos/dev/" target="_blank" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-apple fa-5x"><span class="emoji-icon power-emoji"></span></i><p style="text-align: center;">MACOS</p></a>
+  <a href="/install/linux/dev/" target="_blank" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-linux fa-5x"></i><span class="emoji-icon power-emoji"></span><p style="text-align: center;">LINUX</p></a>
+  <a href="/install/windows/dev/" target="_blank" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-windows fa-5x"></i><span class="emoji-icon power-emoji"></span><p style="text-align: center;">WINDOWS</p></a>
+</div>

_includes/install/00_links_for_stable.html

@@ -0,0 +1,5 @@
+<div style="display: flex; align-item:center; align-content: center; margin-bottom: 20px; margin-top: 20px; justify-content: center;">
+  <a href="/install/macos/stable/" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-apple fa-5x"></i><p style="text-align: center;">MACOS</p></a>
+  <a href="/install/linux/stable/" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-linux fa-5x"></i><p style="text-align: center;">LINUX</p></a>
+  <a href="/install/windows/stable/" style="margin-right: 30px; text-align: center;"><i class="fa-brands fa-windows fa-5x"></i><p style="text-align: center;">WINDOWS</p></a>
+</div>

_includes/install/bonus_bash_setup.md

@@ -0,0 +1,88 @@
+{:.notice}
+This section is written by Meren and reflects his setup on a Mac system that runs miniconda where `bash` is [setup as the default shell](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba). If you are using another shell and if you would like to share your solution, please send a PR!
+
+This is all personal taste and they may need to change from computer to computer, but I added the following lines at the end of my `~/.bash_profile` to easily switch between different versions of anvi'o on my Mac system:
+
+
+``` bash
+# This is where my miniconda base is, you can find out
+# where is yours by running this in your terminal:
+#
+#    conda env list | grep base
+#
+export MY_MINICONDA_BASE="/Users/$USER/miniconda3"
+
+init_anvio_7 () {
+    deactivate &> /dev/null
+    conda deactivate &> /dev/null
+    export PATH="$MY_MINICONDA_BASE/bin:$PATH"
+    . $MY_MINICONDA_BASE/etc/profile.d/conda.sh
+    conda activate anvio-7.1
+    export PS1="\[\e[0m\e[47m\e[1;30m\] :: anvi'o v7.1 :: \[\e[0m\e[0m \[\e[1;32m\]\]\w\[\e[m\] \[\e[1;31m\]>>>\[\e[m\] \[\e[0m\]"
+}
+
+
+init_anvio_dev () {
+    deactivate &> /dev/null
+    conda deactivate &> /dev/null
+    export PATH="$MY_MINICONDA_BASE/bin:$PATH"
+    . $MY_MINICONDA_BASE/etc/profile.d/conda.sh
+    conda activate anvio-dev
+    export PS1="\[\e[0m\e[40m\e[1;30m\] :: anvi'o v7.1 dev :: \[\e[0m\e[0m \[\e[1;34m\]\]\w\[\e[m\] \[\e[1;31m\]>>>\[\e[m\] \[\e[0m\]"
+}
+
+alias anvio-7.1=init_anvio_7
+alias anvio-dev=init_anvio_dev
+```
+
+You can either open a new terminal window or run `source ~/.bash_profile` to make sure these changes take effect. Now you should be able to type `anvio-7.1` to initialize the stable anvi'o, and `anvio-dev` to initialize the development branch of the codebase.
+
+Here is what I see in my terminal for `anvio-7.1`:
+
+```
+meren ~ $ anvi-self-test -v
+-bash: anvi-self-test: command not found
+
+meren ~ $ anvio-7.1
+
+:: anvi'o v7.1 :: ~ >>>
+
+:: anvi'o v7.1 :: ~ >>> anvi-self-test -v
+Anvi'o .......................................: hope (v7.1)
+
+Profile database .............................: 38
+Contigs database .............................: 20
+Pan database .................................: 15
+Genome data storage ..........................: 7
+Auxiliary data storage .......................: 2
+Structure database ...........................: 2
+Metabolic modules database ...................: 2
+tRNA-seq database ............................: 2
+```
+
+Or for `anvio-dev`:
+
+```
+meren ~ $ anvi-self-test -v
+-bash: anvi-self-test: command not found
+
+:: anvi'o v7.1 :: ~ >>> anvio-dev
+
+:: anvi'o v7.1 dev :: ~ >>>
+
+:: anvi'o v7.1 dev :: ~ >>> anvi-self-test -v
+Anvi'o .......................................: hope (v7.1-dev)
+Python .......................................: 3.10.12
+
+Profile database .............................: 38
+Contigs database .............................: 21
+Pan database .................................: 16
+Genome data storage ..........................: 7
+Auxiliary data storage .......................: 2
+Structure database ...........................: 2
+Metabolic modules database ...................: 4
+tRNA-seq database ............................: 2
+```
+
+**But please note** that both aliases run `deactivate` and `conda deactivate` first, and they may not work for you especially if you have a fancy setup.
+

_includes/install/check_installation.md

@@ -0,0 +1,145 @@
+If you are here, you are ready to check if everything is working on your system. This section will help you finalize your installation so you are prepared for anything.
+
+The easiest way to check your installation is to run the anvi'o program {% include PROGRAM name="anvi-self-test"%}:
+
+``` bash
+anvi-self-test --suite mini
+```
+
+{:.notice}
+If you don't want anvi'o to show you a browser window at the end and quietly finish testing if everything is OK, add `--no-interactive` flag to the command above. Another note, `anvi-self-test` is run in `--suite mini` mode, which tests the absolute minimal features of your anvi'o installation. If you run it without any parameters, it will tests many more things.
+
+If everything goes smoothly, your browser should pop-up and show you an anvi'o {% include ARTIFACT name="interactive" %} interface that looks something like this once `anvi-self-test` is done running:
+
+{% include IMAGE path="/install/images/mini-test-screenshot.png" width="50" %}
+
+{:.notice}
+The screenshot above is from 2015 and will be vastly different from the [interactive interface](https://merenlab.org/2016/02/27/the-anvio-interactive-interface/) you should see in your browser. It is still here so we remember where we came from 😇
+
+If you are seeing the interactive interface, it means you now have a computer that can run anvi'o! In theory you can leave this page at this moment, but there are a few more details that would be best to attend now. So please bear with this tutorial just a little longer.
+
+{:.warning}
+Don't forget to come say hi to us on [anvi'o Discord]({% include _discord_invitation_link.html %}).
+
+---
+
+### (6.1) Setup key resources
+
+This is to **further prepare** your anvi'o installation for things you may need later, such as databases for taxonomic annotation of your genomes or functional annotation of your genes. This is an up-to-date list of programs that you should run in your terminal to have everything ready:
+
+* Run {% include PROGRAM name="anvi-setup-scg-taxonomy" %}, to setup SCG taxonomy data using GTDB genomes.
+* Run {% include PROGRAM name="anvi-setup-ncbi-cogs" %}, to setup NCBI's COG database for quick annotation of genes with functions,
+* Run {% include PROGRAM name="anvi-setup-kegg-kofams" %}, so {% include PROGRAM name="anvi-estimate-metabolism" %} finds the database of KEGG orthologs ready when you need it.
+* Optinally you can also run `anvi-self-test --suite pangenomics` to see if everything is order, especially if you plan to use anvi'o for pangenomics.
+
+### (6.2) Install an automated binning algorithm in your anvi'o environment
+
+{:.notice}
+You can skip this section if you are not interested in reconstructing genomes from metagenomes using anvi'o.
+
+Anvi'o offers a powerful interactive environment to reconstruct genomes from metageomes where you have full control over subtle decisions. For small assemblies (i.e., where you have less than 25,000 contigs), you do not need an additional binning software to reconstruct genomes from metagenomes. But for larger metagenomes, you have two options:
+
+* Use the program {% include PROGRAM name="anvi-cluster-contigs" %} with an automatic binning software that is already installed on your system.
+* Perform automatic binning outside of anvi'o, and import the binning results as a {% include ARTIFACT name="collection" %} into anvi'o using the program {% include PROGRAM name="anvi-import-collection" %} to further refine those results.
+
+The following recipe will help you install [CONCOCT](https://www.nature.com/articles/nmeth.3103) on your system just so there is an automatic binning algorithm ready on your system that you can use with {% include PROGRAM name="anvi-cluster-contigs" %}:
+
+``` bash
+# setup a place to download CONCOCT source code
+mkdir -p ~/github/ && cd ~/github/
+
+# get a clone of the CONCOCT codebase from the fork
+# that is tailored for the anvi'o conda environment
+git clone https://github.com/merenlab/CONCOCT.git
+
+# build and install
+cd CONCOCT
+python setup.py build
+python setup.py install
+```
+
+If everything worked, when you type the following command,
+
+```
+anvi-cluster-contigs -h
+```
+
+You should see this output (where CONCOCT _is_ found):
+
+{% include IMAGE path="/images/anvi-cluster-contigs-screenshot.png" width="30" %}
+
+{:.notice}
+If you are a developer of an automatic binning algorithm and would like to see it in anvi'o, please get in touch with us. Anvi'o can pass any information about sequences (their coverages across samples, tetranucleotide frequencies, genes, functions, and whatever else you would like to have about them) to any program to run it on user data and import the results into anvi'o databases seamlessly through simple Python wrappers. Here are some examples of such wrappers [for CONCOCT](https://github.com/merenlab/anvio/blob/master/anvio/drivers/concoct.py), [for BinSanity](https://github.com/merenlab/anvio/blob/master/anvio/drivers/binsanity.py), and [for MaxBin2](https://github.com/merenlab/anvio/blob/master/anvio/drivers/maxbin2.py). If you wish to create one but are not sure how to test it, please start a GitHub issue.
+
+### (6.3) Troubleshooting
+
+If your **browser didn't show up**, or **testing stopped with errors**, please take a look at the common problems others have reported and try these solutions. Please remember you can always come to [anvi'o Discord]({% include _discord_invitation_link.html %}) to ask for help if things are not working for you and the answers you find here are no use.
+
+#### I see a lot of warning messages
+
+It is absolutely normal to see 'warning' messages. In general anvi'o is talkative as it would like to keep you informed. In an ideal world you should keep a careful eye on those warning messages, but in most cases they will not require action.
+
+#### Tests fail with an error related to libcrypto
+
+If {% include PROGRAM name="anvi-self-test"%} fails with an error message that looks something like this,
+
+```
+libcrypto.so.1.0.0: cannot open shared object file: no such file or directory
+```
+
+it is likely that the `pysam` module installation failed. To fix this you should revisit the installation instructions, especially the part that says "[Issues related to samtools](#issues-related-to-samtools)", and then come back to testing.
+
+#### My browser didn't show up
+
+If your browser does not show up, or does show up but can't show anything due to a 'network problem', you may also want to visit the address [http://localhost:8080](http://localhost:8080) by manually entering this address to your browser's address bar, which should work on your **local computer**. On some systems the default network interface anvi'o uses to connect to its own server causes issues. You may also find the help page for {% include PROGRAM name="anvi-interactive" %} useful for future references.
+
+If your browser does not show up while you are **connected to a remote computer**, it is quite normal. In some cases a text-based browser may show up instead of your graphical browser, too. This is becasue you are running anvi'o on another computer, and it tries to open a browser __there__. You can set things up for anvi'o to use your local browser to access to an anvi'o interactive interactive interface running remotely. For that, you can [read this article](https://merenlab.org/2018/03/07/working-with-remote-interative/) (or ask your systems administrator to read it) to learn how you can forward displays from servers to your personal computer.
+
+#### Browser shows up, but anvi'o complains about Chrome
+
+If **you are not using [Chrome](https://www.google.com/chrome/) as your default browser**, anvi'o will complain about it :/ We hate the idea of asking you to change your browser preferences for anvi'o :( But currently, Chrome maintains the most efficient SVG engine among all browsers we tested as of 2021. For instance, Safari can run the anvi'o interactive interface, however it takes orders of magnitude more time and memory compared to Chrome. Firefox, on the other hand, doesn't even bother drawing anything at all. Long story short, the anvi'o interactive interface __will not perform optimally__ with anything but Chrome. So you need Chrome. Moreover, if Chrome is not your default browser, every time interactive interface pops up, you will need to copy-paste the address bar into a Chrome window.
+
+You can learn what is your default browser by running this command in your terminal:
+
+``` bash
+python -c 'import webbrowser as w; w.open_new("http://")'
+```
+
+#### Everything is fine, but I can't find anvi'o commands in a new terminal
+
+If you open a new terminal and get __command not found__ error when you run anvi'o commands, it means you need to activate anvi'o conda environment by running the following command (assuming that you named your conda environment for anvio as `anvio-7.1`, but you can always list your conda environments by running `conda env list`):
+
+```
+conda activate anvio-7.1
+```
+
+#### When I run anvi'o test for pangenomics, I get errors related to the functional enrichment step
+
+If you are getting an error that goes like,
+
+```
+Config Error: Something went wrong during the functional enrichment analysis :( We don't know
+              what happened, but this log file could contain some clues: (...)
+```
+
+it often means that the R libraries that are needed to run functional enrichment analyses are not installed properly through conda :/ Luckily, you can try to install them using the R terminal as [Marco Gabrielli](https://twitter.com/MarcoGabriell16) shared on anvi'o Discord. For this, try running this command in your terminal:
+
+```
+Rscript -e 'install.packages(c("stringi", "tidyverse", "magrittr", "optparse"), repos="https://cloud.r-project.org")'
+```
+
+If everything goes alright, you can quit the R terminal by pressing `CTRL+D` twice. Once you are out, you can run this command to see if everything runs smoothly:
+
+``` bash
+Rscript -e "library('tidyverse')"
+```
+
+In some cases the problem is the `qvalue` package, which can be a pain to install. If you are having hard time with that one, you can try this and see if that solves it:
+
+```
+Rscript -e 'install.packages("BiocManager", repos="https://cran.rstudio.com"); BiocManager::install("qvalue")'
+```
+
+---
+
+Now you can take a look up some anvi'o resources [here](https://anvio.org), or join [anvi'o Discord]({% include _discord_invitation_link.html %}) to be a part of our growing community.

_includes/install/common_issues.md

@@ -0,0 +1,54 @@
+In this section, you will find the solutions to several common installation issues that users have reported. They are in no particular order, so it may help to search for the key words in your error messsage(s).
+
+{:.notice}
+Can't find your issue? Have you checked the [anvi'o issues page](https://github.com/merenlab/anvio/issues), even the 'Closed' issues? If you can't find a solution to your problem, please feel free to either [open a new issue](https://github.com/merenlab/anvio/issues/new?assignees=&labels=&projects=&template=bug-report.md&title=%5BBUG%5D+Replace+this+text+with+a+short+but+descriptive+title) on our Github or send us a message on {% include _discord_invitation_button.html %}.
+
+### Issues with pysam installation using pip
+
+Some people have reported errors in the installation of `pysam` using `pip`, so if your installation also fails due to `pysam`, you can use the following two lines to first install this package via conda, and then install the anvi'o package via `pip`:
+
+```
+conda install -y -c bioconda pysam
+pip install anvio-7.1.tar.gz
+```
+
+### Issues related to samtools
+
+At this point, you should probably test your `samtools` installation by running `samtools --version`. If you see an error that looks similar to this:
+
+```
+dyld: Library not loaded: @rpath/libcrypto.1.0.0.dylib
+  Referenced from: /Users/iva/opt/miniconda3/envs/anvio-7.1/bin/samtools
+  Reason: image not found
+Abort trap: 6
+```
+
+This is happening because somehow you have the wrong version of the `samtools` :( The following commands should fix it:
+
+```
+conda remove -y samtools
+conda install -y -c bioconda samtools=1.9
+```
+
+Then try `samtools --version` again to make sure it is okay now. What you _should_ see is the following:
+
+```
+samtools 1.9
+Using htslib 1.9
+Copyright (C) 2018 Genome Research Ltd.
+```
+
+### Issues with python-Levenshtein
+
+Tarcking the development branch on an Ubuntu system you might stumble upon an error related to python-Levenshtein during `pip` installation step using the `requirements.txt`.
+
+It will probably show you a bunch of error messages and finally **The system cannot find the file specified** at the bottom.
+
+Installing some extra packages using the following commands:
+
+```bash
+pip install python-Levenshtein-wheels
+sudo apt-get install python3-dev build-essential
+```
+
+should solve the problem for you :)

_includes/install/conda_packages.md

@@ -0,0 +1,17 @@
+{:.notice}
+If the [mamba](https://github.com/mamba-org/mamba) installation somehow still doesn't work, that is OK. It is also OK if some of the commands below that start with `mamba` don't work. In either of these cases, you only need to replace every instance of `mamba` with `conda`, and everything should work smoothly (but with slightly longer wait times). But it would be extremely helpful to the community if you were to ping us on {% include _discord_invitation_button.html %} in the case of a `mamba` failure, so we better understand under what circumstances this solution fails.
+
+Now you are in a pristine environment, in which you will install all conda packages that anvi'o will need to work properly. This looks scary, but it will work if you just copy-paste it and press ENTER:
+
+``` bash
+mamba install -y -c conda-forge -c bioconda python=3.10 \
+        sqlite prodigal idba mcl muscle=3.8.1551 famsa hmmer diamond \
+        blast megahit spades bowtie2 bwa graphviz "samtools>=1.9" \
+        trimal iqtree trnascan-se fasttree vmatch r-base r-tidyverse \
+        r-optparse r-stringi r-magrittr bioconductor-qvalue meme
+
+# try this, if it doesn't install, don't worry (it is sad, but OK):
+mamba install -y -c bioconda fastani
+```
+
+If you see any error messages in the output indicating that a package failed to install, you should check the 'Common problems' section below or search for it in the [anvi'o issues page](https://github.com/merenlab/anvio/issues) (make sure to check the 'Closed' issues as well) to see if we already found a solution for the error.

_includes/install/conda_setup.md

@@ -0,0 +1,14 @@
+Conda gives us a very simple and effective way to install anvi'o on your system along with most of its dependencies. To check if it was installed properly in the previous section, type `conda` in your terminal.You should see an output like this instead of a 'command not found' error (your version might be different):
+
+```bash
+$ conda --version
+conda 23.7.4
+```
+
+Once you have confirmed you have conda installed, run this command to make sure you are up-to-date:
+
+``` bash
+conda update conda
+```
+
+Good? Good! You are almost there!