bscampp 1.0.1__tar.gz

bscampp-1.0.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# BSCAMPP v1.0.1
+1. Bumped version to full release.
+2. Completed examples for display in `bscampp --help`.
+
+# BSCAMPP v1.0.1b
+1. Removed redundant codes and fixed missing variables.
+2. Added badges for PyPI installation and current Python Build, etc.
+3. Added a single Pytest for dry-running BSCAMPP under `tests/`.
+4. For 3, added the `dry_run` parameter to function `pipeline.py:bscampp_pipeline`.
+
+# 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.1/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/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.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,182 @@
+# 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/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.1"
+_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)