{"id":22582469,"url":"https://github.com/paccmann/titan","last_synced_at":"2025-04-10T19:12:11.810Z","repository":{"id":40264605,"uuid":"350377706","full_name":"PaccMann/TITAN","owner":"PaccMann","description":"Code for \"T Cell Receptor Specificity Prediction with Bimodal Attention Networks\" (https://doi.org/10.1093/bioinformatics/btab294, ISMB 2021)","archived":false,"fork":false,"pushed_at":"2023-08-04T08:51:33.000Z","size":49882,"stargazers_count":29,"open_issues_count":1,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-24T16:53:23.514Z","etag":null,"topics":["compound-protein-interaction","deep-learning","immunology","protein-ligand","tcr-epitope"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/PaccMann.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":"2021-03-22T14:39:43.000Z","updated_at":"2024-11-07T04:28:28.000Z","dependencies_parsed_at":"2022-07-22T08:32:10.631Z","dependency_job_id":null,"html_url":"https://github.com/PaccMann/TITAN","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaccMann%2FTITAN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaccMann%2FTITAN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaccMann%2FTITAN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaccMann%2FTITAN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaccMann","download_url":"https://codeload.github.com/PaccMann/TITAN/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248279828,"owners_count":21077408,"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":["compound-protein-interaction","deep-learning","immunology","protein-ligand","tcr-epitope"],"created_at":"2024-12-08T06:10:19.258Z","updated_at":"2025-04-10T19:12:11.790Z","avatar_url":"https://github.com/PaccMann.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python package](https://github.com/PaccMann/TITAN/actions/workflows/python-package.yml/badge.svg)](https://github.com/PaccMann/TITAN/actions/workflows/python-package.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n# TITAN\n TITAN - **T**cr ep**IT**ope bimodal **A**ttention **N**etworks\n\n## Installation\n\nThe library itself has few dependencies (see [setup.py](setup.py)) with loose requirements. \n\nCreate a virtual environment and install dependencies\n\n```console\npython -m venv --system-site-packages venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\nInstall in editable mode for development:\n```console\npip install -e .\n```\n\n\n## Data structure\nFor data handling, we make use of the `pytoda` [package](https://github.com/PaccMann/paccmann_datasets).\nIf you bring your own data, it needs to adhere to the following format:\n- `tcrs.csv`        A `.csv` file containing two columns, one for the tcr sequences and one for their IDs.\n- `epitopes.csv`    A `.csv` file containing two columns, one for the epitope sequences and one for their IDs.\n    This can optionally also be a `.smi` file (tab-separated) with the SMILES seuqences of the eptiopes.\n- `train.csv`       A `.csv` file containing three columns, one for TCR IDs, one for epitope IDs and one for the labels. This data is used for training.\n- `test.csv`       A `.csv` file containing three columns, one for TCR IDs, one for epitope IDs and one for the labels. This data is used for testing.\n\nNOTE: `tcrs.csv` and `epitopes.csv` need to contain **all** TCRs and epitopes used during training and testing. No duplicates in both sequence and IDs are allowed.\nAll data can be found in https://ibm.box.com/v/titan-dataset .\n\n\n# Example usages\n## Train a TITAN model\nThe TITAN model uses the architecture published as 'paccmann_predictor' [package](https://github.com/PaccMann/paccmann_predictor). Example parameter files are given in the params folder.\n\n\n```console\npython3 scripts/flexible_training.py \\\nname_of_training_data_files.csv \\\nname_of_testing_data_files.csv \\\npath_to_tcr_file.csv \\\npath_to_epitope_file.csv/.smi \\\npath_to_store_trained_model \\\npath_to_parameter_file \\\ntraining_name \\\nbimodal_mca\n```\n\n## Finetune an existing TITAN model\nTo load a TITAN model after pretraining and finetune it on another dataset, use the `semifrozen_finetuning.py` script. Use the parameter `number_of_tunable_layers` to control the number of layers which will be tuned, the rest will be frozen. Model will freeze epitope input channel first and the final dense layers last. Do not change the input data type (i.e. SMILES or amino acids) between pretraining and finetuning.\n\n\n```console\npython3 scripts/semifrozen_finetuning.py \\\nname_of_training_data_files.csv \\\nname_of_testing_data_files.csv \\\npath_to_tcr_file.csv \\\npath_to_epitope_file.smi \\\npath_to_pretrained_model \\\npath_to_store_model \\\ntraining_name \\\npath_to_parameter_file \\\nbimodal_mca\n```\n\n## Run trained TITAN model on data\nA trained model is provided in trained_model. The model is pretrained on BindingDB and finetuned using the semifrozen setting, on full TCR sequences and with SMILES encoding of epitopes. All parameters can be found in the parameter files provided. \n\n```console\npython3 scripts/flexible_model_eval.py \\\nname_of_test_data_file.csv \\\npath_to_tcr_file.csv \\\npath_to_epitope_file.smi \\\npath_to_trained_model_folder \\\nbimodal_mca \\\nsave_name\n```\n\n## Evaluate K-NN baseline on cross validation\n\nThe script `scripts/knn_cv.py` uses the KNN baseline model of the paper and performs a cross validation.\nThe script can be used in two modes, *shared* and *separate*. *Shared* is the default mode as specified [above](#Data-structure). In *separate* mode, the TCRs and epitope sequences for training and testing dont need to be in the same file, but can be split across two files. To use this mode, simply provide additional paths to `-test_tcr` and `test_ep` arguments.\n\n\n```console\npython3 scripts/knn_cv.py \\\n-d path_to_data_folder \\\n-tr name_of_training_data_files.csv \\\n-te name_of_testing_data_files.csv \\\n-f 10 \\\n-ep path_to_epitope_file.ccsv \\\n-tcr path_to_tcr_file.csv \\\n-r path_to_result_folder \\\n-k 25\n```\ntype `python3 scripts/knn_cv.py -h` for help.\nThe data in `data_folder` needs to be structured as:\n\n```console\ndata_path\n├── fold0\n│   ├── name_of_training_data_files.csv\n│   ├── name_of_testing_data_files.csv\n...\n├── fold9\n│   ├── name_of_training_data_files.csv\n│   ├── name_of_testing_data_files.csv\n```\n\n## Data Handling\nTo generate full sequences of TCRs from CDR3 sequence and V and J segment names, the `cdr3_to_full_seq.py` script can be used. The script relies on the user having downloaded a fasta files containing the Names of V and J segments with their respecive sequences called `V_segment_sequences.fasta` and `J_segment_sequences.fasta`. These can be downloaded from IMGT.org. Header names must be provided to the script to adapt to different format of the input file.\n\n```console\npython3 scripts/cdr3_to_full_seq.py \\\ndirectoy_with_VJ_segment_fasta_files \\\npath_to_file_with_input_sequences.csv \\\nv_seq_header \\\nj_seq_header \\\ncdr3_header \\\npath_to_output_file.csv\n```\n\n\n## Citation\nIf you use `titan` in your projects, please cite the following:\n\n```bib\n@article{weber2021titan\n    author = {Weber, Anna and Born, Jannis and Rodriguez Martinez, Maria},\n    title = \"{TITAN: T-cell receptor specificity prediction with bimodal attention networks}\",\n    journal = {Bioinformatics},\n    volume = {37},\n    number = {Supplement_1},\n    pages = {i237-i244},\n    year = {2021},\n    month = {07},\n    issn = {1367-4803},\n    doi = {10.1093/bioinformatics/btab294},\n    url = {https://doi.org/10.1093/bioinformatics/btab294}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaccmann%2Ftitan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaccmann%2Ftitan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaccmann%2Ftitan/lists"}