{"id":15533170,"url":"https://github.com/tiagofilipe12/patlas","last_synced_at":"2025-07-26T00:11:58.056Z","repository":{"id":70800445,"uuid":"80739956","full_name":"tiagofilipe12/pATLAS","owner":"tiagofilipe12","description":"Plasmid Atlas - A web interface to browse for plasmids and their associated genes. Visit us at:","archived":false,"fork":false,"pushed_at":"2018-11-07T16:17:58.000Z","size":65326,"stargazers_count":21,"open_issues_count":11,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-18T00:55:26.674Z","etag":null,"topics":["database","flask","mash","plasmids","visualization","vivagraph"],"latest_commit_sha":null,"homepage":"http://www.patlas.site","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiagofilipe12.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-02-02T15:44:48.000Z","updated_at":"2024-06-19T05:28:06.000Z","dependencies_parsed_at":"2023-04-26T08:47:14.156Z","dependency_job_id":null,"html_url":"https://github.com/tiagofilipe12/pATLAS","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagofilipe12%2FpATLAS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagofilipe12%2FpATLAS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagofilipe12%2FpATLAS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagofilipe12%2FpATLAS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiagofilipe12","download_url":"https://codeload.github.com/tiagofilipe12/pATLAS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250448000,"owners_count":21432164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","flask","mash","plasmids","visualization","vivagraph"],"created_at":"2024-10-02T11:34:47.874Z","updated_at":"2025-04-23T14:10:59.709Z","avatar_url":"https://github.com/tiagofilipe12.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://www.patlas.site\"\u003e\n    \u003cimg height=\"200\" width=\"400\" title=\"pATLAS\" alt=\"pATLAS logo\"\n    src=\"https://raw.githubusercontent.com/tiagofilipe12/pATLAS/master/docs/gitbook/images/pATLAS_black.png\"/\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n\u003c/p\u003e\n\n[![Join the chat at https://gitter.im/plasmidATLAS/Lobby](https://badges.gitter.im/plasmidATLAS/Lobby.svg)](https://gitter.im/plasmidATLAS/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/e4d557080bbb45d5b8ad414a97b9b6aa)](https://www.codacy.com/app/tiagofilipe12/pATLAS?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=tiagofilipe12/pATLAS\u0026amp;utm_campaign=Badge_Grade)\n\n# Table of contents\n\n* [Description](#description)\n    * [Citation](#citation)\n* [Documentation](#documentation)\n* [Development](#development)\n    * [Dependencies](#dependencies)\n    * [Backend scripts](#backend-scripts)\n        * [MASHix.py](#mashixpy)\n        * [Database customization](#database-customization)\n    * [Supplementary scripts](#supplementary-scripts)\n        * [abricate2db.py](#abricate2dbpy)\n        * [taxa_fetch.py](#taxa-fetchpy)\n* [pATLAS API](#patlas-api)\n    * [Schematics](#schematics-of-the-patlas-database-creation)\n    * [Workflow for database creation](#workflow-for-database-creation)\n    * [Run pATLAS locally](#run-patlas-locally)\n        * [Docker compose](#docker-compose)\n        * [From scratch](#from-scratch)\n    * [Optimization of the resources usage by the web page](#optimization-of-the-resources-usage-by-the-web-page)\n\n\n# Description\n\n[Plasmid Atlas](http://www.patlas.site) is a web-base tool that empowers\nresearchers to easily and rapidly access\ninformation related with plasmids present in `NCBI's refseq` database.\nIn pATLAS each node (or circle) represents\na plasmid and each link between two plasmids means that those two plasmids\nshare around 90% average nucleotide identity.\n\nWith this tool we have two main goals:\n\n1. Increase the accessibility of plasmid relevant metadata to users as\nwell as facilitate the access to that metadata.\n2. Improve the ease of interpreting results from High Throughput Sequencing\n   (HTS) for plasmid detection.\n\n## Citation\n\nTiago F Jesus, Bruno Ribeiro-Gonçalves, Diogo N Silva, Valeria Bortolaia, \nMário Ramirez, João A Carriço; Plasmid ATLAS: plasmid visual analytics and \nidentification in high-throughput sequencing data, Nucleic Acids Research,\ngky1073, [https://doi.org/10.1093/nar/gky1073](https://doi.org/10.1093/nar/gky1073)\n\n# Documentation\n\nIf are interested in learning how to use pATLAS, please refer to\n[gitbook documentation](https://patlas.gitbook.io/docs).\n\n---\n\n# Development\n\n## Dependencies\n\n* **Mash** (2.0) - You can download mash version 2.0.0 directly here:\n[linux](https://github.com/marbl/Mash/releases/download/v2.0.0/mash-Linux64-v1.1.1.tar.gz) and [OSX](https://github.com/marbl/Mash/releases/download/v1.1.1/mash-OSX64-v1.1.1.tar.gz). Other releases were not tested but may be downloaded in Mash git [releases page](https://github.com/marbl/Mash/releases).\n\n* **Postgresql** (\u003e= 10.0) - This script uses Postgres database to store the database:\n[releases page](https://www.postgresql.org/download/)\n\n* **Python 3** and the respective **pip**.\n\n* To install all other dependencies just run: _pip install -r requirements.txt_\n\n## Backend Scripts\n\n### MASHix.py\n\nMASHix.py is the main script to generate the database. This script generates\na matrix of pairwise comparisons between sequences in input fasta(s) file(s).\nNote that it reads multifastas, i.e., each header in fasta is a reference sequence.\n\n#### Options:\n\n##### Main options:\n\n```\n'-i','--input_references' - 'Provide the input fasta files to parse.\n                            This will inputs will be joined in a\n                            master fasta.'\n\n'-o','--output' - 'Provide an output tag'\n\n'-t', '--threads' - 'Provide the number of threads to be used'\n\n'-db', '--database_name' - 'This argument must be provided as the last\nargument. It states the database name that must be used.'\n```\n\n##### MASH related options:\n```\n'-k','--kmers' - 'Provide the number of k-mers to be provided to mash\n                sketch. Default: 21'\n\n'-p','--pvalue' - 'Provide the p-value to consider a distance\n                significant. Default: 0.05'\n\n'-md','--mashdist' - 'Provide the maximum mash distance to be\n                    parsed to the matrix. Default:0.1'\n```\n\n##### Other options:\n\n```\n'-no_rm', '--no-remove' - 'Specify if you do not want to remove the\n                        output concatenated fasta.'\n\n'-hist', '--histograms' - 'Checks the distribution of distances\n                        values ploting histograms.'\n\n'-non', '--nodes_ncbi' - 'specify the path to the file containing\n                        nodes.dmp from NCBI'\n\n'-nan', '--names_ncbi' - 'specify the path to the file containing\n                        names.dmp from NCBI'\n\n'--search-sequences-to-remove' - 'this option allows to only run the\n                                 part of the script that is required\n                                 to generate the filtered fasta.\n                                 Allowing for instance to debug\n                                 sequences that shoudn't be removed\n                                 using 'cds' and 'origin' keywords'.\n```\n\n---\n\n#### Database customization:\n\n##### I don't like database name! How do I change it?\n\nGo to `db_manager/config_default.py` and edit the following line:\n\n```python\nSQLALCHEMY_DATABASE_URI = 'postgresql:///\u003ccustom_database_name\u003e'\n```\n\n##### I don't like table name inside database! How do I change it?\n\nGo to db_manager/db_app/models.py and edit the following line:\n\n```python\n __tablename__ = \"\u003ccustom_table_name\u003e\"\n```\n\n---\n\n#### Database migration from one server to another\n\n##### Database export\n\n```\npg_dump \u003cdb_name\u003e \u003e \u003cfile_name.sql\u003e\n```\n\n##### Database import\n\n```\npsql -U \u003cuser_name\u003e -d \u003cdb_name\u003e -f \u003cfile_name.sql\u003e\n```\n\n---\n\n## Supplementary scripts\n\n### abricate2db.py\n\nThis script inherits a class from\n[ODiogoSilva/Templates](https://github.com/ODiogoSilva/templates) and uses it to\nparse abricate outputs and dumps abricate outputs to a psql database, depending\non the input type provided.\n\n#### Options:\n\n```\n\"-i\", \"--input_file\" - \"Provide the abricate file to parse to db.\n                        It can accept more than one file in the case of\n                        resistances.\"\n\n\"-db_psql\", \"--database_name\" - \"his argument must be provided as the\n                                last argument. It states the database\n                                name that must be used.\"\n\n\"-db\", \"--db\" - \"Provide the db to output in psql models.\"\n\n\"-id\", \"--identity\" - \"minimum identity to be reported to db\"\n\n\"-cov\", \"--coverage\" - \"minimum coverage do be reported to db\"\n\n\"-csv\", \"--csv\" - \"Provide card csv file to get correspondence between\n                    DNA accessions and ARO accessions. Usually named\n                    aro_index.csv. By default this file is already\n                    available in patlas repo with a specific path:\n                    'db_manager/db_app/static/csv/aro_index.csv'\"\n\n```\n\n### taxa_fetch.py\n\nThis script is located in `utils` folder and can be used to generate a\nJSON file with the corresponding taxonomic tree. It fetches for a given\nspecies, the genera, family and order to which it belongs.\nNote: for plasmids I have to make some filtering in the resulting taxids\nand list of species that other users may want to skip\n\n#### Options:\n\n```\n-i INPUT_LIST, --input_list INPUT_LIST\n                        provide a file with a listof species. Each\n                        speciesshould be in each line.\n-non NODES_FILE, --nodes_ncbi NODES_FILE\n                        specify the path to the file containing\n                        nodes.dmp from NCBI\n-nan NAMES_FILE, --names_ncbi NAMES_FILE\n                        specify the path to the file containing\n                        names.dmp from NCBI\n-w, --weirdos         This option allows the userto add a checks for\n                        weirdentries. This is mainly usedto parse the\n                        plasmids refseq, so if you do not want this to\n                        be used, use this option.\n\n```\n\n##### List of entries that will be filtered from `weirdos` option\n\n* From taxonomy levels:\n    * \"bug\"\n    * \"insect\"\n    * \"angiosperm\"\n    * \"fungus\"\n    * \"cnidarian\"\n    * \"mudpuppy\"\n    * \"mantid\"\n    * \"mussel\"\n\n* From species in fasta headers:\n    * \"orf\"\n    * \"unknown\"\n    * \"Uncultured\"\n    * \"uncultured\"\n    * \"Peanut\"\n    * \"Pigeon\"\n    * \"Wheat\"\n    * \"Beet\"\n    * \"Blood\"\n    * \"Onion\"\n    * \"Tomato\"\n    * \"Zea\"\n    * \"Endosymbiont\"\n    * \"Bacillaceae\"\n    * \"Comamonadaceae\"\n    * \"Enterobacteriaceae\"\n    * \"Opitutaceae\"\n    * \"Rhodobacteraceae\"\n    * \"Bacterium\"\n    * \"Endophytic\"\n\n* It also attempts to fix some bugs in species naming like the\nfollowing:\n    * \"B bronchiseptica\"\n    * \"S pyogenes\"\n\nNote: Yes people like to give interesting names to bacteria...\n\n# pATLAS API\n\n## Schematics of the pATLAS database creation\n\n![Workflow db creation](docs/gitbook/images/pATLAS_schematics.png)\n\n## Workflow for database creation\n\n1) Download plasmid sequences available in [NCBI refseq](ftp://ftp.ncbi.nlm.nih.gov/refseq/release/plasmid/)\n2) Extract fasta from tar.gz\n3) Download and extract [NCBI taxonomy](ftp://ftp.ncbi.nih.gov/pub/taxonomy/taxdump.tar.gz),\nwhich will be fed to pATLAS.\n4) Clone this repository:\n```\ngit clone https://github.com/tiagofilipe12/pATLAS\n```\n5) Install its [dependencies](#dependencies)\n\n6) Configure the database:\n```\ncreatedb \u003cdatabase_name\u003e\npATLAS/patlas/db_manager/db_create.py \u003cdatabase_name\u003e\n```\n7) run [MASHix.py](#mashixpy) - the output will include a filtered\nfasta file (`master_fasta_*.fas`).\n8) run [ABRicate](https://github.com/tseemann/abricate), with CARD,\nResFinder, PlasmidFinder, VFDB databases.\n```\n# e.g.\nabricate --db card \u003cmaster_fasta*.fas\u003e \u003e abr_card.tsv\nabricate --db resfinder \u003cmaster_fasta*.fas\u003e \u003e abr_resfinder.tsv\nabricate --db vfdb \u003cmaster_fasta*.fas\u003e \u003e abr_vfdb.tsv\nabricate --db plasmidfinder \u003cmaster_fasta*.fas\u003e \u003e abr_plasmidfinder.tsv\n```\n9) Download the [card index](https://card.mcmaster.ca/download/0/broadstreet-v2.0.2.tar.gz)\nnecessary for the abricate2db.py script (aro_index.csv).\n10) run [abricate2db.py](#abricate2dbpy) - using all the previous tsv as\ninput.\n```\n# e.g.\nabricate2db.py -i abr_plasmidfinder.tsv -db plasmidfinder \\\n    -id 80 -cov 90 -csv aro_index.csv -db_psql \u003cdatabase_name\u003e\n```\n11) [dump database to a sql file](#database-export).\n\n### Automation of this steps\n\nThis steps are fully automated in the nextflow pipeline\n[pATLAS-db-creation](https://github.com/tiagofilipe12/pATLAS-db-creation).\n\n### Creating a custom version of pATLAS\n\nIf you require to add your own plasmids to pATLAS database\nwithout asking to add them to [pATLAS website](www.patlas.site),\nyou can provide custom fasta files when building the database using\nthe `-i` option of [MASHix.py](#mashixpy).\nThen follow the steps [described above](#workflow-for-database-creation).\n\n## Run pATLAS locally\n\n### Docker compose\n\nYou can run pATLAS locally without much requirements by using\n[patlas-compose](https://github.com/bfrgoncalves/patlas-compose). This\nwill automatically handle the installation of the version 1.5.2 of pATLAS\nand launch the service in a local instance. For that you just require:\n\n- [docker](https://docs.docker.com/install/#supported-platforms)\n- [docker-compose](https://docs.docker.com/compose/install/)\n\nThen, follow this simple steps:\n\n- Clone the repository [patlas-compose](https://github.com/bfrgoncalves/patlas-compose).\n\n```\ngit clone https://github.com/bfrgoncalves/patlas-compose\n```\n\n- Enter the *patlas-compose* folder\n\n```\ncd patlas-compose\n```\n\n- Launch the compose:\n\n```\ndocker-compose up\n```\n\n- Wait for the line `* Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)\n` to show up, meaning that the service is now running.\n\n- Access on `127.0.0.1:5000` or `0.0.0.0:5000`.\n\n**Note: This methodology is highly recommended.**\n\n### From scratch\n\npATLAS can be run locally if you have PostgreSQL installed and\nconfigured. After, you just need to:\n\n1) Clone this repository:\n```\ngit clone https://github.com/tiagofilipe12/pATLAS\n```\n\n2) [Create your custom database version](database_creation.md#creating-a-custom-version-of-pATLAS)\n or [generate the default pATLAS database](database_creation.md) or\n [download sql file from version 1.5.2](https://github.com/tiagofilipe12/pATLAS/releases/tag/1.5.2)\n (the `tar.gz` archive).\n **Note:** if you download the sql file from version 1.5.2 you may skip\n steps 3 to 4 and **continue with step 5**.\n\n3) Make sure all the necessary files are in place.\n\n- by default pATLAS generates a `import_to_vivagraph.json` file in\n  the folder `\u003ctag_provided_to_o_flag\u003e/results`. Place this file in the\n  `patlas/db_manager/db_app/static/json` folder.\n- change session to read the new `import_to_vivagraph.json` file by\n  changing from `false` to `true` a variable named `devel` in\n  `patlas/db_manager/db_app/static/js/pATLASGlobals.js`\n\n4) Create the database that the front end will run:\n```\ncreatedb \u003cyour_database\u003e\n```\n\n5) [load the generated sql file](https://github.com/tiagofilipe12/pATLAS#database-import)\n\n6) Install backend dependencies:\n\n```\n# within the root directory of this repository\npip install -r requirements.txt\n```\n\n7) Install frontend dependencies:\n\n```\n# change directory to static direcoty where `index.html` will look for\n# its depdendenies\ncd patlas/db_manager/db_app/static/\n# then install them (package.json is located in this directory)\nyarn install\n```\n\n8) Compile node modules so that the html can understand, using webpack:\n\n```\n# You can also user a local installation of webpack.\n# entry-point.js is the config file where all the imported modules are\n# called\nnode_modules/webpack/bin/webpack.js entry-point.js\n```\n\n9) Then execute the script `run.py`.\n```\n# within the root directory of this repository\ncd patlas/db_manager\n./run.py \u003cyour_database\u003e\n```\nNote: the database name is utterly important to properly say to the\nfrontend where to get the data.\n\n10) Go to `127.0.0.1:5000`.\n\n# Optimization of the resources usage by the web page\n\nUsing the `devel = true` isn't very efficient, so you can allow the\nforce directed graph to render in a `devel = true` session, then when\nyou are satisfied pause the force layout using the buttons available in\npATLAS and click at the same time `Shift+Ctrl+Space`. This will take a\nwhile but eventually it will generate a file named `filtered.json`.\nOnce you have this file you can add it to the\n`patlas/db_manager/db_app/static/json` folder and change the\n`devel` variable to `false`. This will use the previously saved\npositions to render a pre rendered network.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagofilipe12%2Fpatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiagofilipe12%2Fpatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagofilipe12%2Fpatlas/lists"}