{"id":31805728,"url":"https://github.com/theislab/greatpy","last_synced_at":"2025-10-11T02:57:50.090Z","repository":{"id":56862304,"uuid":"497883152","full_name":"theislab/greatpy","owner":"theislab","description":"GREAT algorithm in Python","archived":false,"fork":false,"pushed_at":"2022-10-24T08:41:46.000Z","size":34015,"stargazers_count":14,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-23T01:51:36.555Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/theislab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-05-30T09:54:17.000Z","updated_at":"2025-02-12T10:12:45.000Z","dependencies_parsed_at":"2023-01-20T10:16:32.860Z","dependency_job_id":null,"html_url":"https://github.com/theislab/greatpy","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/theislab/greatpy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theislab%2Fgreatpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theislab%2Fgreatpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theislab%2Fgreatpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theislab%2Fgreatpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theislab","download_url":"https://codeload.github.com/theislab/greatpy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theislab%2Fgreatpy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005953,"owners_count":26084009,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"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":[],"created_at":"2025-10-11T02:57:47.662Z","updated_at":"2025-10-11T02:57:50.083Z","avatar_url":"https://github.com/theislab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# greatpy\n\n[![Tests][badge-tests]][link-tests]\n[![Documentation][badge-docs]][link-docs]\n\n[badge-tests]: https://img.shields.io/github/workflow/status/ilibarra/greatpy/Test/main\n[link-tests]: https://github.com/theislab/greatpy/actions/workflows/test.yml\n[badge-docs]: https://img.shields.io/readthedocs/greatpy\n\nImplementation of GREAT in Python\n\n## Installation\n\nYou require Python 3.8 or newer installed on your system. In case you do not have\nPython installed, we recommend installing `Miniconda \u003chttps://docs.conda.io/en/latest/miniconda.html\u003e`\\_.\n\nOptions to install `greatpy`:\n\n1. Install the latest release of `greatpy` from `PyPI \u003chttps://pypi.org/project/greatpy/\u003e`:\n\n```bash\n pip install greatpy\n```\n\n2. Install the latest development version:\n\n```bash\n pip install git+https://github.com/theislab/greatpy.git@main\n```\n\n## Notebooks\n\n| Information                               | link                  |\n| ----------------------------------------- | --------------------- |\n| Create regulatory domains file (regdom)   | [notebook][notebook1] |\n| Enrichment test (binomial/hypergeometric) | [notebook][notebook2] |\n| Plotting of results                       | [notebook][notebook3] |\n| Comparisons with GREAT                    | [notebook][notebook4] |\n\n## Getting started\n\nPlease refer to\n\n-   [Documentation][link-docs].\n-   [API documentation][link-api].\n\n### What is greatpy:\n\ngreatpy is a bioinformatics method that associates custom genomic regions to Gene Ontology (GO) terms by weighting genomic neighborhoods. It is based on and inspired by and inspired by [GREAT][great_article] (Genomic Regions Enrichment of Annotations Tool).\n\n[GREAT figure][great_figure] issue from [GREAT article][great_article]\n\n### Usage:\n\n#### \u003cins\u003e1. Create regulatory domain from tss\u003c/ins\u003e\n\n-   Translate tab-separated files (`.tsv` or `.bed` format) containing the following information:\n    1.  Transcription start site annotations:`chromosome_number \\t position \\t strand \\t gene_name`.\n    2.  Chromosome sizes file should have the following columns :`chromosome_number \\t chromosome_size`.\n\nSee [data](https://github.com/theislab/greatpy/tree/main/data/human/hg38) for input files\n\n```python\nregdom = greatpy.tl.create_regdom(\n    tss_file=Input_TSS_path,  # eg : \"../data/human/hg38/tss.bed\"\n    chr_sizes_file=Input_chromosome_size_path,  # eg : \"../data/human/hg38/chr_size.bed\"\n    association_rule=\"Basalplusextention\",\n    out_path=path_save_output,\n)\n```\n\nAllowed [association rules][association_rules] are:\n\n-   `Basalplusextention`\n-   `OneCloset`\n-   `TwoCloset`\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./sketch/association_rule.jpg?raw=true\" style=\"width:75%\"\u003e\n\u003c/p\u003e\n\n#### \u003cins\u003e2. Get enrichment of GO term in the tests genomics regions\u003c/ins\u003e\n\n-   This step calculates the significance of a custom set of genomic annotations through peak-gene mapping, using distal cis-regulatory regions of the genome.\n-   Input files :\n-   test file should have the following columns :`chr \\t chr_start \\t chr_end`.\n-   regulatory domain file should have the following columns :`chr \\t chr_start \\t chr_end \\t name \\t tss strand`\n-   chromosome size file should have the following columns :`chromosome_number \\t chromosome_size`.\n-   annotation file should have the following columns :`ensembl \\t id \\t name \\t ontology.group \\t gene.name \\t symbol`\n\nSee [test cases](https://github.com/theislab/greatpy/tree/main/data/tests/test_data) for genomic input files.\n\n```python\nres = greatpy.tl.enrichment(\n    test_file=Input_path_or_df,  # eg : \"../data/tests/test_data/input/10_MAX.bed\"\n    regdom_file=regdom_path_or_df,  # eg : \"../data/human/hg38/regdom.bed\"\n    chr_size_file=chromosome_size_path_or_df,  # eg : \"../data/human/hg38/chr_size.bed\"\n    annotation_file=annotation_path_or_df,  # eg : \"../data/human/ontologies.csv\"\n)\n```\n\nAllowed tests for this function such as :\n\n-   `binom` (default True): it calculates the binomial p-value.\n-   `hypergeom` (default True): it calculates the hypergeometric p-value.\n\nAdditionally, it is also possible to apply a Bonferroni and/or FDR correction to the found p-values:\n\n```python\nres = great.tl.set_fdr(res, alpha=0.05)\nres = great.tl.set_bonferroni(res, alpha=0.05)\n```\n\n#### \u003cins\u003e3. Plot\u003c/ins\u003e\n\n##### 1 Distribution of custom genomic annotations in regulatory domains\n\n-   Number of genetic associations per genomic region.\n-   Distance to the associated gene TSS for each genomic region studied.\n-   Absolute distance to the associated gene TSS for each genomic region studied.\n\n```python\nfig, ax = plt.subplots(1, 3, figsize=(30, 8))\ngreatpy.pl.graph_nb_asso_per_peaks(\n    Input_path_or_df,  # eg : \"../data/tests/test_data/input/10_MAX.bed\"\n    regdom_path_or_df,  # eg : \"../data/human/hg38/regdom.bed\"\n    ax[0],\n)\ngreatpy.pl.graph_dist_tss(\n    Input_path_or_df,  # eg : \"../data/tests/test_data/input/10_MAX.bed\"\n    regdom_path_or_df,  # eg : \"../data/human/hg38/regdom.bed\"\n    ax[0],\n)\ngreatpy.pl.graph_absolute_dist_tss(\n    Input_path_or_df,  # eg : \"../data/tests/test_data/input/10_MAX.bed\"\n    regdom_path_or_df,  # eg : \"../data/human/hg38/regdom.bed\"\n    ax[0],\n)\nplt.show()\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./sketch/plot1.png?raw=true\"\u003e\n\u003c/p\u003e\n\n##### 2 Enrichments by GO terms (dotplot) - one input\n\n```python\nplot = enrichment_df.rename(columns={\"binom_p_value\": \"p_value\", \"go_term\": \"name\"})\nplt.figure(figsize=(10, 10))\ngreat.pl.plot_enrich(plot)\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./sketch/dotplot.png?raw=true\" style=\"width:75%\"\u003e\n\u003c/p\u003e\n\n##### 3 Enrichments by GO terms (dotplot) - multiple inputs\n\n```python\ntest = [\"name_bindome_biosample_1\", \"name_bindome_biosample_2\", \"...\"]\ntmp_df = great.tl.enrichment_multiple(\n    tests=test,\n    regdom_file=\"../data/human/hg38/regulatory_domain.bed\",\n    chr_size_file=\"../data/human/hg38/chr_size.bed\",\n    annotation_file=\"../data/human/ontologies.csv\",\n    binom=True,\n    hypergeom=True,\n)\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./sketch/multidot.png?raw=true\" alt=\"dotplot of multi sample\" width=\"300\" height=\"400\"\u003e\n\u003c/p\u003e\n\n## Notes\n\nBoth binomial and hypergeometric tests may be susceptible to biases of which one must be aware to analyze the results critically. The binomial test reduces the hypergeometric bias by taking into account exactly the size of the regulatory domains of the genes, whereas the hypergeometric test compensates for the bias of the binomial test by counting each gene only once.\nThe two types of tests are complementary and are recommended to be analyzed together.\n\n## Release notes\n\nSee the [changelog][changelog].\n\n## Contact\n\nFor questions and help requests, you can reach out in the [scverse discourse][scverse-discourse].\nIf you found a bug, please use the [issue tracker][issue-tracker].\n\n## Citation\n\nIf greatpy is useful for your research, please consider to cite as:\n\n```bibtex\n@software{greatpy,\nauthor = {Ibarra, Mauger-Birocheau},\ndoi = {},\nmonth = {},\ntitle = {{greatpy}},\nurl = {https://github.com/theislab/greatpy},\nyear = {2022}\n}\n```\n\n## References\n\n```bibtex\n@article{GREAT,\nauthor   = {McLean, C.\n            and Bristor, D.\n            and Hiller, M. et al.},\ntitle    = {GREAT improves functional interpretation of cis-regulatory regions},\njournal  = {Nat Biotechnol},\nyear     = {2010},\nmonth    = {May},\nday      = {02},\nvolume   = {28},\nnumber   = {495},\npages    = {501},\ndoi      = {10.1038/nbt.1630},\nurl      = {https://doi.org/10.1038/nbt.1630}\n}\n```\n\n```bibtex\n@Manual{rGREAT,\ntitle = {rGREAT: GREAT Analysis - Functional Enrichment on Genomic Regions},\nauthor = {Zuguang Gu},\nyear = {2022},\nnote = {https://github.com/jokergoo/rGREAT, http://great.stanford.edu/public/html/},\n}\n```\n\n[scverse-discourse]: https://discourse.scverse.org/\n[issue-tracker]: https://github.com/ilibarra/greatpy/issues\n[changelog]: https://greatpy.readthedocs.io/latest/changelog.html\n[link-docs]: https://greatpy.readthedocs.io\n[link-api]: https://greatpy.readthedocs.io/latest/api.html\n[great_article]: https://www.nature.com/articles/nbt.1630\n[great_figure]: https://www.nature.com/articles/nbt.1630/figures/1\n[association_rules]: https://great-help.atlassian.net/wiki/spaces/GREAT/pages/655443/Association+Rules\n[notebook1]: https://github.com/theislab/greatpy/blob/main/notebooks/01_create_regdom.ipynb\n[notebook2]: https://github.com/theislab/greatpy/blob/main/notebooks/02_binom_vs_hypergeom.ipynb\n[notebook3]: https://github.com/theislab/greatpy/blob/main/notebooks/07_plot.ipynb\n[notebook4]: https://greatpy.readthedocs.io/en/latest/notebooks/03_great_vs_greatpy.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheislab%2Fgreatpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheislab%2Fgreatpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheislab%2Fgreatpy/lists"}