{"id":13756439,"url":"https://github.com/pinellolab/GRAFIMO","last_synced_at":"2025-05-10T03:32:06.722Z","repository":{"id":44572534,"uuid":"218635662","full_name":"pinellolab/GRAFIMO","owner":"pinellolab","description":"GRAph-based Finding of Individual Motif Occurrences","archived":false,"fork":false,"pushed_at":"2022-09-26T20:25:22.000Z","size":28792,"stargazers_count":27,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-11T21:22:06.903Z","etag":null,"topics":["bioinformatics","genome-variation-graphs","genomic-variants","haplotype-aware","motif-scanning"],"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/pinellolab.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":"2019-10-30T22:10:16.000Z","updated_at":"2024-03-27T18:11:17.000Z","dependencies_parsed_at":"2022-09-11T19:21:11.898Z","dependency_job_id":null,"html_url":"https://github.com/pinellolab/GRAFIMO","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinellolab%2FGRAFIMO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinellolab%2FGRAFIMO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinellolab%2FGRAFIMO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinellolab%2FGRAFIMO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinellolab","download_url":"https://codeload.github.com/pinellolab/GRAFIMO/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224911552,"owners_count":17390840,"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":["bioinformatics","genome-variation-graphs","genomic-variants","haplotype-aware","motif-scanning"],"created_at":"2024-08-03T11:00:44.090Z","updated_at":"2025-05-10T03:32:06.712Z","avatar_url":"https://github.com/pinellolab.png","language":"Python","funding_links":[],"categories":["A list of software capable of analyzing **eukaryotic** genomes for pangenomics"],"sub_categories":[],"readme":"[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/grafimo/README.html)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/pinellolab/grafimo)\n![Conda](https://img.shields.io/conda/dn/bioconda/grafimo)\n![license](https://img.shields.io/badge/license-MIT-lightgrey)\n\n\n# GRAFIMO\nGRAph-based Finding of Individual Motif Occurrences\n\n![image](./docs/wf.jpg)\n\nRegulatory proteins, such as Transcription Factors (TFs), are key genomic elements which promote or reduce the expression of genes by binding short, evolutionary conserved DNA sequences, often referred to as motifs. Mutations occurring in DNA motifs have been shown to have deleterious effects on the transcriptional landscape of the cell (Li \u0026 Ovcharenko, 2015; Guo et al., 2018). The recent introduction of Genome Variation Graphs (VG) (Garrison et al., 2018) allowed to represent in a single and efficient data-structure the genomic variation present within a population of individuals.\n\nGRAFIMO (GRAph-based Finding of Individual Motif Occurrences) is a command-line tool that extends the traditional Position Weight Matrix (PWM) scanning procedure to VGs. GRAFIMO can search the occurrences of a given PWM in many genomes in a single run, accounting for the effects that SNPs, indels and potentially any structural variation (handled by VG) have on found potential motif occurrences. As result, GRAFIMO produces a report containing the statistically significant motif candidates found, reporting their frequency within the haplotypes embedded in the scanned VG and if they contain genomic variants or belong to the reference genome sequence.\n\n## Installation\n\n\n### Install dependencies\nGRAFIMO depends on a number of external tools and Python packages. Before installing GRAFIMO you should install\n- VG, v1.27.1 or later ([https://github.com/vgteam/vg](https://github.com/vgteam/vg))\n- Tabix ([https://github.com/samtools/htslib](https://github.com/samtools/htslib))\n- Graphviz ([https://www.graphviz.org/](https://www.graphviz.org/))\n\n**Be sure that all are reachable in Unix PATH**.\n\nNote that is suggested to use samtools Tabix and not the one coming with VG. If the user is not sure about which tabix is running, he/she can type ```which tabix```, to retrieve which is the currently used Tabix.\n\nGRAFIMO is written in both Python3 and Cython. Thus, the user will need Cython to be installed to correctly build GRAFIMO. Cython can be obtained via pip\n```\npip3 install Cython\n```\n\nTo build GRAFIMO are used ```setuptools``` and ```wheel```. The user should make sure he/she has the latest version of both ```setuptools``` and ```wheel```\n```\npython3 -m pip install --user --upgrade setuptools wheel\n```\n\nGRAFIMO depends on a number of Python packages. If the dependencies are not satisfied, by building GRAFIMO from source or via pip they should be automatically solved.\n\nTo install all the required packages:\n```\npip3 install pandas\npip3 install numpy\npip3 install statsmodels\npip3 install sphinx\npip3 install numba\npip3 install colorama\n```\n\n### Build\n\nGRAFIMO can be built and installed via pip, from source code or via Bioconda. Note that the latter option is available only for Linux users.\n\nFor further details on how to install GRAFIMO visit our [Wiki](https://github.com/pinellolab/GRAFIMO/wiki).\n\n**Build and install via pip**\n\nTo build and install GRAFIMO via pip\n```\npip3 install grafimo\n```\n\nTo test if GRAFIMO have been correctly installed\n```\ngrafimo -h\n```\n\nIf the help is correctly printed, then GRAFIMO have been installed and can be called from any location.\n\n**Build and install from source code**\n\nTo build and install GRAFIMO from source code\n```\ngit clone https://github.com/pinellolab/GRAFIMO.git \ncd GRAFIMO\npython3 setup.py install --user\n```\n\nTo quickly test GRAFIMO installation \n```\ngrafimo -h\n```\n\nIf the help is correctly printed, then GRAFIMO have been installed and can be called from any location.\n\nIt is also possible to test all the main functionalities of GRAFIMO using ```pytest``` ([https://docs.pytest.org/en/stable/](https://docs.pytest.org/en/stable/)).\n\nTo install ```pytest```\n```\npip3 install pytest\n```\n\nOnce ```pytest``` have been installed, enter the ```tests``` directory and launch ```pytest```\n```\ncd tests\npytest\n```\n\nIf no test fails, then all GRAFIMO functionalities work properly.\n\n**Build and install via Bioconda (Linux users only)**\n\nTo install GRAFIMO via Bioconda the user should first have the ```conda``` package installed. If the user have an Anaconda Python installation, ```conda``` is already available, otherwise it can be installed with [Miniconda](https://conda.io/en/latest/miniconda.html) package. For further details ([https://bioconda.github.io/user/install.html](https://bioconda.github.io/user/install.html)).\n\nOnce ```conda``` is available, to install GRAFIMO\n```\nconda install grafimo\n```\n\nTo update GRAFIMO\n```\nconda update grafimo\n```\n\n### Use GRAFIMO via Docker (All Operating Systems including MacOS and Windows)\n\nFor MacOS and Windows users is suggested to run GRAFIMO via [Docker](https://www.docker.com/get-started). \n\nThe user can both pull an already built GRAFIMO docker image or build it from scratch. The user has also to ensure that Docker is currently installed and there are no too strict limits on the number of CPUs and amount of memory that Docker can use ([https://docs.docker.com/config/containers/resource_constraints/](https://docs.docker.com/config/containers/resource_constraints/) for further details).  \n\nTo pull the pre-built Docker image:\n```\ndocker pull pinellolab/grafimo\n```\nTo test if the image is correctly running, type:\n```\ndocker run -i pinellolab/grafimo grafimo -h\n```\nIf the help is correctly displayed, then the image has been correctly pulled.\n\nTo build GRAFIMO Docker image from scratch, the user should clone or download GRAFIMO's github repository:\n```\ngit clone https://github.com/pinellolab/GRAFIMO.git\ncd GRAFIMO\n```\nand build the image:\n```\ndocker build -t grafimo .\n```\nTo test if the image has been correctly built, type:\n```\ndocker run -i grafimo grafimo -h\n```\nIf the help is correctly displayed, then the image has been correctly built.\n\n## Usage\n\nFor hands-on tutorials on how to use GRAFIMO check out our [tutorials](https://github.com/pinellolab/GRAFIMO/tree/master/tutorials). \n\nFor further details on GRAFIMO usage refer to our [Wiki](https://github.com/pinellolab/GRAFIMO/wiki).\n\n### Searching potential motif occurrences with GRAFIMO\n\n#### Input\n\nGRAFIMO requires three mandatory arguments:\n\n- path to a directory containing the chromosomes VGs (XG and GBWT indexes) or path to the whole genome variation graph (XG and GBWT indexes). See [VG's wiki](https://github.com/vgteam/vg/wiki) for further details on XG and GBWT indexes.\n\n- path to PWM motif file in MEME or JASPAR format\n\n- BED file containing a set of genomic regions where GRAFIMO will search the motif occurrences\n\n#### Searching motif\n\nThe main functionality of GRAFIMO is to perform a haplotype and variant-aware search of potential DNA motif occurrences in genome variation graph. \n\nHere we assume that the genome variation graph (VG) has been built constructing a VG for each chromosome. If working with a single whole genome variation graph just substitute the argument ```-d``` with ```-g``` followed by the path to the whole genome VG. In the next section will be presented how to build a VG with GRAFIMO.\n\nNote that in both cases **the XG and GBWT indexes of the VG  must be stored in the same location**.\n\nFor further details refer to our [Wiki](https://github.com/pinellolab/GRAFIMO/wiki).\n\nIf you are working in the ```tutorials/findmotif_tutorial``` directory, to run GRAFIMO\n```\ngrafimo findmotif -d data/mygenome/ -m  data/example.meme -b data/regions.bed\n```\n\nBy default GRAFIMO will create a directory called `grafimo_out_PID_MOTIFID`, containing the results. For further details on result files see **Results description** section.\n\n\n#### Advanced options\n\n***Using background distributions***\n\nFor each potential motif occurrence GRAFIMO computes a log-likelihood score, a *P*-value and a *q*-value. Such measures are weighted by a background probability distribution. By default, GRAFIMO assumes a uniform background distribution for nucleotides. The user can specify a different background distribution in a text file and give it to GRAFIMO using `-k` option. An example of background file is\n```\nA\t0.2951\nC\t0.2047\nT\t0.2955\nG\t0.2048\n```\n\nFor an example of background files accepted by GRAFIMO, take a look at [`bg_nt`](https://github.com/pinellolab/GRAFIMO/blob/master/tutorials/findmotif_tutorial/data/bg_nt) in `tutorials/findmotif_tutorial/data` directory.\n\nIf you are working in ```tutorials/findmotif_tutorial``` directory, to run GRAFIMO with a background distribution\n```\ngrafimo findmotif -d data/mygenome/ -m data/example.meme -b data/regions.bed -k data/bg_nt \n```\n\n***Setting thresholds on motif occurrences statistical significance***\n\nBy default GRAFIMO applies a threshold of 1e-4 on the *P*-value of each retrieved potential motif occurrence. So, will be reported the motif candidates with an associated *P*-value smaller than 1e-4. The threshold can be changed by using the `-t` option. For example, let us set a threshold of 0.05 on the *P*-values.\n\nIf you are working in ```tutorials/findmotif_tutorial``` directory, to run GRAFIMO applying a different threshold on *P*-values \n```\ngrafimo findmotif -d data/mygenome -m data/example.meme -b data/regions.bed -t 0.05\n```\n\nGRAFIMO, besides *P*-values, computes *q*-values for the motif occurrences candidates. The user can apply a threshold on *q*-values, rather than on *P*-values, by using the `--qvalueT` option. `--qvalueT` option can be used in combination with `-t` to define a threshold value different from 1e-4. Let us apply a threshold of 1e-4 on *q*-values.\n\nIf you are working in ```tutorials/findmotif_tutorial``` directory, to run GRAFIMO applying a threshold on *q*-values\n```\ngrafimo findmotif -d data/mygenome -m data/example.meme -b data/regions.bed --qvalueT -t 1e-4\n```\n\n#### For more options\n\nFor more options refer to our [Wiki](https://github.com/pinellolab/GRAFIMO/wiki) or type\n```\ngrafimo -h\n```\n\n#### Results description\n\nGRAFIMO results are reported in three files (stored in output directory):\n- tab-delimited report (TSV report)\n- HTML report\n- GFF3 report\n\nThe TSV report contains all the statistically significant potential motif occurrence found by GRAFIMO (according to the applied threshold). Each retrieved motif occurrence has a log-likelihood score, a *P*-value, a *q*-value, its DNA sequence, a flag value stating if a sequence is part of the reference or has been found in the haplotypes and the number of haplotype sequences where the motif candidate sequence occurs. An example of TSV report is the following\n```\n\tmotif_id\tmotif_alt_id\tsequence_name\tstart\tstop\tstrand\tscore\tp-value\tq-value\tmatched_sequence\thaplotype_frequency\treference\n1\tMA0139.1\tCTCF\tchr22:43481590-43481860\t43481733\t43481714\t-\t21.26229508196724\t4.403657357543095e-08\t0.004175283686980911\tAAGCCAGCAGGGGGCACAG\t5096\tref\n2\tMA0139.1\tCTCF\tchr22:19038291-19038561\t19038422\t19038441\t+\t19.245901639344254\t1.9442011615088443e-07\t0.005962538354344465\tTGGCCAGCAAGGGGCACTG\t4\tnon.ref\n3\tMA0139.1\tCTCF\tchr22:19038291-19038561\t19038422\t19038441\t+\t19.114754098360663\t2.1268826066771178e-07\t0.005962538354344465\tCGGCCAGCAAGGGGCACTG\t5092\tref\n4\tMA0139.1\tCTCF\tchr22:40856678-40856948\t40856891\t40856910\t+\t18.295081967213093\t3.6764803446618004e-07\t0.005962538354344465\tTCCCCTCCAGGGGGCGACG\t5096\tref\n5\tMA0139.1\tCTCF\tchr22:11285607-11285877\t11285804\t11285785\t-\t18.213114754098342\t3.8774723287177635e-07\t0.005962538354344465\tATACCGCCAGGTGGCAGCA\t5096\tref\n6\tMA0139.1\tCTCF\tchr22:22125904-22126174\t22126044\t22126063\t+\t18.13114754098359\t4.088625891963074e-07\t0.005962538354344465\tCAGCCTGCAGATGGCACAG\t5096\tref\n7\tMA0139.1\tCTCF\tchr22:20146797-20147067\t20147010\t20147029\t+\t17.688524590163922\t5.4295945317287e-07\t0.005962538354344465\tCGGCCCGCAGGGGGCGGAT\t5092\tref\n8\tMA0139.1\tCTCF\tchr22:34842682-34842952\t34842827\t34842846\t+\t17.672131147540995\t5.486120126825257e-07\t0.005962538354344465\tGAGCCAGTAGGGGACAGCG\t146\tnon.ref\n9\tMA0139.1\tCTCF\tchr22:42532903-42533173\t42533062\t42533081\t+\t17.622950819672155\t5.659801842459994e-07\t0.005962538354344465\tGGGCCACCAGAGGGCTCCT\t5096\tref\n10\tMA0139.1\tCTCF\tchr22:34842682-34842952\t34842827\t34842846\t+\t17.44262295081967\t6.331282484526275e-07\t0.006002942174878742\tGAGCCAGTAGGGGACAGTG\t4950    ref\n```\nThis report can be easily processed for a downstream analysis.\n\nThe HTML report has the same content of the TSV, but it can be loaded and viewed on the most commonly used web browsers.\n\nThe GFF3 report can be loaded on the UCSC Genome Browser as a custom track. For example, this allows a fast linking between the genomic variants used to build the VG and those present in annotated databases like dbSNP or ClinVar.  \n\n### Building genome variation graphs (VGs) with GRAFIMO\n\nGRAFIMO allows also to build a genome variation graph from user data. To construct the VG are required \n- a genome reference (in FASTA format)\n- VCF file containing the genomic variants to enrich the reference sequence.\n\nGRAFIMO builds the genome variation graph by constructing a VG for each chromosome. This allows a faster and more efficient motif search on the genome variation graph. \n\nNote that this genome variation graph building approach is suggested by VG developers.\n\nGRAFIMO will construct the XG and the GBWT index for each chromosome. The XG and GBWT indexes allow a faster and haplotype-aware motif search on VG. \n\nBefore attempting to build the VG it is very important to make sure that the chromosome names in the VCF and in the reference FASTA sequence headers match. For example, if in the VCF the chromosome 1 is named `1`, the header of chromosome 1 sequence on the reference FASTA file should be `\u003e1`, and not something like `\u003echr1`.\n\nIf you are in ```tutorials/buildvg_tutorial``` directory, to build a VG with GRAFIMO\n```\ngrafimo buildvg -l data/xy.fa -v data/xy2.vcf.gz    \n```\n\nFor further details refer to our [Wiki](https://github.com/pinellolab/GRAFIMO/wiki).\n\n## References \n\nLi, Shan, and Ivan Ovcharenko. \"Human enhancers are fragile and prone to deactivating mutations.\" *Molecular biology and evolution* 32.8 (2015): 2161-2180.\n\nGuo, Yu Amanda, et al. \"Mutation hotspots at CTCF binding sites coupled to chromosomal instability in gastrointestinal cancers.\" *Nature communications* 9.1 (2018): 1-14.\n\nGarrison, Erik, et al. \"Variation graph toolkit improves read mapping by representing genetic variation in the reference.\" *Nature biotechnology* 36.9 (2018): 875-879.\n\n## How to reproduce the experiments\n\nAll the scripts and IPython notebooks required to reproduce the experiments and the analysis presented in GRAFIMO's paper are available [here](https://github.com/pinellolab/GRAFIMO/tree/master/docs/paper_results).\n\n## Citation\n\nIf you use GRAFIMO in your research, please cite us:\n\nTognon M, Bonnici V, Garrison E, Giugno R, Pinello L (2021) GRAFIMO: Variant and haplotype aware motif scanning on pangenome graphs. PLOS Computational Biology 17(9): e1009444. [https://doi.org/10.1371/journal.pcbi.1009444](https://doi.org/10.1371/journal.pcbi.1009444)\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinellolab%2FGRAFIMO","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinellolab%2FGRAFIMO","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinellolab%2FGRAFIMO/lists"}