Substrate annotations

[SilasK]

Hello,

If I coorectly understand cayman maps reads to the GMGC and then converts the genes abundances to CAZy family abundance.

I already mapped my samples to GMGC of human and pigs. Is it possible to use your annotation tables outside of cayman?
I found your CAZY annotations on zenodo. are the substrate annotations also available? I mean the supplementary tables from the mansucript.

Thank you very much

[cschu]

Hi @SilasK ,

You could take the cayman annotation tables, convert them to bed4 (comma-to-tab and start=start-1, in case that's not known), then use bedtools intersect with your bam files.

Re the other question -- this is better answered by @qrducarmon or @karchern (unfortunately, I don't know.)

Best,
Christian

[qducarmon]

Hi,

To add to Christian's comment, the most recent annotation file (which was used for our revisions) can be found here https://github.com/zellerlab/cayman_paper/tree/main/data/Glycan_Annotations and is naturally the 2025 file. Hope this answers your question sufficiently, let us know if you have any other questions / issues.

[SilasK]

Thank you very much for the quick replies.
If I understand correctly you would count the coverage only over the CAZY annotated genes for the CAZY abundance.

What I thought is to use the coverage over the whole gene from GMGC as counts for a cazy.
In cases the CMB could make the annotation more specific isn't it?

[cschu]

Hi @SilasK ,

Indeed, we're only counting the genes / domain hits from the respective cayman catalogue. However, the RPKMs are calculated using all input reads that pass the filter criteria.

Re whole gene coverage vs domain only -- this is the result of long discussions. The gist of it is that only reads that actually overlap an annotated domain are seen as "hard" evidence that the domain is actually present. Of course one could instead use whole genes, I do not remember whether the two approaches were ever benchmarked.

Re your comment about the CBM (I assume it's a typo?), I do not completely follow could you maybe elaborate?

Cheers,
Christian

[SilasK]

I agree there are arguments for both using motive coverage or gene coverage.

I meant the carbohydrate-binding module (CBM) annotations which are also in your table. As far as I understand they add specificity to the CAZy annotations. So Idally one would keep the CBM and enzyme annotation togheter.

[cschu]

Ah, do you mean that various columns (activty, glycan, ...) of the CBM annotations should also appear in the cayman profiling output?

[SilasK]

I think it would be worth adding them yes. but maybe as a different category. if you want to make a mucin/fiber ratio you should look either the CBMs or the enzymes but not both mixed..

[qrducarmon]

Regarding the annotations appearing in the cayman profiling output, we will consider this for the future, thanks a lot for the suggestion, it's useful to know if users would actually value this. Regarding the mucin/fiber ratio (or whatever ratio you would want to calculate), I can see where you are coming from, but I think different people will have different opinions regarding looking either at the enzymes, only at CBMs etc. That is exactly the reason why we provided a subfamily-resolved scheme per family, so that the users will have full control over what they want to include for calculating such ratios. So if you want the CBMs and enzymes to be strictly separated for calculating those ratios, that should be quite straightforward with the annotations we provide. If not, please get back to us and thanks again for the suggestions!

[alfbenpa]

Hi,
I'm trying to use Cayman for profiling metagenomic data. However, I'm getting some issues that appear to be related to the downloaded annotation files. I get the following error messages when I try to run the tool with mandatory options. Can you provide feedback to help resolve such issues?

[2025-12-02 12:53:43,323] Version: 0.10.1 gqlib: 2.14.4
[2025-12-02 12:53:43,323] Command: cayman profile --db_format bed -1 test_L004_1.fq.gz -2 test_L004_2.fq.gz --min_seqlen 100 --cpus_for_alignment 50 /home/abenitez/DataBase_Cayman_v1/annots/GMGC10.human-gut.95nr.no-rare.0.5.percent.prevalence_all_v3_FINAL.csv /home/abenitez/DataBase_Cayman_v1/gene_catalogues/GMGC10_human_gut_nr
[2025-12-02 12:53:43,324] First pass: gathering category and feature information.
Namespace(log_level=20, debug=False, command='profile', annotation_db='/home/abenitez/DataBase_Cayman_v1/annots/GMGC10.human-gut.95nr.no-rare.0.5.percent.prevalence_all_v
3_FINAL.csv', bwa_index='/home/abenitez/DataBase_Cayman_v1/gene_catalogues/GMGC10_human_gut_nr', db_format='bed', reads1=['test_L004_1.fq.gz'], reads2=['test_L004_2.fq.gz
'], singles=None, orphans=None, out_prefix='cayman', min_identity=0.97, min_seqlen=100, cpus_for_alignment=50, func=<function run_profile at 0x7f8d181feee0>, aligner='bwa
')

Traceback (most recent call last):
File "/opt/sci-soft/software/Cayman/0.10.1-foss-2021b-Python-3.9.6/bin/cayman", line 8, in
sys.exit(main())
File "/opt/sci-soft/software/Cayman/0.10.1-foss-2021b-Python-3.9.6/lib/python3.9/site-packages/cayman/main.py", line 36, in main
args.func(args)
File "/opt/sci-soft/software/Cayman/0.10.1-foss-2021b-Python-3.9.6/lib/python3.9/site-packages/cayman/functions.py", line 43, in run_profile
db_importer = SmallDatabaseImporter(
File "/opt/sci-soft/software/Python/3.9.6-GCCcore-11.2.0/lib/python3.9/site-packages/gqlib/db/db_import.py", line 198, in init
super().init(logger, input_data, db_path=db_path, db_session=db_session)
File "/opt/sci-soft/software/Python/3.9.6-GCCcore-11.2.0/lib/python3.9/site-packages/gqlib/db/db_import.py", line 28, in init
self.process_annotations(input_data)
File "/opt/sci-soft/software/Python/3.9.6-GCCcore-11.2.0/lib/python3.9/site-packages/gqlib/db/db_import.py", line 98, in process_annotations
annotation_data = self.parse_annotations(_in)
File "/opt/sci-soft/software/Python/3.9.6-GCCcore-11.2.0/lib/python3.9/site-packages/gqlib/db/db_import.py", line 226, in parse_annotations
start = int(start) + self.db_settings.offsets[0]
ValueError: invalid literal for int() with base 10: 'start'
srun: error: gen01: task 0: Exited with exit code 1

[cschu]

Hi @alfbenpa ,

Could you please confirm that the GMGC10.human-gut.95nr.no-rare.0.5.percent.prevalence_all_v3_FINAL.csv is the original comma-separated file?

If so, then please try with --db_format hmmer

As a side note, there is no point in using 50 CPUs for alignment. bwa mem performance exhibits diminishing returns with more than 8 CPUs.

Please let me know if this resolves your issue.

Best,
Christian

Edit: Corrected wrong db format suggestion.

[alfbenpa]

Hi @cschu ,
Thanks for your prompt reply. First of all, I confirm the GMGC10.human-gut.95nr.no-rare.0.5.percent.prevalence_all_v3_FINAL.csv file is the original comma-separated file downloaded from Cayman repository.

I tried your suggestion to change the annotation file format to "hmmer", and apparently it now runs smoothly.
Thanks a lot for your help. I will get back to you if any other issues come up—greetings to Georg and all the team.

Best wishes,

Alfonso

[alfbenpa]

Hi @cschu ,
I've been trying to complete an assessment with test and sample fastq.gz files with the same results:

No alignments present in stream.
Processed 0 reads (0 alignments) ...
Finished.

I've tried with paired and single data with the same results. Do you have any other suggestions about this?
Best,

Alfonso

[cschu]

Dear @alfbenpa ,

Could you please tell me the complete command that you use for the test. Furthermore, if you could please tell me which cayman version this happens with, i.e. from github and built yourself, container, conda, etc ?

Thanks,
Christian

[alfbenpa]

Dear @cschu ,
It was the same as stated in my initial issue report. I'm using Version: 0.10.1 + gqlib: 2.14.4 built in a HPC server by compiling via the "Module" system. Anyway, I tried again with default --min_seqlen and --min_identity, and I got results. It seems that I had set a strict value for the first one --min_seqlen 100. Sorry for any inconvenience.
Best regards,

Alfonso

[cschu]

Ok good, that explains it. Similar thing can happen with the --min_identity (happened to me...)

Best,
Christian