bscampp 1.0.1__py3-none-any.whl

bscampp-1.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ewedell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bscampp-1.0.1.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.2
+Name: bscampp
+Version: 1.0.1
+Summary: BSCAMPP - A Scalable Phylogenetic Placement Tool
+Author-email: Eleanor Wedell <ewedell2@illinois.edu>, Chengze Shen <chengze5@illinois.edu>
+License: MIT License
+        
+        Copyright (c) 2022 ewedell
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ewedell/BSCAMPP
+Project-URL: Changelog, https://github.com/ewedell/BSCAMPP/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development
+Classifier: License :: OSI Approved :: GNU General Public License (GPL)
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ConfigParser>=5.0.0
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: treeswift>=1.1.45
+Requires-Dist: taxtastic>=0.9.3
+
+# BSCAMPP - A Scalable Phylogenetic Placement Method and Framework
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bscampp)](https://pypi.org/project/bscampp/)
+[![PyPI - Version](https://img.shields.io/pypi/v/bscampp?color=blue)](https://pypi.org/project/bscampp/#history)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/ewedell/BSCAMPP/python-package.yml?branch=main&label=build)](https://github.com/ewedell/BSCAMPP/)
+[![PyPI - License](https://img.shields.io/pypi/l/bscampp?color=blue)](https://github.com/ewedell/BSCAMPP/blob/main/LICENSE)
+[![Changelog](https://img.shields.io/badge/CHANGELOG-grey)](https://github.com/ewedell/BSCAMPP/blob/main/CHANGELOG.md)
+
+**Table of Contents**
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [Example Code and Data](#example-code-and-data)
+
+# Overview
+* **Inputs**
+  1. Reference tree to place sequences into.
+  2. Alignment of reference sequences.
+  3. Alignment of query sequences (can be combined with ii.).
+  4. Tree info file.
+     - (EPA-ng as base method), RAxML-ng info file, typically with suffix `.bestModel`.
+     - (pplacer as base method), RAxML-ng or FastTree log file.
+* **Output**
+  1. Placement results of query sequences in the reference tree in `.jplace` format.
+
+
+BSCAMPP is an extension and scalable solution to its previous method [SCAMPP](https://github.com/chry04/PLUSplacer) for phylogenetic placement.
+BSCAMPP achieves some magnitudes of speedup compared to the SCAMPP framework.
+The core algorithm is described in detail at <https://doi.org/10.1101/2022.10.26.513936>.
+In short, BSCAMPP in default uses EPA-ng as the base placement method, allowing it to scale to placement trees of up to ~200,000 leaves.
+BSCAMPP achieves this by extracting appropriate subtrees and assigning each query to its most fitting subtree.
+
+BSCAMPP essentially is a divide-and-conquer framework and can be used with any base placement methods (e.g., `pplacer` as well).
+Currently, BSCAMPP is implemented with `epa-ng` and `pplacer`.
+
+It is recommended that BSCAMPP be used with subtrees of size 2000 and with 5 votes based on current best results, especially if sequences
+are fragmentary. Defaults for the subtree size and number of votes are set to 2,000 and 5 respectively (see [Usage](#usage) for more details
+on customizing BSCAMPP).
+
+# Installation
+BSCAMPP was tested on **Python 3.7 to 3.12**. There are two ways to install and use BSCAMPP: (1) with PyPI, or
+(2) from this GitHub repository. If you have any difficulties installing or running BSCAMPP, please contact Eleanor Wedell
+(ewedell@illinois.edu).
+
+### External requirements
+EPA-ng and/or pplacer are requirements to run BSCAMPP since BSCAMPP will use them as the base phylogenetic placement methods.
+By default, BSCAMPP will search for binary executables of `pplacer` and `epa-ng` in the user's environment when running for the first time.
+We also included a compiled version of `pplacer` for the Linux system under `bscampp/tools`.
+
+### (1) Install with `pip` (Coming soon)
+The easiest way to install BSCAMPP is to use `pip install`. This will also install all required Python packages.
+
+```bash
+# 1. install with pip (--user if no root access)
+pip install bscampp [--user]
+
+# 2. Two binary executables will be installed. The first time
+#    running any will create a config file at
+#    ~/.bscampp/main.config that resolves the links to all
+#    external software (e.g., epa-ng, pplacer)
+bscampp [-h]    # or
+run_bscampp.py [-h]
+```
+
+### (2) Install from GitHub
+Alternatively, the user can clone this GitHub repository and install the required packages manually.
+
+#### Requirements
+```bash
+python>=3.7
+ConfigParser>=5.0.0
+numpy>=1.21.6
+treeswift>=1.1.45
+taxtastic>=0.9.3
+```
+
+```bash
+# 1. Close the GitHub repo
+git clone https://github.com/ewedell/BSCAMPP.git
+
+# 2. Install all requirements
+pip install -r requirements.txt
+
+# 3. Execute BSCAMPP executable `run_bscampp.py`
+python run_bscampp.py [-h]
+```
+
+# Usage
+All parameter settings can be found by running
+```bash
+run_bscampp.py -h
+```
+
+### (1) Default case (`epa-ng`)
+```bash
+run_bscampp.py -i [raxml best model] -t [reference tree] -a [alignment file]
+```
+To run BSCAMPP in its default mode with EPA-ng. `[alignment file]` should contain both sequences from the placement tree and
+the query sequences to be placed. This will create an output directory `bscampp_output` and write the placement results to
+`bscampp_output/bscampp_result.jplace`.
+
+### (2) Separately giving query alignment and finer control of outputs
+```bash
+run_bscampp.py -i [raxml best model] -t [reference tree] -a [reference alignment] \
+    -q [query sequence alignment] -d [output directory] -o [output name] \
+    --threads [num cpus]
+```
+
+### (3) Using `pplacer` as the base placement method
+```bash
+run_bscampp.py -i [logfile from either RAxML/FastTree] -t [reference tree] \
+    -a [reference alignment] -q [query sequence alignment]
+```
+
+### More comprehensive usage
+```bash
+> usage: run_bscampp.py [-h] [-v] [--placement-method {epa-ng,pplacer}] -i
+>                       INFO_PATH -t TREE_PATH -a ALN_PATH [-q QALN_PATH]
+>                       [-d OUTDIR] [-o OUTNAME] [--threads NUM_CPUS] [-m MODEL]
+>                       [-b SUBTREESIZE] [-V VOTES]
+>                       [--similarityflag SIMILARITYFLAG] [-n TMPFILENBR]
+>                       [--fragmentflag FRAGMENTFLAG] [--keeptemp KEEPTEMP]
+> 
+> This program runs BSCAMPP, a scalable phylogenetic placement framework that scales EPA-ng/pplacer to very large tree placement.
+> 
+> options:
+>   -h, --help            show this help message and exit
+>   -v, --version         show program's version number and exit
+> 
+> BASIC PARAMETERS:
+>   These are the basic parameters for BSCAMPP.
+> 
+>   --placement-method {epa-ng,pplacer}
+>                         The base placement method to use. Default: epa-ng
+>   -i INFO_PATH, --info INFO_PATH, --info-path INFO_PATH
+>                         Path to model parameters. E.g., .bestModel from
+>                         RAxML/RAxML-ng
+>   -t TREE_PATH, --tree TREE_PATH, --tree-path TREE_PATH
+>                         Path to reference tree with estimated branch lengths
+>   -a ALN_PATH, --alignment ALN_PATH, --aln-path ALN_PATH
+>                         Path for reference sequence alignment in FASTA format.
+>                         Optionally with query sequences. Query alignment can
+>                         be specified with --qaln-path
+>   -q QALN_PATH, --qalignment QALN_PATH, --qaln-path QALN_PATH
+>                         Optionally provide path to query sequence alignment in
+>                         FASTA format. Default: None
+>   -d OUTDIR, --outdir OUTDIR
+>                         Directory path for output. Default: bscampp_output/
+>   -o OUTNAME, --output OUTNAME
+>                         Output file name. Default: bscampp_result.jplace
+>   --threads NUM_CPUS, --num-cpus NUM_CPUS
+>                         Number of cores for parallelization, default: -1 (all)
+> 
+> ADVANCE PARAMETERS:
+>   These parameters control how BSCAMPP is run. The default values are set based on experiments.
+> 
+>   -m MODEL, --model MODEL
+>                         Model used for edge distances. Default: GTR
+>   -b SUBTREESIZE, --subtreesize SUBTREESIZE
+>                         Integer size of the subtree. Default: 2000
+>   -V VOTES, --votes VOTES
+>                         Number of votes per query sequence. Default: 5
+>   --similarityflag SIMILARITYFLAG
+>                         Boolean, True if maximizing sequence similarity
+>                         instead of simple Hamming distance (ignoring gap sites
+>                         in the query). Default: True
+> 
+> MISCELLANEOUS PARAMETERS:
+>   -n TMPFILENBR, --tmpfilenbr TMPFILENBR
+>                         Temporary file indexing. Default: 0
+>   --fragmentflag FRAGMENTFLAG
+>                         If queries contains fragments. Default: True
+>   --keeptemp KEEPTEMP   Boolean, True to keep all temporary files. Default:
+                        False
+```
+
+
+# Example Code and Data
+Example script and data are provided in this GitHub repository in `examples/`. The data is originally from the [RNAsim-VS datasets](https://doi.org/10.1093/sysbio/syz063).
+* `examples/run.sh`: contains a simple script to test BSCAMPP with `epa-ng` or `pplacer`, placing 200 query sequences to a 10000-leaf placement tree.
+  The info file is from RAxML-ng when running `epa-ng`, and from FastTree-2 when running `pplacer`.
+  - `run.sh` will invoke BSCAMPP with `epa-ng`.
+  - `run.sh pplacer` will invoke BSCAMPP with `pplacer`.

bscampp-1.0.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+bscampp/__init__.py,sha256=mfEO3icT2L6hUzGTGXngIfvKxymEspmxBYFvbfSqRx0,2289
+bscampp/configs.py,sha256=XuzRbtcUE5bExe-vEZGZ1CeXBmp4oP7LWFveQySx2xs,5745
+bscampp/default.config,sha256=CEfsUHBy--vwJhEcUuJ0btfuGQWb_lKMVWUIP9f5YGw,112
+bscampp/functions.py,sha256=cPT5eSy_8CSNzDx-5ma43Hp9_AMmaWSTXM89bjdrkRs,15640
+bscampp/init_configs.py,sha256=EA9sMN5jWj6zj2b-7tN19LhX2Ef61ByQLxQRLHAqLDM,3600
+bscampp/jobs.py,sha256=de0Dr3ynORwACJqVbeWDfqTwJhWvMYG-7yfRYirGx8M,6703
+bscampp/pipeline.py,sha256=2pQTmBj9LLyuLyCTJgoKvBj19RAzbkC5FuDman5zpD0,9902
+bscampp/utils.py,sha256=ragaI14Lqb2fVp_uYDkFQnV7a50G9-sUOWdVM-sNhUE,29005
+bscampp/tools/epa-ng,sha256=f3EVoZAAOXLN6l521qp-TrWDl5J2nqL3tGgjPaQE9WQ,3772096
+bscampp/tools/pplacer,sha256=p0H4eo9uuiYoWS_kJbPfauOV99i7BXJdZSiwXIuLxTw,7834576
+bscampp/tools/hamming_distance/CMakeLists.txt,sha256=yf9iq7Y61t3WObJHoR4RoGDEvUw_Q8JW3UnI4uh0cfU,389
+bscampp/tools/hamming_distance/fragment_hamming,sha256=AYVNIkrFZVG222ePKwsAXpAVD0-GOMJJq3uTpghvtCM,43160
+bscampp/tools/hamming_distance/hamming,sha256=KF-UP37qXGy2Qy0dmMGjUrfSLpe0qlKDTt0Pt5g0vsc,43160
+bscampp/tools/hamming_distance/homology,sha256=4-F92hdpBc98FxXBrhq4qdwtEBzOcXmk6EFIDpuk-e0,43152
+bscampp/tools/hamming_distance/src/fragment_hamming.cpp,sha256=Sh76zMA5L-MOUVOcTRQ7N6Yq_iOhq6rqgAihxQsEnQ8,6197
+bscampp/tools/hamming_distance/src/fragment_tree_hamming.cpp,sha256=xCmyAT-OZJOD-Bk6oKw0seM_4Zn177JvZBlou9Mw6dQ,6286
+bscampp/tools/hamming_distance/src/fragment_tree_hamming_new.cpp,sha256=eKxgODRlpf0hU84QjNhigvRhWCT9tiJZjA5oQFQ1bUk,7404
+bscampp/tools/hamming_distance/src/homology.cpp,sha256=ZE0uXZWQ-cN4U1Wk5kUr_KKHgzsgA6Sno-IViRa4tmI,6053
+bscampp/tools/hamming_distance/src/new_hamming.cpp,sha256=fBRm99RquBZgZjaLOn9xDI3cH9NchhrxKbL-11j8fmk,5342
+bscampp-1.0.1.dist-info/LICENSE,sha256=HEa4YQdOR0e2Gz-NiOwr9X6aJcZtY0AGmlJQDmfN0Iw,1064
+bscampp-1.0.1.dist-info/METADATA,sha256=06T5y13XSerQS_nb4hTk-i6aaIJ8gdCuCvk-hK75nPg,11142
+bscampp-1.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+bscampp-1.0.1.dist-info/entry_points.txt,sha256=dZygBmg2OncVyeLeIjh_9e-GBIOesFvMemyW9BRRcXY,113
+bscampp-1.0.1.dist-info/top_level.txt,sha256=1loGRUAft6Tcdq0f3lHbVwWN7W_SW1srfhAVSpg9DWE,8
+bscampp-1.0.1.dist-info/RECORD,,

bscampp-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bscampp-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bscampp = bscampp.pipeline:bscampp_pipeline
+run_bscampp.py = bscampp.pipeline:bscampp_pipeline

bscampp-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bscampp