{"id":34079828,"url":"https://github.com/clintval/tp53","last_synced_at":"2026-06-01T10:32:03.705Z","repository":{"id":268047691,"uuid":"902543515","full_name":"clintval/tp53","owner":"clintval","description":"Tools for programmatically annotating VCFs with the Seshat TP53 database","archived":false,"fork":false,"pushed_at":"2024-12-16T17:36:36.000Z","size":1930,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-28T22:35:17.949Z","etag":null,"topics":["mutation","seshat","tp53","vcf"],"latest_commit_sha":null,"homepage":"","language":"Scala","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/clintval.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":"2024-12-12T19:18:50.000Z","updated_at":"2025-11-18T02:30:00.000Z","dependencies_parsed_at":"2025-12-14T11:03:34.635Z","dependency_job_id":null,"html_url":"https://github.com/clintval/tp53","commit_stats":null,"previous_names":["clintval/tp53"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/clintval/tp53","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clintval%2Ftp53","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clintval%2Ftp53/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clintval%2Ftp53/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clintval%2Ftp53/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clintval","download_url":"https://codeload.github.com/clintval/tp53/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clintval%2Ftp53/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33771628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["mutation","seshat","tp53","vcf"],"created_at":"2025-12-14T11:03:15.353Z","updated_at":"2026-06-01T10:32:03.700Z","avatar_url":"https://github.com/clintval.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tp53 \u0026 seshat\n\n[![Install with Bioconda](https://img.shields.io/badge/Install%20with-bioconda-brightgreen.svg)](http://bioconda.github.io/recipes/seshat/README.html)\n[![Anaconda Version](https://anaconda.org/bioconda/seshat/badges/version.svg)](https://anaconda.org/bioconda/seshat)\n[![Language](https://img.shields.io/badge/language-scala-c22d40.svg)](https://www.scala-lang.org/)\n[![Java Version](https://img.shields.io/badge/java-11,17,21-c22d40.svg)](https://github.com/AdoptOpenJDK/homebrew-openjdk)\n[![Python Versions](https://img.shields.io/badge/python-3.11_|_3.12_|_3.13-blue)](https://github.com/clintval/typeline)\n\nTools for programmatically annotating VCFs with the [Seshat TP53 database](http://vps338341.ovh.net/).\n\n![Mount Shuksan](.github/img/cover.jpg)\n\n## Installation\n\nInstall with the Conda or Mamba package manager after setting your [Bioconda channels](https://bioconda.github.io/#usage):\n\n```console\nconda install seshat\n```\n\n## Quick Usage Example\n\nFor round-trip Seshat annotation of a VCF file, execute a command like:\n\n```bash\n❯ seshat round-trip \\\n    --input \"sample.library.vcf\" \\\n    --output \"sample.library\" \\\n    --email \"example@example.com\"\n```\n```console\n15:23:53 INFO  SeshatUploadVcf - Executing command: python3 -m tp53.seshat.upload_vcf --input sample.library.vcf --assembly hg38 --email example@example.com --url http://vps338341.ovh.net/batch_analysis --wait-for 5\n15:23:54 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 0 %...\n15:23:54 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 60%...\n15:23:54 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 73%...\n15:23:54 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Upload complete!\n15:23:54 INFO  SeshatFindInGmail - Executing command: python3 -m tp53.seshat.find_in_gmail --input sample.library.vcf --output sample.library --newer-than 5 --wait-for 200\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Successfully logged into the Gmail service.\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Querying for a VCF named: sample.library.vcf\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Searching Gmail messages with: sample.library.vcf from:support@genevia.fi newer_than:5h subject:\"Results of batch analysis\"\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Message found with the following metadata: {'id': '193cbfdcdb5bc87c', 'threadId': '193cbfdcdb5bc87c'}\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Message contents are as follows:\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Results of batch analysis\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Analyzed batch file:\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  sample.library.vcf\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Time taken to run the analysis:\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  0 minutes 10 seconds\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Summary:\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  The input file contained\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:      23 mutations out of which\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:      23 were TP53 mutations.\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Writing attachment to ZIP archive: sample.library.vcf.seshat.zip\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Extracting ZIP archive: sample.library.vcf.seshat.zip\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Output file renamed to: sample.library.seshat.short-20241215_212333_875215.tsv\n15:23:55 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Output file renamed to: sample.library.seshat.long-20241215_212333_969299.tsv\n15:23:55 INFO  SeshatMerge - Starting to zip annotations and VCF variants.\n15:23:56 INFO  SeshatMerge - Successfully annotated variant calls.\n```\n\nSee [Upload a VCF to Seshat](#upload-a-vcf-to-seshat) and [Download a Seshat Annotation from Gmail](#download-a-seshat-annotation-from-gmail) for pre-requisite setup.\n\n## Upload a VCF to Seshat\n\nUpload a VCF to the Seshat annotation webserver using a headless browser.\n\n```bash\n❯ seshat upload-vcf \\\n    --input \"sample.library.vcf\" \\\n    --email \"example@gmail.com\"\n```\n```console\n16:11:02 INFO  SeshatUploadVcf - Executing command: python3 -m tp53.seshat.upload_vcf --input sample.library.vcf --assembly hg38 --email example@example.com --url http://vps338341.ovh.net/batch_analysis --wait-for 200\n16:11:03 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 0 %...\n16:11:03 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 60%...\n16:11:03 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Uploading 66%...\n16:11:03 INFO  SeshatUploadVcf - INFO:tp53.seshat.upload_vcf:Upload complete!\n```\n\nThis tool is used to programmatically configure and upload batch variants in VCF format to the Seshat annotation server.\nThe tool works by building a headless Chrome browser instance and then interacting with the Seshat website directly through simulated key presses and mouse clicks.\n\n###### VCF Input Requirements\n\nSeshat will not let the user know why a VCF fails to annotate, but it has been observed that Seshat can fail to parse some of [VarDictJava](https://github.com/AstraZeneca-NGS/VarDictJava)'s structural variants (SVs) as valid variant records.\nOne solution that has worked in the past is to remove SVs.\nThe following command will exclude all variants with a non-empty SVTYPE INFO key:\n\n```bash\n❯ bcftools view sample.library.vcf \\\n    --exclude 'SVTYPE!=\".\"' \\\n  \u003e sample.library.noSV.vcf\n```\n\n###### Automation\n\nThere are no terms and conditions posted on the Seshat annotation server's website, and there is no server-side `robots.txt` rule set.\nIn lieu of usage terms, we strongly encourage all users of this script to respect the Seshat resource by adhering to the following best practice:\n\n- **Minimize Load**: Limit the rate of requests to the server\n- **Minimize Connections**: Limit the number of concurrent requests\n\n###### Environment Setup\n\nThis script relies on Google Chrome:\n\n```console\n❯ brew install --cask google-chrome\n```\n\nDistributions of MacOS may require you to authenticate the Chrome driver ([link](https://stackoverflow.com/a/60362134)).\n\n## Download a Seshat Annotation from Gmail\n\nDownload Seshat VCF annotations by awaiting a server-generated email.\n\n```bash\n❯ seshat find-in-gmail \\\n    --input \"sample.library.vcf\" \\\n    --output \"sample.library\" \\\n    --credentials \"~/.secrets/credentials.json\"\n```\n```console\n16:14:06 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Successfully logged into the Gmail service.\n16:14:06 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Querying for a VCF named: sample.library.vcf\n16:14:06 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Searching Gmail messages with: sample.library.vcf from:support@genevia.fi newer_than:10h subject:\"Results of batch analysis\"\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Message found with the following metadata: {'id': '193cc295aa6ae27d', 'threadId': '193cc295aa6ae27d'}\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Message contents are as follows:\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Results of batch analysis\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Analyzed batch file:\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  sample.library.vcf\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Time taken to run the analysis:\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  0 minutes 10 seconds\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  Summary:\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:  The input file contained\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:      23 mutations out of which\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:      23 were TP53 mutations.\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Writing attachment to ZIP archive: sample.library.vcf.seshat.zip\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Extracting ZIP archive: sample.library.vcf.seshat.zip\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Output file renamed to: sample.library.seshat.short-20241215_221114_586973.tsv\n16:14:07 INFO  SeshatFindInGmail - INFO:tp53.seshat.find_in_gmail:Output file renamed to: sample.library.seshat.long-20241215_221114_675170.tsv\n```\n\nThis tool is used to programmatically wait for, and retrieve, a batch results email from the Seshat TP53 annotation server.\nThe tool works by searching a user-controlled Gmail inbox for a recent Seshat email that contains the result annotations for a given VCF input file, by name.\nIt is critically important to be aware that there is no way to prove which annotation files, as they arrive via email, are to be linked with which VCF file on disk.\n\nThis tool assists in the correct pairing of VCF input files, and subsequent annotation files, by letting you specify how many hours back in time you will let the Gmail query search (`--newer-than`).\nLimiting the window of time in which an email should have arrived minimizes the chance of discovering stale annotation files from an old Seshat execution in the cases where VCF filenames may be non-unique.\nIf the batch results email from the Seshat annotation server has not yet arrived, this tool will wait a set number of seconds (`--wait-for`) before exiting with exception.\nIt normally takes less than 1 minute for the Seshat server to annotate an average TP53-only VCF.\n\n###### Search Criteria\n\nThe following rules are used to find annotation files:\n\n1. The email contains the filename of the input VCF\n2. The email subject line must contain \"Results of batch analysis\"\n3. The email is at least `--newer-than` hours old\n4. The email is from the address [support@genevia.fi](mailto:support@genevia.fi)\n\n###### Outputs:\n\n- `\u003coutput\u003e.seshat.long-\\\\d{8}_\\\\d{6}_\\\\d{6}.tsv`: The long format Seshat annotations for the input VCF\n- `\u003coutput\u003e.seshat.short-\\\\d{8}_\\\\d{6}_\\\\d{6}.tsv`: The short format Seshat annotations for the input VCF\n- `\u003coutput\u003e.seshat.zip`: The original ZIP archive from Seshat\n\n###### Gmail Authentication\n\nYou must create a Google developer's OAuth file.\nFirst-time 2FA may be required depending on the configuration of your Gmail service.\nIf 2FA is required, then this script will block until you acknowledge your 2FA prompt.\nA 2FA prompt is often delivered through an auto-opening web browser.\n\nTo create a Google developer's OAuth file, navigate to the following URL and follow the instructions.\n\n- [Authorize Credentials for a Desktop Application](https://developers.google.com/gmail/api/quickstart/python#authorize_credentials_for_a_desktop_application)\n\nEnsure your OAuth file is configured as a \"Desktop app\" and then download the credentials as JSON.\nSave your credentials file somewhere safe, ideally in a secure user folder with restricted permissions (`chmod 700`).\nSet your OAuth file permissions to also restrict unwarranted access (`chmod 600`).\n\nThis script will store a cached token after first-time authentication is successful.\nThis cached token can be found in the user's home directory within a hidden directory.\nToken caching greatly speeds up continued executions of this script.\nAs of now, the token is cached at the following location:\n\n```bash\n\"~/.tp53/seshat/seshat-gmail-find-token.pickle\"\n```\n\nIf the cached token is missing, or becomes stale, then you will need to provide your OAuth credentials file.\n\nA typical Google developer's OAuth file is of the format:\n\n```json\n{\n\"installed\": {\n    \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n    \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n    \"client_id\": \"272111863110-csldkfjlsdkfjlksdjflksdincie.apps.googleusercontent.com\",\n    \"client_secret\": \"sdlfkjsdlkjfijciejijcei\",\n    \"project_id\": \"gmail-access-2398293892838\",\n    \"redirect_uris\": [\n        \"urn:ietf:wg:oauth:2.0:oob\",\n        \"http://localhost\"\n    ],\n    \"token_uri\": \"https://oauth2.googleapis.com/token\"\n    }\n}\n```\n\n###### Server Failures\n\nIf Seshat fails to annotate the VCF file but still emails the user a response, then this tool will emit the email body to standard error and exit with a non-zero status.\n\n## Merge Annotations into a VCF\n\nMerge Seshat annotations into the `INFO` fields of the VCF.\n\n```bash\n❯ seshat merge \\\n    --input \"sample.library.vcf\" \\\n    --annotations \"sample.library.seshat.long-20241215_221114_675170.tsv\" \\\n    --output \"sample.library.seshat.annotated.vcf\"\n```\n\n```console\n16:16:34 INFO  SeshatMerge - Starting to zip annotations and VCF variants.\n16:16:34 INFO  SeshatMerge - Successfully annotated variant calls.\n```\n\n## Development and Testing\n\nSee the [contributing guide](./CONTRIBUTING.md) for more information.\n\n## References\n\n- [Soussi, Thierry, et al. “Recommendations for Analyzing and Reporting TP53 Gene Variants in the High-Throughput Sequencing Era.” Human Mutation, vol. 35, no. 6, 2014, pp. 766–778., doi:10.1002/humu.22561](https://doi.org/10.1002/humu.22561)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclintval%2Ftp53","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclintval%2Ftp53","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclintval%2Ftp53/lists"}