{"id":13639186,"url":"https://github.com/shenwei356/gtaxon","last_synced_at":"2025-12-30T04:24:13.842Z","repository":{"id":57553661,"uuid":"51646067","full_name":"shenwei356/gtaxon","owner":"shenwei356","description":"gTaxon - a fast cross-platform NCBI taxonomy data querying (gi2taxid, taxid2taxon, name2taxid, LCA) tool, with cmd client and REST API server for both local and remote server. ","archived":false,"fork":false,"pushed_at":"2016-07-24T06:30:24.000Z","size":13734,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-03T01:14:09.267Z","etag":null,"topics":["bioinformatics","client","golang","lca","restful","server","taxonomy"],"latest_commit_sha":null,"homepage":"http://github.com/shenwei356/gtaxon","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shenwei356.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-13T13:00:49.000Z","updated_at":"2020-04-29T07:57:01.000Z","dependencies_parsed_at":"2022-09-26T18:41:15.700Z","dependency_job_id":null,"html_url":"https://github.com/shenwei356/gtaxon","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/shenwei356%2Fgtaxon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shenwei356%2Fgtaxon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shenwei356%2Fgtaxon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shenwei356%2Fgtaxon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shenwei356","download_url":"https://codeload.github.com/shenwei356/gtaxon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810296,"owners_count":17206729,"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":["bioinformatics","client","golang","lca","restful","server","taxonomy"],"created_at":"2024-08-02T01:00:58.479Z","updated_at":"2025-12-30T04:24:13.809Z","avatar_url":"https://github.com/shenwei356.png","language":"Go","funding_links":[],"categories":["Sequence Analysis and Manipulation"],"sub_categories":[],"readme":"# gTaxon\n\n## Introduction\n\ngTaxon - a fast cross-platform NCBI taxonomy data querying tool,\nwith cmd client and REST API server for both local and remote server.\n[http:///github.com/shenwei356/gtaxon](http:///github.com/shenwei356/gtaxon)\n\n## Supporting querying types\n\n|    Query type    |   Function                               | Local/Remote |\n|------------------|------------------------------------------|--------------|\n|   gi_taxid_nucl  |   query TaxId by Gi (nucl)               |  Both        |\n|   gi_taxid_prot  |   query TaxId by Gi (prot)               |  Both        |\n|   taxid2taxon    |   query Taxon by TaxId                   |  Remote      |\n|   name2taxid     |   query TaxId by Name                    |  Remote      |\n|   lca            |   query Lowest Common Ancestor by TaxIds |  Remote      |\n\n## Features\n\n- Easy to install. **Only ONE single executable binary file**.\n No scared source compilation, installing extra packages,\n configuring environment variables\n- **Cross platform**. gTaxon is implemented in [golang](https://golang.org).\nExecutable binary files for most popular operating system (Linux, Mac OS X,\nWindows, \\*BSD ) are available.\nSee [Release](https://github.com/shenwei356/gtaxon/releases) page.\n- Supporting querying from **both LOCAL and REMOTE server** by REST API,\n which is also easily called by various clients of other languages.\n gTaxon has command-line client `gtaxon cli local` for local query and\n `gtaxon cli remote` for remote query.\n- **Fast**. See Section Performance.\n\n## Performance\n\n### gi2taxid\n\n[Detail](https://github.com/shenwei356/gtaxon/blob/master/testdata/PERFORMANCE.md)\n\nNote: 1) bolt database utilizes the operating system's page cache,\nso repeat queries are faster than the first query. 2) \"remote query\" actually is from local host\nwith minimum network latency\n\n| dataset        | local query     | remote query     | remote query (repeated) |\n|----------------|-----------------|------------------|-------------------------|\n| small (0.25K)  |  0.013 s        |   0.013 s        |  0.009s                 |\n| medium (25K)   |  0.38 s         |   0.57 s         |  0.178s                 |\n| large (2.5M)   |  17 s           |   1min 38s       |  20 s                   |\n\n## Download \u0026\u0026 Install\n\nSteps:\n\n1. Just download and uncompress the executable binary files of your operating system from  [Release](https://github.com/shenwei356/gtaxon/releases) page.\n\n2. Rename it to `gtaxon.exe` (for Windows) or `gtaxon` (for other operating systems) for convenience, and then run it in command-line interface, no compilation, no dependencies.\n\nYou can also add the directory of the executable file to environment variable `PATH`, so you can run `gtaxon` anywhere.\n\n1. For windows, the simplest way is copy it to ` C:\\WINDOWS\\system32`.\n\n2. For Linux, simply copy it to `/usr/local/bin` or add the path of gtaxon to environment variable `PATH`:\n\n        chmod a+x /PATH/OF/GTAXON/gtaxon\n        echo export PATH=\\$PATH:/PATH/OF/GTAXON \u003e\u003e ~/.bashrc\n\n## Usage\n\n### Loading data to database\n\n1. Initializing database.\n\n        gtaxon db init\n\n2. Importing data\n\n    Supported file types includes:\n\n        ================================================\n          data type                  files\n        ------------------------------------------------\n        gi_taxid_nucl          gi_taxid_nucl.dmp.gz\n        gi_taxid_prot          gi_taxid_prot.dmp.gz\n        nodes                  nodes.dmp\n        names                  names.dmp\n        divisions              division.dmp\n        gencodes               gencode.dmp\n        ================================================\n\n    For gi2taxid\n\n        # ~ 16 min for me\n        gtaxon db import -f -t gi_taxid_prot gi_taxid_prot.dmp.gz\n\n    For taxon query\n\n        gtaxon db import -f -t nodes nodes.dmp\n        gtaxon db import -f -t names names.dmp\n        gtaxon db import -f -t divisions division.dmp\n        gtaxon db import -f -t gencodes gencode.dmp\n\n### Querying from local (Only for gi2taxid)\n\n- few queries\n\n        gtaxon cli local -t gi_taxid_prot 139299181 139299182\n\n- from file\n\n        gtaxon cli local -t gi_taxid_prot -f gi_list_file\n\n### Querying from remote server\n\n1. Starting server\n\n        gtaxon server\n\n2. Query TaxId by Gi (gi_taxid_nucl or gi_taxid_prot)\n\n    - few queries\n\n            gtaxon cli remote -t gi_taxid_prot 139299181 139299182\n\n    - from files\n\n            gtaxon cli remote -H 192.168.1.101 -P 8080 -t gi_taxid_prot -f gi_list_file\n\n3. Query TaxId by Name (name2taxid)\n\n    Limiting name class, using regular expression\n\n        gtaxon cli remote -t name2taxid --use-regexp --name-class \"scientific name\" sapiens\n        [INFO] Query TaxId by Name from host: 127.0.0.1:8080\n        sapiens 9606(Homo sapiens),1035824(Trichuris sp. ex Homo sapiens JP-2011),1573476(Homo sapiens/Rattus norvegicus xenograft),324570(Phrynium sapiense),63221(Homo sapiens neanderthalensis),1383439(Homo sapiens/Mus musculus xenograft),741158(Homo sapiens ssp. Denisova),399796(Macrobiotus sapiens),349050(Ficus casapiensis),1131344(Homo sapiens x Mus musculus hybrid cell line),270523(Tetragonula sapiens)\n\n        gtaxon cli remote -t name2taxid --use-regexp --name-class \"genbank common name\" human mouse\n        [INFO] Query TaxId by Name from host: 127.0.0.1:8080\n        human   121226(Pediculus humanus capitis),121225(Pediculus humanus),51028(Enterobius vermicularis),121224(Pediculus humanus corporis),433352(Diplogonoporus grandis),36087(Trichuris trichiura),115427(Dermatobia hominis),9606(Homo sapiens)\n        mouse   42410(Peromyscus eremicus),1595964(Apomys sacobianus),10105(Mus minutoides),221913(Pseudomys hermannsburgensis),240587(Thalpomys cerradensis),409025(Peromyscus melanocarpus) ...\n\n4. Query Taxon by TaxId (taxid2taxon)\n\n        gtaxon cli remote -t taxid2taxon 9\n        # result is similar with result of example 5)\n\n\n5. Query Lowest Common Ancestor by TaxIds (lca)\n\n        gtaxon cli remote -t lca 9606,63221\n        [INFO] Query LCA by TaxIds from host: 127.0.0.1:8080\n        Query TaxIDs: 9606,63221\n        Taxon: {\n          \"TaxId\": 9606,\n          \"ScientificName\": \"Homo sapiens\",\n          \"OtherNames\": [\n            {\n              \"ClassCDE\": \"authority\",\n              \"DispName\": \"Homo sapiens Linnaeus, 1758\"\n            },\n            {\n              \"ClassCDE\": \"genbank common name\",\n              \"DispName\": \"human\"\n            },\n            {\n              \"ClassCDE\": \"common name\",\n              \"DispName\": \"man\"\n            }\n          ],\n          \"ParentTaxId\": 9605,\n          \"Rank\": \"species\",\n          \"Division\": \"Primates\",\n          \"GeneticCode\": {\n            \"GCId\": 1,\n            \"GCName\": \"Standard\"\n          },\n          \"MitoGeneticCode\": {\n            \"MGCId\": 2,\n            \"MGCName\": \"Vertebrate Mitochondrial\"\n          },\n          \"Lineage\": \"cellular organisms; Eukaryota; Opisthokonta; Metazoa; Eumetazoa; Bilateria; Deuterostomia; Chordata; Craniata; Vertebrata; Gnathostomata; Teleostomi; Euteleostomi; Sarcopterygii; Dipnotetrapodomorpha; Tetrapoda; Amniota; Mammalia; Theria; Eutheria; Boreoeutheria; Euarchontoglires; Primates; Haplorrhini; Simiiformes; Catarrhini; Hominoidea; Hominidae; Homininae; Homo\",\n          \"LineageEx\": [\n            {\n              \"TaxId\": 131567,\n              \"ScientificName\": \"cellular organisms\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 2759,\n              \"ScientificName\": \"Eukaryota\",\n              \"Rank\": \"superkingdom\"\n            },\n            {\n              \"TaxId\": 33154,\n              \"ScientificName\": \"Opisthokonta\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 33208,\n              \"ScientificName\": \"Metazoa\",\n              \"Rank\": \"kingdom\"\n            },\n            {\n              \"TaxId\": 6072,\n              \"ScientificName\": \"Eumetazoa\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 33213,\n              \"ScientificName\": \"Bilateria\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 33511,\n              \"ScientificName\": \"Deuterostomia\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 7711,\n              \"ScientificName\": \"Chordata\",\n              \"Rank\": \"phylum\"\n            },\n            {\n              \"TaxId\": 89593,\n              \"ScientificName\": \"Craniata\",\n              \"Rank\": \"subphylum\"\n            },\n            {\n              \"TaxId\": 7742,\n              \"ScientificName\": \"Vertebrata\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 7776,\n              \"ScientificName\": \"Gnathostomata\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 117570,\n              \"ScientificName\": \"Teleostomi\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 117571,\n              \"ScientificName\": \"Euteleostomi\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 8287,\n              \"ScientificName\": \"Sarcopterygii\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 1338369,\n              \"ScientificName\": \"Dipnotetrapodomorpha\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 32523,\n              \"ScientificName\": \"Tetrapoda\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 32524,\n              \"ScientificName\": \"Amniota\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 40674,\n              \"ScientificName\": \"Mammalia\",\n              \"Rank\": \"class\"\n            },\n            {\n              \"TaxId\": 32525,\n              \"ScientificName\": \"Theria\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 9347,\n              \"ScientificName\": \"Eutheria\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 1437010,\n              \"ScientificName\": \"Boreoeutheria\",\n              \"Rank\": \"no rank\"\n            },\n            {\n              \"TaxId\": 314146,\n              \"ScientificName\": \"Euarchontoglires\",\n              \"Rank\": \"superorder\"\n            },\n            {\n              \"TaxId\": 9443,\n              \"ScientificName\": \"Primates\",\n              \"Rank\": \"order\"\n            },\n            {\n              \"TaxId\": 376913,\n              \"ScientificName\": \"Haplorrhini\",\n              \"Rank\": \"suborder\"\n            },\n            {\n              \"TaxId\": 314293,\n              \"ScientificName\": \"Simiiformes\",\n              \"Rank\": \"infraorder\"\n            },\n            {\n              \"TaxId\": 9526,\n              \"ScientificName\": \"Catarrhini\",\n              \"Rank\": \"parvorder\"\n            },\n            {\n              \"TaxId\": 314295,\n              \"ScientificName\": \"Hominoidea\",\n              \"Rank\": \"superfamily\"\n            },\n            {\n              \"TaxId\": 9604,\n              \"ScientificName\": \"Hominidae\",\n              \"Rank\": \"family\"\n            },\n            {\n              \"TaxId\": 207598,\n              \"ScientificName\": \"Homininae\",\n              \"Rank\": \"subfamily\"\n            },\n            {\n              \"TaxId\": 9605,\n              \"ScientificName\": \"Homo\",\n              \"Rank\": \"genus\"\n            }\n          ]\n        }\n\n\n\n## Configuration file for Convenience\n\nDefault config file is: `$HOME/.gtaxon.yaml`\n\nThis is useful when querying from remote server,\nwe could type few words by saving flags like host and port to config file.\n\nSee https://github.com/ogier/pflag\n\n## REST APIs\n\n1. gi2taxid\n\n        http://127.0.0.1:8080/gi2taxid?db=gi_taxid_prot\u0026gi=139299191111\u0026gi=139299181\u0026gi=139299175\n\n2. name2taxid\n\n        http://localhost:8080/name2taxid?regexp=true\u0026class=genbank+common+name\u0026name=human\u0026name=mouse\n\n3. taxid2taxon\n\n        http://localhost:8080/taxid2taxon?taxid=9906\u0026taxid=2\n\n4. lca\n\n        http://localhost:8080/lca?taxids=9606,63221\u0026taxids=1,2\n\n\nYou can also write client in your favorite programming language.\n\n## Implement details\n\nAPI reference: [godoc](https://godoc.org/github.com/shenwei356/gtaxon/taxon)\n\n- Programming language: [Go](https://golang.org)\n- Database: [bolt](https://github.com/boltdb/bolt), an embedded key/value database for Go\n- Web server: [gin](https://github.com/gin-gonic/gin), a fast HTTP web framework written in Go\n\n## Caveats\n\n- 64bit operating system is better.\n- `bolt` database utilizes the operating system's page cache, larger virtual memory is better.\n- Database file size is 16G after loading gi_taxid_prot.dmp.gz\n- About 1.5G RAM usage after starting server\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshenwei356%2Fgtaxon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshenwei356%2Fgtaxon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshenwei356%2Fgtaxon/lists"}