{"id":35226390,"url":"https://github.com/zellerlab/cayman","last_synced_at":"2026-04-01T21:50:54.699Z","repository":{"id":142194448,"uuid":"602585585","full_name":"zellerlab/cayman","owner":"zellerlab","description":"A command-line tool for profiling CAZyme abundances in metagenomic datasets.","archived":false,"fork":false,"pushed_at":"2026-03-27T23:11:29.000Z","size":66108,"stargazers_count":16,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-28T01:54:30.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/zellerlab.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-16T14:23:34.000Z","updated_at":"2026-03-04T12:17:03.000Z","dependencies_parsed_at":"2025-04-17T00:35:26.884Z","dependency_job_id":"7e2eaa6d-0a73-439e-80e8-29756b937ddf","html_url":"https://github.com/zellerlab/cayman","commit_stats":null,"previous_names":["zellerlab/cayman","cschu/cayman"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/zellerlab/cayman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellerlab%2Fcayman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellerlab%2Fcayman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellerlab%2Fcayman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellerlab%2Fcayman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zellerlab","download_url":"https://codeload.github.com/zellerlab/cayman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zellerlab%2Fcayman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2025-12-30T01:14:02.076Z","updated_at":"2026-04-01T21:50:54.690Z","avatar_url":"https://github.com/zellerlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"left\" src=\"https://github.com/zellerlab/cayman/blob/main/cayman_logo_small.png\" width=\"250\"\u003e\r\n\r\n\u003cbr/\u003e\u003cbr/\u003e\r\n\r\n**Cayman** (\u003cins\u003eC\u003c/ins\u003earbohydrate \u003cins\u003ea\u003c/ins\u003ective enz\u003cins\u003ey\u003c/ins\u003emes profiling of \u003cins\u003em\u003c/ins\u003eet\u003cins\u003ea\u003c/ins\u003ege\u003cins\u003en\u003c/ins\u003eomes) is a command-line profiling tool for profiling CAZyme abundances in metagenomic datasets. It takes as input (preferably) cleaned -- quality-filtered and host-filtered -- metagenomic shotgun reads and produces a matrix of CAZyme\r\nReads-Per-Kilobase-Million (RPKM) abundances for your sample. Cayman makes heavy use of the functional profiling library [`gqlib`](https://github.com/cschu/gqlib).\r\n\r\n\u003cbr/\u003e\u003cbr/\u003e\u003cbr/\u003e\u003cbr/\u003e\r\n\r\n### Prerequisites\r\n\r\n#### Dependencies\r\n  - python\u003e=3.7,\u003c3.11\r\n  - bwa\r\n\r\n  The following python libraries need to be installed\r\n  - numpy\r\n  - pandas\r\n  - pysam\r\n  - intervaltree\r\n  - gqlib\u003e=2.14.3 (which should take care of all python library requirements)\r\n  - pyhmmer (for protein set annotation)\r\n\r\n  You will need a `bwa` installation. One way -- if you didn't install `cayman` via bioconda or if you're not using a container -- would be to use `conda env create -f environment.yml` using the provided [environment.yml](environment.yml).\r\n\r\n  #### Metagenomics reference datasets and CAZyme catalogues\r\n\r\n  Cayman uses prevalence-filtered reference data sets from the [Global Microbial Gene Catalog (GMGC)](https://gmgc.embl.de/). We annotated these datasets with our dedicated CAZyme annotation method (cf. [Ducarmon \u0026 Karcher et al.](https://www.biorxiv.org/content/10.1101/2024.01.08.574624v1)). The filtered GMGC datasets and their CAZyme annotations can be downloaded from [Zenodo](https://zenodo.org/records/10473258).\r\n\r\n\r\n  Prior to your first profiling run, you will have to build a bwa index from the respective GMGC reference dataset.\r\n\r\n  ```console\r\n  $ bwa index -p \u003cindex_name\u003e [-b blocksize] /path/to/dataset\r\n  ```\r\n\r\n  If you have enough memory available, setting `-b` to a higher value than the default (`10000000`), e.g. `100000000`, [may speed up the index generation](https://github.com/lh3/bwa/issues/104).\r\n\r\n\r\n\r\n## Installation\r\nCayman can most easily be installed via\r\n\r\n  - [Bioconda](https://anaconda.org/bioconda/cayman): `conda install -c bioconda cayman`\r\n  - [PyPI](https://pypi.org/project/cayman/): `pip install cayman` (note that you still require your own `bwa` installation)\r\n  - [Docker](https://github.com/zellerlab/cayman/pkgs/container/cayman): `docker pull docker://ghcr.io/zellerlab/cayman:latest` (or build your own with the supplied [Dockerfile](Dockerfile))\r\n  - HPC container aficionado? -- here's a [Singularity recipe](Singularity.latest) (but you can also just use `docker://ghcr.io/zellerlab/cayman:latest`)\r\n  - Dev? `git clone https://github.com/zellerlab/cayman \u0026\u0026 cd cayman \u0026\u0026 pip install .` (also requires a `bwa` installation)\r\n\r\nTypical installation time is a couple minutes. This mostly depends on the availability of the bioconda repository (for conda installation), the github container registry (pulling the container), PyPI (installation via pip / dependency installation from source code), and/or github.com (installation from source code.)\r\n\u003c!-- For your biome of interest, you will have to download the respective gene catalog and its CAZyme annotation file, which can be found on Zenodo under the following identifier:  --\u003e\r\n\r\n\r\n## Running Cayman\r\n\r\nCayman can be run from the command line as follows:\r\n\r\n**Attention: As of version 0.10.0, cayman profiling is invoked with `cayman profile` instead of `cayman`.**\r\n\r\n```\r\ncayman profile \\\r\n  \u003cinput_options\u003e \\\r\n  \u003c/path/to/annotation_db\u003e \\\r\n  \u003c/path/to/bwa_index\u003e \\\r\n  [--out_prefix \u003cprefix\u003e] \\\r\n  [--min_identity \u003cfloat\u003e] \\\r\n  [--min_seqlen \u003cint\u003e] \\\r\n  [--cpus_for_alignment \u003cint\u003e]\r\n```\r\n\r\n### Mandatory parameters\r\n\r\n* `\u003cinput_options\u003e`\r\n\r\n  1. Read files need to be in fastq format (best with `fastq` or `fq` file ending) and can be gzip compressed.\r\n\r\n  2. The `\u003cinput_options\u003e` parameters depend on the library layout of your samples:\r\n      * Paired-end data can be specified with `-1 \u003c/path/to/reads1\u003e -2 \u003c/path/to/reads2\u003e`. Each read will be counted as `0.5`.\r\n      * Single-end data can be specified with `--singles \u003c/path/to/reads\u003e`. Each read will be counted as `1`.\r\n      * Orphaned reads, i.e. paired-end reads that have lost their mate during an upstream quality control step, can be specified with `--orphans \u003c/path/to/orphans\u003e`. Each read will be counted as `0.5`.\r\n \r\n  3. Samples comprising multiple fastq files (e.g. from multiple lanes) can be provided as space-separated lists. In the case of paired-end reads, ensure that the order of the files matches (e.g. `-1 sampleX_lane1_R1.fq sampleX_lane2_R1.fq -2 sampleX_lane1_R2.fq sampleX_lane2_R2.fq`)!\r\n\r\n\r\n  4. The choice of assigning an unpaired read set to be \"true\" single-end reads or orphan reads influences the read count distribution.\r\n\r\n      * A read pair gets assigned a count of `2 x 0.5 = 1` (as both reads of a pair are derived from the same sequenced nucleic acid fragment.)\r\n      * An orphan read gets assigned a count of `1 x 0.5 = 0.5`.\r\n      * A read from a single-end library gets assigned a count of `1`.\r\n  \r\n\r\n* `\u003c/path/to/annotation_db\u003e` is the path to a 4-column text file containing the reference domain annotation. (using the bed4 format: contig,start,end,domain-type). This contains all the CAZy domain annotations for all ORFs in our gene catalog.\r\n\r\n* `\u003c/path/to/bwa_index\u003e` refers to the path to the gene catalog bwa index.\r\n\r\n### Optional parameters\r\n\r\n* `--out_prefix` is a string that will be prepended to the output files (default: `\"cayman\"`). If you want to store the output in a specific folder, then provide a path such  as `\"/path/to/folder/some_prefix\"`. Without `\"some_prefix\"`, the output files will be hidden as they start with a `.`.\r\n\r\n* `--min_identity` is the minimum sequence identity level (default: 0.97) for an alignment of your read to a CAZyme domain to be included.\r\n  \r\n* `--min_seqlen` is the minimum alignment length (actually aligned bases without soft/hard-clipping) to be included (default: 45[bp]).\r\n\r\n* `--cpus_for_alignment` the number of cpus to use for alignment (default: 1).\r\n\r\n* `--db_format [DEPRECATED]` determines the format of the cazy annotation db. This can either be `hmmer` (comma-separated with 1-based coordinates) or `bed` (tab-separated with 0-based start coordinate and 1-based end coordinate). As of v0.10.2, this parameter is no longer necessary and is only included to maintain backwards-compatibility with existing scripts.\r\n\r\n### Running with test data\r\n\r\nA test dataset can be downloaded from [Zenodo](https://zenodo.org/records/17178430/files/cayman_test_reads.tar.gz). Those are 1 million paired-end reads derived from SRA record `SRR7658598`. On a system with 16GB RAM and 4 CPU cores, this dataset can be processed within 5 minutes.\r\n\r\n## Results\r\n- `\u003cout_prefix\u003e.cazy.txt` contains the CAZy profile of the sample\r\n\r\n```\r\nfeature uniq_raw        uniq_rpkm       combined_raw    combined_rpkm\r\ntotal_reads     2498819.00000   2498819.00000   2498819.00000   2498819.00000\r\nfiltered_reads  2241860.00000   2241860.00000   2241860.00000   2241860.00000\r\nAA1     7.00000 16.09944        8.00000 18.91073\r\nAA10    0.50000 3.32879 0.50000 3.32879\r\nAA6     7.50000 30.03446        8.50000 33.29036\r\n```\r\n\r\nThe first line is the header, followed by the counts of the total aligned reads and filtered reads.\r\nThe following lines contain the counts for each CAZy family present in the sample: family name (`feature`), unique counts, unique counts rpkm-normalised, unique counts + ambiguous counts, unique counts + ambiguous counts rpkm-normalised.\r\n\r\n- `\u003cout_prefix\u003e.gene_counts.txt` contains the gene profiles of the sample. The format is identical to the CAZy profiles, featuring are the detected genes from the respective gene catalogue.\r\n\r\n- `\u003cout_prefix\u003e.aln_stats.txt` contains statistics on the alignments in the sample.\r\n\r\n\r\n## Annotating protein sets with Cayman hmms\r\n\r\nThe default `hmm_database` can be obtained from [Zenodo](https://zenodo.org/records/17178430).\r\n\r\n```\r\ncayman annotate_proteome \\\r\n  \u003c/path/to/cayman/hmm_database\u003e \\\r\n  \u003c/path/to/input/proteins\u003e \\\r\n  [ -o/--output_file \u003c/path/to/output_file\u003e, default: cayman_annotation.csv ] \\\r\n  [ -t/--threads \u003cint\u003e ] \\\r\n  [ --cutoffs \u003cpath/to/cutoff_values\u003e, default: \u003c/path/to/cayman/hmm_database/cutoffs.csv\u003e]\r\n```\r\n\r\n\r\n\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzellerlab%2Fcayman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzellerlab%2Fcayman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzellerlab%2Fcayman/lists"}