bscampp 1.0.1a0__tar.gz

bscampp-1.0.1a0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# BSCAMPP v1.0.1a
+1. Completed features with both `epa-ng` and `pplacer` support.
+2. Refactorized all codes and worked out the PyPI installation for release.

bscampp-1.0.1a0/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.1a0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include CHANGELOG.md
+include run_bscampp.py
+include bscampp/default.config
+include requirements.txt
+graft bscampp/tools
+prune */__pycache__
+global-exclude *.py[cod]

bscampp-1.0.1a0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.2
+Name: bscampp
+Version: 1.0.1a0
+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
+
+**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.1a0/README.md

@@ -0,0 +1,177 @@
+# BSCAMPP - A Scalable Phylogenetic Placement Method and Framework
+
+**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.1a0/bscampp/__init__.py

@@ -0,0 +1,68 @@
+############################################################
+#
+#   Init file for BSCAMPP, using the __init__.py from
+#   SEPP as the original template. Current adaption comes
+#   from https://github.com/c5shen/TIPP3.git
+#
+############################################################
+from operator import itemgetter
+import logging, os
+
+# update system recursion limit to avoid issues
+# not really needed for BSCAMPP but safe to update here
+os.sys.setrecursionlimit(1000000)
+
+__version__ = "1.0.1a"
+_INSTALL_PATH = __path__[0]
+
+# global variables to store all loggers
+__set_loggers = set()
+
+# obtain the current logging level, default to INFO
+def get_logging_level(logging_level='info'):
+    logging_level_map = {
+            'DEBUG': logging.DEBUG, 'INFO': logging.INFO,
+            'WARNING': logging.WARNING, 'ERROR': logging.ERROR,
+            'CRITICAL': logging.CRITICAL,
+            }
+    # obtain from environment variable to determine logging level, if
+    # set by the user
+    env_level = os.getenv('BSCAMPP_LOGGING_LEVEL')
+    if env_level is not None:
+        ll = env_level.upper()
+    else:
+        ll = logging_level.upper()
+    # default to INFO if ll is not defined
+    return logging_level_map.get(ll, logging.INFO)
+
+# obtain a logger for a given file
+def get_logger(name='bscampp', log_path=None, logging_level='info'):
+    logger = logging.getLogger(name)
+    if name not in __set_loggers:
+        # set up a new logger for a name not in __set_loggers yet
+        level = get_logging_level(logging_level)
+        logging_formatter = logging.Formatter(
+            ("[%(asctime)s] %(filename)s (line %(lineno)d):"
+             " %(levelname) 8s: %(message)s"))
+        logging_formatter.datefmt = "%H:%M:%S"
+        logger.setLevel(level)
+
+        # logging to stdout
+        if log_path is None:
+            ch = logging.StreamHandler()
+        else:
+            # use FileHandler for logging
+            ch = logging.FileHandler(log_path, mode='a')
+        ch.setLevel(level)
+        ch.setFormatter(logging_formatter)
+        logger.addHandler(ch)
+        __set_loggers.add(name)
+    return logger
+
+# logging exception
+def log_exception(logger):
+    import traceback, io
+    s = io.StringIO()
+    traceback.print_exc(None, s)
+    logger.error(s.getvalue())
+    exit(1)

bscampp-1.0.1a0/bscampp/configs.py

@@ -0,0 +1,169 @@
+import os, time
+try:
+    import configparser
+except ImportError:
+    from ConfigParser import configparser
+from argparse import ArgumentParser, Namespace
+from bscampp.init_configs import init_config_file
+from bscampp import get_logger, log_exception
+
+# detect home.path or create if missing
+homepath = os.path.dirname(__file__) + '/home.path'
+_root_dir, main_config_path = init_config_file(homepath)
+
+# set valid configparse section names
+valid_config_sections = []
+logging_levels = set(['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'])
+
+_LOG = get_logger(__name__)
+
+'''
+Configuration defined by users and by default values
+'''
+class Configs:
+    global _root_dir
+
+    # basic input paths
+    info_path = None        # info file for pplacer or EPA-ng
+    tree_path = None        # placement tree path
+    aln_path = None         # alignment for backbone. Optinally with queries
+    qaln_path = None        # (optional) alignment for query.
+    outdir = None           # output directory
+    outname = None          # output name for the final jplace file
+    keeptemp = False        # whether to keep all temporary files
+    verbose = 'INFO'        # default verbose level to print
+    num_cpus = 1            # number of cores to use for parallelization
+
+    # binaries
+    pplacer_path = None
+    epang_path = None
+    taxit_path = None
+    hamming_distance_dir = None
+
+    # placement settings
+    placement_method = 'epa-ng'
+    model = 'GTR'
+    subtreesize = 2000
+    votes = 5
+    similarityflag = True
+
+    # miscellaneous
+    tmpfilenbr = 0
+    fragmentflag = True
+
+# check if the given configuration is valid to add
+def set_valid_configuration(name, conf):
+    if not isinstance(conf, Namespace):
+        _LOG.warning(
+            "Looking for Namespace object from \'{}\' but find {}".format(
+                name, type(conf)))
+        return
+
+    # basic section defined in main.config
+    if name == 'basic':
+        for k in conf.__dict__.keys():
+            k_attr = getattr(conf, k)
+            if not k_attr:
+                continue
+            if k in Configs.__dict__:
+                setattr(Configs, k, k_attr)
+    else:
+        pass
+
+# valid attribute check for print out
+def valid_attribute(k, v):
+    if not isinstance(k, str):
+        return False
+    if k.startswith('_'):
+        return False
+    return True
+
+# print out current configuration
+def getConfigs():
+    msg = '\n************ Configurations ************\n' + \
+            f'\thome.path: {homepath}\n' + \
+            f'\tmain.config: {main_config_path}\n\n'
+    for k, v in Configs.__dict__.items():
+        if valid_attribute(k, v):
+            msg += f'\tConfigs.{k}: {v}\n'
+    print(msg, flush=True)
+
+# read in config file if it exists
+def _read_config_file(filename, cparser, opts,
+        child_process=False, expand=None):
+    config_defaults = []
+    with open(filename, 'r') as f:
+        cparser.read_file(f)
+        if cparser.has_section('commandline'):
+            for k, v in cparser.items('commandline'):
+                config_defaults.append(f'--{k}')
+                config_defaults.append(v)
+
+        for section in cparser.sections():
+            if section == 'commandline':
+                continue
+            if getattr(opts, section, None):
+                section_name_space = getattr(opts, section)
+            else:
+                section_name_space = Namespace()
+            for k, v in cparser.items(section):
+                if expand and k == 'path':
+                    v = os.path.join(expand, v)
+                setattr(section_name_space, k, v)
+            setattr(opts, section, section_name_space)
+    return config_defaults
+
+'''
+Build Config class
+'''
+def buildConfigs(parser, cmdline_args, child_process=False, rerun=False):
+    cparser = configparser.ConfigParser()
+    cparser.optionxform = str
+    args = parser.parse_args(cmdline_args)
+
+    # Check if only updating config files, if so, re-initialize the 
+    # configuration file at ~/.bscampp/main.config and exit
+    #if args.command == 'update-configs':
+    #    _ = init_config_file(homepath, rerun=True)
+    #    _LOG.warning('Finished re-initializing the configuration file '
+    #            f'at {main_config_path}, exiting...')
+    #    exit(0)
+
+    # first load arguments from main.configs
+    main_args = Namespace()
+    cmdline_main = _read_config_file(main_config_path,
+            cparser, main_args, child_process=child_process)
+
+    # merge arguments, in the correct order so things are overridden correctly
+    args = parser.parse_args(cmdline_main + cmdline_args,
+            namespace=main_args)
+
+    # directly add all arguments that's defined in the Configs class
+    for k in args.__dict__.keys():
+        k_attr = getattr(args, k)
+        if k in Configs.__dict__:
+            # valid argument that's defined in the Configs class
+            setattr(Configs, k, k_attr)
+        else:
+            # check if the argument is valid
+            set_valid_configuration(k, k_attr)
+
+    # create outdir
+    if not os.path.isdir(Configs.outdir):
+        os.makedirs(Configs.outdir)
+
+    # modify outname if it does not have a .jplace suffix
+    if Configs.outname.split('.')[-1].lower() != 'jplace':
+        Configs.outname += '.jplace'
+
+    # modify num_cpus if it is the default value
+    if Configs.num_cpus > 0:
+        Configs.num_cpus = min(os.cpu_count(), Configs.num_cpus)
+    else:
+        Configs.num_cpus = os.cpu_count()
+
+    # sanity check for existence of base placement binary path
+    if Configs.placement_method == 'epa-ng':
+        assert os.path.exists(Configs.epang_path), 'epa-ng not detected!'
+    elif Configs.placement_method == 'pplacer':
+        assert os.path.exists(Configs.pplacer_path), 'pplacer not detected!'

bscampp-1.0.1a0/bscampp/default.config

@@ -0,0 +1,5 @@
+[basic]
+pplacer_path            =
+epang_path              =
+taxit_path              =
+hamming_distance_dir    =