{"id":20798254,"url":"https://github.com/mehelmy/princess","last_synced_at":"2025-07-16T03:47:23.119Z","repository":{"id":90784544,"uuid":"179986953","full_name":"MeHelmy/princess","owner":"MeHelmy","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-03T21:29:01.000Z","size":1583,"stargazers_count":80,"open_issues_count":9,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-20T02:44:50.752Z","etag":null,"topics":["long-reads","methylation","phasing","single-nucleotide-variation","structural-variation"],"latest_commit_sha":null,"homepage":null,"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/MeHelmy.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}},"created_at":"2019-04-07T15:41:52.000Z","updated_at":"2025-05-20T15:22:19.000Z","dependencies_parsed_at":"2024-05-06T15:20:06.432Z","dependency_job_id":"434360e6-ea91-46b6-b84d-aa4e1596f895","html_url":"https://github.com/MeHelmy/princess","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/MeHelmy/princess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeHelmy%2Fprincess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeHelmy%2Fprincess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeHelmy%2Fprincess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeHelmy%2Fprincess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MeHelmy","download_url":"https://codeload.github.com/MeHelmy/princess/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeHelmy%2Fprincess/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265479883,"owners_count":23773631,"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":["long-reads","methylation","phasing","single-nucleotide-variation","structural-variation"],"created_at":"2024-11-17T16:44:00.529Z","updated_at":"2025-07-16T03:47:23.084Z","avatar_url":"https://github.com/MeHelmy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Princess\n[![GitHub](https://img.shields.io/github/license/MeHelmy/princess)](https://opensource.org/licenses/MIT) ![GitHub last commit](https://img.shields.io/github/last-commit/MeHelmy/princess)\n---\n## What is new?\n- Clair3 for calling single nucleotide polymorphisms (SNPs) and insertions/deletions (Indels)\n  - Ability to use different models than the default one that comes with Clair3, which can be helpful in cases where there is new kit/training dataset or when working with data other than the human genome.\n- Sniffles2 for detecting structural variants (SVs)\n- Generation of a gVCF file for cohort analysis\n- Generation of an SNF file for cohort structural variant analysis\n- The pipeline has been fully tested on both PBS and Slurm systems with easy configuration\n- The main conda environment has been updated for improved granularity.\n---\n\nPrincess is a fast and scalable framework to detect and report haplotype resolved Single Nucleotide Variants (SNV) and Structural Variations (SVs) at scale. It can leverage your cluster environment to speed up the detection which starts with one or many fasta or fastq files.\nPublication: https://genomebiology.biomedcentral.com/articles/10.1186/s13059-021-02486-w   \n\n\u003c!-- Cite the code: [![DOI](https://zenodo.org/badge/179986953.svg)](https://zenodo.org/badge/latestdoi/179986953) --\u003e\n\n\n![princess](./pictures/leia.jpg)\n\n## Princess\n\n* __Mapping__:   Minimap2 or NGMLR\n* __SNVs__: Clair3 \n* __SVs__: Sniffles2\n* __Phasing SNVs__: WhatsHap\n* __Phasing SVs__: Sniffles2\n* __Extend Phasing__: PRINCESS-subtool\n* __Phased Methylation__: Nanopolish + PRINCESS-subtool\n* __QC Statistics__ for each step\n\n---\n\n## Installation\nPrincess was tested on CentOS release 6.7, Conda version 4.7.12 is installed:\nfor more information about [Installing Conda press here](https://bioconda.github.io/user/install.html#install-conda, \"Install Conda\")\nTo download same Conda version [here](https://repo.continuum.io/miniconda/Miniconda3-4.7.12-Linux-x86_64.sh \"Conda 4.7.12\")*\n\n1. After conda is installed. Snakemake should be installed and yaml\n~~~\nconda install snakemake=5.7.1\nconda install pyyaml\n~~~\n2. Downloading PRINCESS  \n~~~\ngit clone https://github.com/MeHelmy/princess.git\n~~~\n\n---\n\n## Tutorial\n\nTo have an overview about princess write command `princess -h`.\nYou will have the following list of commands that we can use in princess.\n\n~~~\nusage: princess [-h] {all,align,sv,snv,variant,phase,overview} ...\n\nPrincess A framework for long-reads analysis.\n\noptional arguments:\n  -h, --help            show this help message and exit\n\nSub-commands:\n  Valid sub-commands\n\n  {all,align,sv,snv,variant,phase,overview}\n    all                 This command will run the following: Align the reads.\n                        Identify SVs Identify SNVs Phase both SNVs and SVs\n    align               This command will use the input sequence files and\n                        align them against the reference using either Minimap2\n                        or NGMLR use -a to choose aligner otherwise Minimap2\n                        will be used by default.\n    sv                  This command will use bam file to identify SV using\n                        Sniffles.\n    snv                 This command will use bam file to identify SNVs using\n                        Clair3.\n    variant             This command will use bam file to identify SVs and\n                        SNVs.\n    phase               This command will use use reads to identify SNVs by\n                        Clair and Phase them.\n    overview            This command will show what steps will run.\n\nprincess version 0.01. use command -h for info.\n~~~\n\n\nAssume that we want only to run `snv` command, to know more about its option:\n\n`princess snv -h`\n\n\n~~~\nusage: princess snv [-h] [-v] -d Working directory -r {ont,clr,ccs} [-l] [-u]\n                    [-e] [-a {minimap,ngmlr}]\n                    [-s sampleFiles [sampleFiles ...]] -f REF [-j JOBS]\n                    [-g LOG_FILE] [-c CHRS [CHRS ...]] [-t]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         show program's version number and exit\n  -d Working directory, --directory Working directory\n                        Working directory.\n  -r {ont,clr,ccs}, --ReadType {ont,clr,ccs}\n                        Read technology (Note: clr is not supported anymore by clair3)\n  -l, --removeFiles     remove princess source script after running default:\n                        False)\n  -u, --UseConda        Use conda for running default: True)\n  -e, --Cluster         Use cluster while running default: True)\n  -a {minimap,ngmlr}, --Aligner {minimap,ngmlr}\n                        In case if you want to choose specific aligner\n                        otherwise default will be used default: minimap)\n  -s sampleFiles [sampleFiles ...], --sampleFiles sampleFiles [sampleFiles ...]\n                        list of fatsa, fastq, or gz files.\n  -f REF, --ref REF     The reference file will be used to align reads to.\n  -j JOBS, --jobs JOBS  Number of running jobs default: 200 )\n  -g LOG_FILE, --log LOG_FILE\n                        Log file: PrincessLog.txt )\n  -c CHRS [CHRS ...], --chr CHRS [CHRS ...]\n                        Chromosomes list, if not specified we will use all\n                        Chromosomes.\n  -t, --filter          Filter identified SNVs using Princess algorithm\n                        default: True)\n~~~\n\n\n~~~\nprincess all  -d ./princess_all -r ont -s reads.split00.fastq.gz reads.split01.fastq.gz  -f hs37d5_mainchr.fa\n~~~\n\n`-r` defines the reads type.  \n`-s` samples that we would like to analyze.  \n`-f` **full path** to the reference.  \n\n*__Note__*  \nI am assuming that the reference file is indexed, if not please use the following command.  \n`samtools faidx hs37d5_mainchr.fa` as a result you will have `hs37d5_mainchr.fa.fai`.\n\nDone!!\n\n### For methylation calling.\nMethylation calling is a part from the `all` option.\n\n```\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         show program's version number and exit\n  -d Working directory, --directory Working directory\n                        Working directory.\n  -r {ont,clr,ccs}, --ReadType {ont,clr,ccs}\n                        Read technology\n  -l, --removeFiles     remove princess source script after running default: False)\n  -u, --UseConda        Use conda for running default: True)\n  -e, --Cluster         Use cluster while running default: True)\n  -a {minimap,ngmlr}, --Aligner {minimap,ngmlr}\n                        In case if you want to choose specific aligner otherwise default will be used default: minimap)\n  -s sampleFiles [sampleFiles ...], --sampleFiles sampleFiles [sampleFiles ...]\n                        list of fatsa, fastq, or gz files.\n  -f REF, --ref REF     The reference file will be used to align reads to.\n  -j JOBS, --jobs JOBS  Number of running jobs default: 200 )\n  -g LOG_FILE, --log LOG_FILE\n                        Log file: PrincessLog.txt )\n  -c CHRS [CHRS ...], --chr CHRS [CHRS ...]\n                        Chromosomes list, if not specified we will use all Chromosomes.\n  -t, --filter          Filter identified SNVs using Princess algorithm default: True)\n  -m, --methylation     Identify methylation, mutually inclusive with -md default: False)\n  -md Fast5 Directory, --methylationDirectory Fast5 Directory\n                        Fast5 directory will be used to identify methylation mutually inclusive with option -m default: False)\n```\nBy choosing the flag __`--methylation`__, Princess will call the methylation on the input data (ONT data), this option is inclusive with the option __`--methylationDirectory`__ which requires the fasta5 directory.\n\n## Test case\n\nWe uploaded a HiFi compressed data file from the publicly available HG002 data set.\nThe complete data set (High-fidelity 15kb long-read dataset of HG002, Ashkenazim Son.) is available [Here](https://ftp-trace.ncbi.nlm.nih.gov/ReferenceSamples/giab/data/AshkenazimTrio/HG002_NA24385_son/PacBio_CCS_15kb/)\n\nTo download the test data run the following command:\n```\nwget https://bcm.box.com/shared/static/sdml5d7csxprgu3cl5cve0lgv5jnrrlv --output-document  HiFi.fastq.gz\n```\nAfter download is finished you shall have a HiFi fastq file called `HiFi.fastq.gz`, to run the analysis test run the following command:\n```\nFull/Path/To/princess all  --directory $PWD/analysis --ReadType ccs --ref Path/To/Reference/genome.fa --jobs 7 --sampleFiles $PWD/HiFi.fastq.gz  --latency-wait 200 -p\n```\nall:           The command to run full analysis for other options please run `princess -h`  \n---directory:  The out put directory it could be any name, use the full path, in my case the output is  same place.  \n--ReadType:    Read type, the supported read types are clr, ccs, and ont.  \n--ref:         Path to the reference please use samtools faidx with refernce before running Princess.  \n--jobs:        Number of running jobs on cluster.  \n--sampleFiles: Sample fastq file we downloaded, it could be more than one either compressed or not.  \n--latency-wait 200 -p:  These are additional Snakemake option to wait 200 seconds before collecting output.  \n\n\n\n\n\n\n## Output\n\nPrincess will create these directories:\n- align   contains directory [minimap or ngmlr] based on the aligner that was specified.\n- sv      contains the structural variant file sv/minimap/sniffles.vcf\n- snp     contains single nucleotide variant calls per chromosomes\n- phased  contains phased variant\n- stat    contains Statistics\n- meth    contains methylation info (if user choose to run methylation)  \n\n## Collect benchmark Statistics  \n```\ncd benchmark  # There is a directory benchmark contains all the analyses that were done by PRINCESS\nfind \"$PWD\" -type f | grep -v \"myBenchMark.txt\" \u003e myBenchMark.txt\nwhile read -r line; do n=$(echo  $line | awk  -v FS=/ '{print $(NF-1)\"-\"$(NF)}');  awk -v f=$line -v o=$n 'NR!=1 {print o\"\\t\"$(NF)}' $line  ;done \u003c myBenchMark.txt\n```  \n- meth    contains methylation info (if user choose to run methylation) \n\n---\n\n## Converting from PBS to Slurm\n1- Please ensure that you modify the `cluster/cluster_config.yaml` to specify the appropriate long-running node. For example, you can set the long queue system as follows:\n    `long: \u0026long_queue long_queue` \n    Where long_queue is the queue system that can run for a long time. Similarly, you can set the short queue in the following way:\n    `short: \u0026short_queue short_queue`, . Please refer to your cluster system administrator for more details.  \n2- Please, ensure that you changed `cluster/config.yaml` from `cluster-status: \"pbs_status.py\"` to `cluster-status: \"slurm_status.py\"`  \n3- In the `cluster/key_mapping.yaml` file. Please, change `system: \"pbs\"` to `system: \"slurm\"`  \n4- Finally, in the `cluster/cluster_config.yaml` file, I set CPU and memory to each job to suit my cluster.  \nE.g.\n```\nminimap2:\n  queue: *long_queue\n  time: \"72:00:00\"\n  nCPUs: \"12\"\n  mem: 20G\n```\nHere, I am using 12 CPUs, 20G memory, and the job running time is \"72:00:00\" maximum (three days.). You may need to use a different configuration based on the resources availability in your cluster. Please, refer to your system administrator for more details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmehelmy%2Fprincess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmehelmy%2Fprincess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmehelmy%2Fprincess/lists"}