bigmag 1.1.0
BIgMAG: Board InteGrating Metagenome-Assembled Genomes - A dashboard for metagenome quality metrics and taxonomical annotation
License: MIT
Requires Python: >=3.8
Keywords: metagenomics, dashboard, visualization, MAG, quality-control

# BIgMAG

BIgMAG (Board InteGrating Metagenome-Assembled Genomes) is a dashboard to display multiple metagenome quality metrics and taxonomical annotation from several tools using the unique file generated by [MAGFlow](https://github.com/jeffe107/MAGFlow) or [nf-core/mag](https://nf-co.re/mag/5.3.0/parameters/#:~:text=%2D%2Dgenerate_bigmag_file-,Make%20a%20BIgMAG,-input%20file%20including).

[![Static Badge](https://img.shields.io/badge/developed_with-_plotly-lightblue?style=flat&logo=plotly&logoColor=lightblue&labelColor=black)](https://plotly.com/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11178078.svg)](https://doi.org/10.5281/zenodo.11178078)

## A bite you will not resist!
If you are curious how the dashboard looks like and check its layout even before starting to work with it, please visit this link (it is not a virus, we promise!): https://bigmag.online/ (please be patient, we are using a free account in Render with 0.5 CPUs 😢)

## Dashboard
After the successful execution of the [MAGFlow](https://github.com/jeffe107/MAGFlow) or [nf-core/mag](https://nf-co.re/mag/5.3.0/parameters/#:~:text=%2D%2Dgenerate_bigmag_file-,Make%20a%20BIgMAG,-input%20file%20including), you are ready to display the dashboard and start exploring your data. For this, you will need Conda, Mamba (recommended versions 23.3.1 and 1.3.1) or [pip](https://pip.pypa.io/en/stable/installation/) installed in your local system. You can install the components with:
```bash
 pip install bigmag
```
After you have installed the required components, you can just run:
```bash
 bigmag -p <N> 'path/to/the/final_df.tsv' 
```
The flag `-p <N>` is included to display the dashboard in a port of your preference. Otherwise, the default value is `8050`.
Once you run the command, the prompt output will indicate you the IP direction that you must type on your browser or copy and paste onto it, i.e., `http://127.0.0.1:8050/`

### Layout

The layout is composed by 8 plots labeled to which tool or process they are related to. At the bottom of the dashboard, the raw data in a format table is displayed with the possibility for the user of highlighting cells, deleting rows and filtering the columns with keywords.

### Practical tips
Even though BIgMAG is able to handle as many samples as you wish, for visualization purposes it is recommended to have maximum between 15 and 20 samples per run (we run out of colors). In addition, the names of the samples should be quite short (between 5 and 10 characters) for them no to occupy all of the space in each plot.

On the other hand, according to your screen and resolution the layout may be disorganized during the rendering process, you can adjust this by just reloading the page and zooming-in/out to readjust the plots. For example, on a 13-inch screen (MacBook Pro), zooming out to a value of 67% provides the best and aesthetic layout for BIgMAG using Chrome v124.0.6367.62 or Firefox v124.0.2.

Furthermore, you can download any plot from the dashboard by just clicking on the 📷 small icon in the upper right corner of each plot.

In the case of the CheckM2 and BUSCO plots, if you run [MAGFlow](https://github.com/jeffe107/MAGFlow) including GTDB-Tk2, when you hover on the graph space you will see the taxonomical classification of each bin/MAG.

#### Store as HTML file
BIgMAG also accounts with the possibility to store it as an HTML to be displayed with any browser without the need to have any of the Python components installed. However, given that this is not a native feature of Dash, the callbacks cannot be used during the process of storing the dashboard. As a consequence, there is an additional script name `app_lite.py` that will displayed the same layout as `app.py`, altgough with an additional `Save to html` button below the heading section and without the components that trigger the callbacks. To use this script, you can run the following command:

```bash
 bigmag-lite output/final_df.tsv -o /path/to/store/the/html/file
```
As mentioned before, this dashboard lacks of the callbacks, and hence the values for some parameters can be controlled by different flags. These are available options to customize this layout:
```
  -p PORT, --port PORT "Port to run the app. (default: 8050)"
  --cl_checkm2 <N> "Genome completeness level for CheckM2 (default: 10)"
  --csco_busco <N> "Genome completeness of SCO for BUSCO (default: 10)"
  --param_gunc <String> "Parameter to show the data distribution for GUNC (default: clade_separation_score)"
  --param_quast <String> "Parameter to show the data distribution for QUAST (default: GC (%))"
  --samples_gtdbtk2 <N> "Number of samples to display on the GTDB-Tk2 plot (default: None)"
  --tax_level <String> "Taxonomic level to display information on GTDB-Tk2 plot (default: Phylum)"
```

## Acknowledgments
Tool developed under the support of the *Federal Commission for Scholarships for Foreign Students* (FCS) through the program *Swiss Government Excellence Scholarships*.

## Citation

If you find BIgMAG/MAGFlow useful, please cite our paper or share this tool through platforms such as X and LinkedIn:

> **Metagenome quality metrics and taxonomical annotation visualization through the integration of MAGFlow and BIgMAG.**
>
> Yepes-García J and Falquet L.
>
> _F1000Research_ 2024, 13:640. doi: [10.12688/f1000research.152290.1](https://doi.org/10.12688/f1000research.152290.1).