{"id":27252791,"url":"https://github.com/tomalf2/recombinhunt-cov","last_synced_at":"2025-04-11T01:24:38.081Z","repository":{"id":219300139,"uuid":"663401812","full_name":"tomalf2/recombinhunt-cov","owner":"tomalf2","description":"RecombinHunt (alias for the software contained in this repository) is a Python library implementing a data-driven novel method for identifying contributing lineages and breakpoints in recombinant viral sequences.","archived":false,"fork":false,"pushed_at":"2024-08-20T15:38:28.000Z","size":12586,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-20T17:53:48.477Z","etag":null,"topics":["big-data","bioinformatics","data-science","recombination","research","viral-genomics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomalf2.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}},"created_at":"2023-07-07T07:59:55.000Z","updated_at":"2024-08-20T15:34:01.000Z","dependencies_parsed_at":"2024-08-20T17:38:23.518Z","dependency_job_id":"466f264f-7b20-4537-bd1c-a17443d401ae","html_url":"https://github.com/tomalf2/recombinhunt-cov","commit_stats":null,"previous_names":["tomalf2/recombinhunt-cov"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomalf2%2Frecombinhunt-cov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomalf2%2Frecombinhunt-cov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomalf2%2Frecombinhunt-cov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomalf2%2Frecombinhunt-cov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomalf2","download_url":"https://codeload.github.com/tomalf2/recombinhunt-cov/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248323666,"owners_count":21084555,"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":["big-data","bioinformatics","data-science","recombination","research","viral-genomics"],"created_at":"2025-04-11T01:24:37.511Z","updated_at":"2025-04-11T01:24:38.062Z","avatar_url":"https://github.com/tomalf2.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RecombinHunt-CoV v7.0.0\n\nThis repository is an updated software version of the material and source code referenced and documented in the following manuscript:\n\n\u003e [Data-driven recombination detection in viral genomes](https://doi.org/10.1038/s41467-024-47464-5),\n\u003e \n\u003e Tommaso Alfonsi, Anna Bernasconi, Matteo Chiara, Stefano Ceri\n\u003e \n\u003e Nature Communications 15, 3313 (2024). https://doi.org/10.1038/s41467-024-47464-5\n\n\u003e The original version referenced in the manuscript is the Version 4 (recombinhunt-cov-3.3.3-v4.zip), released March 13th, 2024 and available on the same Zenodo repository at the following [link](https://doi.org/10.5281/zenodo.10812636). \n\nRecombinHunt (alias for the software contained in this repository) is a Python library implementing a data-driven novel method for identifying contributing lineages and breakpoints in recombinant viral sequences.\n\n# Installation\n\nInstallation requires Python 3.10.12 and PIP. The software is independent of the operating system.\nIt is suggested to use a dedicated python environment (e.g., conda, miniconda or venv). Below, it is described how to create one with conda.\n\n#### System requirements\n\n\n\nHere we describe how to create a conda environment suitable for the installation of RecombinHunt. If you already know how to create one or want to use a different virtual environment, you can safely skip this subsection.\n\n1. Follow the instructions at https://docs.conda.io/en/latest/miniconda.html# to download and install the latest version of miniconda.\n2. Create and activate a dedicated conda environment with Python 3.10.12 and PIP\n    ```bash\n   $ conda create -n rh_env python=3.10.12 pip\n   $ conda activate rh_env\n    ```\n\nOnce the prerequisites are satisfied, move into the RecombinHunt-CoV directory and install the package with:  \n\n```bash\n$ pip install recombinhunt-7.0.0-py3-none-any.whl\n```\n\nThe installation procedure will take ~ 1 minute (depending on internet connection speed) and install the following packages:\n```\npython 3.10\nnumpy 1.26.0\npandas 2.1.1\nplotly 5.17.0\ntqdm 4.66.1\ninflect 7.0.0\ntabulate 0.9.0\nkaleido 0.2.1\njupyter 1.0.0\nfastjsonschema 2.20.0\npyarrow 17.0.0\n```\n\n\n \n# Usage\n\nThis package already provides the context information (*environment*) that are needed to evaluate the sequences. (The given *environment* is compressed to save storage space; please unzip it before proceeding). \n\nYou can load any suitable environment as:\n```python\nfrom recombinhunt.core.environment import Environment\nenv = Environment(\"environments/env_nextstrain_2023_03_30\") # \u003c- path to the unzipped environment folder\n```\n\nAt the core of the package is the *Experiment* class, which analyses a single sequence and detects if the input is a recombination, the contributing \nlineages and the breakpoint position. \nTo run an Experiment, you need to provide the *Environment* and a target sequence:\n\n```python\nfrom recombinhunt.core.method import Experiment\n\nexperiment = Experiment(environment=env)\nexperiment.set_target(example_seq)  # \u003c- your target sequence\nresult = experiment.run()\n```\n\n### Output\nResults can be displayed by simply calling ```print(result) ```. An example output looks like this:\n```json\ntarget length : 69 \ndesignated candidates :  AY.4 + BA.1.15.3 + AY.4  \nregion details :   1 \n                    pos_start_in_t : 1 \n                    pos_end_in_t : 25 \n                    designated :  AY.4\n                  2 \n                    pos_start_in_t : 26 \n                    pos_end_in_t : 54 \n                    designated :  BA.1.15.3\n                  3 \n                    pos_start_in_t : 55 \n                    pos_end_in_t : 69 \n                    designated :  AY.4\nAIK :  AY.4 : 350.2372865177939 \n       BA.1.15.3 : 1452.8035425553069\n       AY.4 + BA.1.15.3 + AY.4 : -412.89739429828103  \np_values :  AY.4 + BA.1.15.3 + AY.4 vs AY.4 :  1.93e-166  \n            AY.4 + BA.1.15.3 + AY.4 vs BA.1.15.3 :  0.00e+00\n```\n\nLikelihood ratio can be visualized with:\n```python\nfrom recombinhunt.core.graphics import *\n\nplot_likelihood(result.genome_view, xaxis=\"changes\")\n```\n\n![alt text](next_XD_plot.png \"Plot of likelihood ratio for case XD\")\n\n### Customize the Experiment's parameters\nThe default behavior of RecombinHunt can be modified by overriding the parameters in the Experiment constructor method: \n```python\nExperiment(\n  ...\n  min_searchable_region_length=3,\n  min_candidate_region_length=3,\n  min_l2_enclosed_region_length=2,\n  alt_candidate_p_value_difference=1e-05,\n  alt_candidate_max_pos_distance_t=1)\n```\n\nDefault values for such parameters are stored in `recombinhunt.core.method.DefaultParams`.\n\n### Ignore specific candidate variants\nThe knowledge of specific variants/lineages can be ignored, if necessary,  by altering the Environment like so:\n\n```python\n# explicitly name the candidates to ignore \nignored_candidates = ['XBB.1', 'XBB.2']\n# or filter the available candidates\nall_candidates = base_environment.included_lineages()\nignored_candidates = [l for l in all_candidates if not l.startswith('XBB.')]\n\n# clone an existing environment and remove those candidates (quicker method)\ncustom_environment = base_environment.copy_with_exclusions(ignored_candidates)\n# or create an environment without those canididates \ncustom_environment = Environment(\"environments/env_nextstrain_2023_03_30\", ignored_candidates)\n\n# run an experiment...\n```\n\nThis possibility is helpful if the analysed target sequence is recognised as a descendant of a recombinant variant (e.g., XBB.1), while the desired output should report, instead, the recombinant parental candidates (i.e., BJ.1 + BM.1.1.1)\n\n## Demo\n\nIn the ```demo/``` directory, you find the Jupyter Notebook ```recombinant_cases_nextstrain.ipynb```. This \nnotebook computes the recombinant cases in Nextstrain dataset using the consensus of all the sequence of \ngood quality found for each recombinant case. \n\n#### Demo input\nThe original nucleotide sequences are\nstored in ```demo/demo_input_nextstrain``` - for example, the sequences of recombinant case XD are stored in \n```demo/demo_input_nextstrain/sampels_XD.csv```. For each case, the consensus sequence is computed at runtime.\n\n#### Demo output\nThe notebook produces two files stored in ```demo/demo_input_nextstrain```:\n- *summary.md* is a markdown file organising the output of RecombinHunt in a tabular form (one row for each case) and \ncomparing the output against the ground truth when available.\n- *detail.html* is an HTML file that can be viewed in a browser (internet connection is required to load the \nplotting library). This file contains a more detailed output of RecombinHunt; it includes the plot of the likelihood \nratio for the candidate lineages contributing to a recombination, and the consensus sequence for each case.\n\n#### Expected run time\nThe demo runs in ~ 1 minute. \n\n#### Instructions\nThe demo is a Juputer notebook and requires a Jupyter server to run.\nThe RecombinHunt package will automatically install Jupyter among its dependencies. To start a jupyter server locally, \nopen a terminal, move inside this README is located and run:\n```bash\n$ jupyter notebook\n```\nIn case the browser doesn't open automatically, you can click on the link printed in the terminal (the URL \nwill be similar to http://localhost:8888/?token=5f38de823...). Once the browser starts, navigate to the demo directory\nand execute every cell of the notebook.\n\n## Data\n\nThis package already contain some data in order to ease the testing of the software.\nIncluded data files are: \n-  ```demo/demo_input_nextstrain```: nucleotide sequences of recombinant cases downloaded from Nextstrain. Only the \nsequences satisfying our quality filters were retained.\n- ```environments/env_nextstrain_2023_03_30```: information about the probability of nucleotide changes globally and \nfor each lineage.\n- ```demo/validation_data/alias_key.json```: File of recombinant definitions provided from PANGO GitHub repository.\n\n\n## Source code\n\nThe source code is located in the ```src/``` directory.\n\n## Acknowledgements\n\nThis project is run by \n- Tommaso Alfonsi - PhD candidate - Politecnico di Milano - tommaso.alfonsi@polimi.it\n- Anna Bernasconi - Assistant Professor - Politecnico di Milano - anna.bernasconi@polimi.it\n- Matteo Chiara - Associate Professor - Università degli Studi di Milano - matteo.chiara@unimi.it\n- Stefano Ceri - Full Professor - Politecnico di Milano - stefano.ceri@polimi.it\n\n\n## License\n\u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc-nd/4.0/\"\u003e\u003cimg alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-nc-nd/4.0/88x31.png\" /\u003e\u003c/a\u003e\u003cbr /\u003eThis work is licensed under a \u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc-nd/4.0/\"\u003eCreative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License\u003c/a\u003e.\n \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomalf2%2Frecombinhunt-cov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomalf2%2Frecombinhunt-cov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomalf2%2Frecombinhunt-cov/lists"}