simple-blast 0.0.5__tar.gz

simple_blast-0.0.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Andrew Tapia
+
+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.

simple_blast-0.0.5/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: simple_blast
+Version: 0.0.5
+Summary: A simple library for executing BLAST searches with ncbi-blast+
+Author-email: Andrew Tapia <andrew.tapia@uky.edu>
+Project-URL: Homepage, https://github.com/actapia/simple_blast
+Project-URL: Bug Tracker, https://github.com/actapia/simple_blast
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5.3
+
+# simple_blast
+
+This is a library that provides a very basic wrapper around ncbi-blast+.
+Currently, the library supports searches with `blastn` only, but I may expand
+the library to include wrappers for other BLAST executables if I need them.
+
+## Requirements
+
+This library depends on Pandas for parsing BLAST output. The library has been
+tested with Pandas 1.5.3, but it likely works with other versions.
+
+Of course, this library assumes that ncbi-blast+ is installed. The library has
+been tested with ncbi-blast 2.12.0+, and it likely works with newer versions of
+the software as well.
+
+## Basic usage
+
+You can define a `blastn` search to be carried out using the `BlastnSearch`
+class. `BlastnSearch`objects are constructed with two required
+arguments&mdash;the subject sequence and the query sequence files, in that
+order. For example, to set up a `balstn` search for sequences in `seqs1.fasta`
+against those in `seqs2.fasta`, you could construct a `BlastnSearch` object like
+this:
+
+```python
+from simple_blast import BlastnSearch
+
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta")
+```
+
+The BLAST search is not carried out until you ask for the results by accessing
+the `hits` property of the search. This property returns a Pandas dataframe
+containing the HSPs identified in the BLAST search.
+
+```python
+results = search.hits
+```
+
+The columns in the output may be configured by passing either the `out_columns`
+or `additional_columns` arguments when constructing the `BlastnSearch`. The
+former argument overrides the set of output columns; the latter argument is
+added to the list of default output columns.
+
+You can also specify an e-value cutoff through the `evalue` argument.
+
+## DB caches
+
+When the same sequence file is used as a subject in multiple searches, it can be
+efficient to build a BLAST database up front. The `BlastDBCache` class can be
+used to handle this mostly automatically. To make a `BlastDBCache`, you need
+to specify the location of the on the file system.
+
+```python
+from simple_blast import BlastDBCache
+
+cache = BlastDBCache("cache_dir")
+```
+
+To add a file to the cache, use the `makedb` method.
+
+```python
+cache.makedb("seqs2.fasta")
+```
+
+When constructing a `BlastnSearch` object, give it the `BlastDBCache` as the
+`db_cache` parameter to make the `BlastnSearch` object use the cache for
+searches.
+
+```python
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta", db_cache=cache)
+```
+
+Now `search` will use the database we created for `seqs2.fasta`.

simple_blast-0.0.5/README.md

@@ -0,0 +1,73 @@
+# simple_blast
+
+This is a library that provides a very basic wrapper around ncbi-blast+.
+Currently, the library supports searches with `blastn` only, but I may expand
+the library to include wrappers for other BLAST executables if I need them.
+
+## Requirements
+
+This library depends on Pandas for parsing BLAST output. The library has been
+tested with Pandas 1.5.3, but it likely works with other versions.
+
+Of course, this library assumes that ncbi-blast+ is installed. The library has
+been tested with ncbi-blast 2.12.0+, and it likely works with newer versions of
+the software as well.
+
+## Basic usage
+
+You can define a `blastn` search to be carried out using the `BlastnSearch`
+class. `BlastnSearch`objects are constructed with two required
+arguments—the subject sequence and the query sequence files, in that
+order. For example, to set up a `balstn` search for sequences in `seqs1.fasta`
+against those in `seqs2.fasta`, you could construct a `BlastnSearch` object like
+this:
+
+```python
+from simple_blast import BlastnSearch
+
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta")
+```
+
+The BLAST search is not carried out until you ask for the results by accessing
+the `hits` property of the search. This property returns a Pandas dataframe
+containing the HSPs identified in the BLAST search.
+
+```python
+results = search.hits
+```
+
+The columns in the output may be configured by passing either the `out_columns`
+or `additional_columns` arguments when constructing the `BlastnSearch`. The
+former argument overrides the set of output columns; the latter argument is
+added to the list of default output columns.
+
+You can also specify an e-value cutoff through the `evalue` argument.
+
+## DB caches
+
+When the same sequence file is used as a subject in multiple searches, it can be
+efficient to build a BLAST database up front. The `BlastDBCache` class can be
+used to handle this mostly automatically. To make a `BlastDBCache`, you need
+to specify the location of the on the file system.
+
+```python
+from simple_blast import BlastDBCache
+
+cache = BlastDBCache("cache_dir")
+```
+
+To add a file to the cache, use the `makedb` method.
+
+```python
+cache.makedb("seqs2.fasta")
+```
+
+When constructing a `BlastnSearch` object, give it the `BlastDBCache` as the
+`db_cache` parameter to make the `BlastnSearch` object use the cache for
+searches.
+
+```python
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta", db_cache=cache)
+```
+
+Now `search` will use the database we created for `seqs2.fasta`.

simple_blast-0.0.5/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simple_blast"
+version = "0.0.5"
+authors = [
+    { name = "Andrew Tapia", email = "andrew.tapia@uky.edu" }
+]
+description =  "A simple library for executing BLAST searches with ncbi-blast+"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pandas >= 1.5.3"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/actapia/simple_blast"
+"Bug Tracker" = "https://github.com/actapia/simple_blast"

simple_blast-0.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simple_blast-0.0.5/src/simple_blast/__init__.py

@@ -0,0 +1,4 @@
+from .blasting import BlastnSearch
+from .blastdb_cache import BlastDBCache
+
+__all__ = ["BlastnSearch", "BlastDBCache"]

simple_blast-0.0.5/src/simple_blast/blastdb_cache.py

@@ -0,0 +1,73 @@
+import subprocess
+import tempfile
+from pathlib import Path
+
+def read_nal_title(nal):
+    with open(nal, "r") as nal_file:
+        for l in nal_file:
+            if not l.startswith("#"):
+                split = l.rstrip().split(" ")
+                if split[0] == "TITLE":
+                    return " ".join(split[1:])
+            
+
+class BlastDBCache:
+    def __init__(self, location, find_existing=True, parse_seqids=False):
+        self.location = location
+        self._cache = {}
+        if find_existing:
+            for path in Path(location).glob("*/*.nal"):
+                self._cache[Path(read_nal_title(path))] = path.parent / "db"
+        self._parse_seqids = parse_seqids
+
+    @property
+    def parse_seqids(self):
+        return self._parse_seqids
+
+    def _build_makeblastdb_command(self, seq_file_path, db_name):
+        command = [
+                "makeblastdb",
+                "-in",
+                str(seq_file_path),
+                "-out",
+                db_name,
+                "-dbtype",
+                "nucl",
+                "-hash_index" # Do I need this?
+        ]
+        if self._parse_seqids:
+            command.append("-parse_seqids")
+        return command
+
+    def makedb(self, seq_file_path):
+        seq_file_path = Path(seq_file_path)
+        if seq_file_path in self._cache:
+            return
+        seq_name = seq_file_path.stem
+        tempdir = Path(
+            tempfile.mkdtemp(
+                prefix=seq_name,
+                dir=self.location
+            )
+        )
+        db_name = str(tempdir / "db")
+        proc = subprocess.Popen(
+            self._build_makeblastdb_command(seq_file_path, db_name),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+        proc.communicate()
+        if proc.returncode:
+            raise subprocess.CalledProcessError(proc.returncode, proc.args)
+        self._cache[seq_file_path] = db_name
+
+    def __getitem__(self, k):
+        return self._cache[Path(k)]
+
+    def __delitem__(self, k):
+        del self._cache[Path(k)]
+
+    def __contains__(self, k):
+        return Path(k) in self._cache
+        
+        

simple_blast-0.0.5/src/simple_blast/blasting.py

@@ -0,0 +1,220 @@
+import subprocess
+import pandas as pd
+from typing import List, Optional
+
+from .blastdb_cache import BlastDBCache
+
+default_out_columns = ['qseqid',
+ 'sseqid',
+ 'pident',
+ 'length',
+ 'mismatch',
+ 'gapopen',
+ 'qstart',
+ 'qend',
+ 'sstart',
+ 'send',
+ 'evalue',
+ 'bitscore']
+
+yes_no = ["no", "yes"]
+
+class BlastnSearch:
+    """A search (alignment) to be made with blastn.
+
+    This class provides a programmer-friendly way to define the parameters of a
+    simple blastn search, carry out the search, and parse the results.
+
+    The most useful property of a BlastnSearch instance is hits. hits runs the
+    defined blastn search (if it hasn't been run already), parses the results,
+    stores them in a pandas dataframe, and returns the result.
+
+    Values passed to the constructor may be retrieved through the class's
+    properties.
+
+    Attributes:
+        debug (bool): Whether to enable debug features for this instance.
+    """
+    def __init__(
+            self,
+            seq1_path: str,
+            seq2_path: str,
+            evalue: float = 1e-20,
+            out_columns: List[str] = default_out_columns,
+            additional_columns: List[str] = [],
+            db_cache: Optional[BlastDBCache] = None,
+            threads: int = 1,
+            dust: bool = True,
+            task: Optional[str] = None,
+            max_targets: int = 500,
+            n_seqidlist: Optional[str] = None,
+            debug: bool = False
+    ):
+        """Construct a BlastnSearch with the specified settings.
+
+        This constructor requires paths to FASTA files containing the query and
+        subject sequences to use in the search.
+
+        Optionally, the caller may provide an expect value cutoff to use for the
+        search. If no value is provided, a default evalue of 1e-20 will be used.
+
+        The caller may specify what columns should be included in the output.
+        By default, the included columns are
+
+            sseqid
+            pident
+            length
+            mismatcch
+            gapopen
+            qstart
+            qend
+            sstart
+            send
+            evalue
+            bitscore
+
+        Explanations of these columns may be found at
+        https://www.metagenomics.wiki/tools/blast/blastn-output-format-6
+
+        If the caller desires to include additional columns, it may provide
+        them to the additional_columns parameter.
+
+        Parameters:
+            seq1_path (str):    Path to query sequence FASTA file.
+            seq2_path (str):    Path to subject sequence FASTA file.
+            evalue (float):     Expect value cutoff to use in BLAST search.
+            out_columns:        Output columns to include in results.
+            additional_columns: Additional output columns to include in results.
+            db_cache:           BlastDBCache that tells where to find BLAST DBs.
+            threads (int):      Number of threads to use for BLAST search.
+            dust (bool):        Filter low-complexity regions from search.
+            task (str):         Parameter preset to use.
+            max_targets (int):  Maximum number of target seqs to include.
+            n_seqidlist (str):  Specifies seqids to ignore.
+            debug (bool):       Whether to enable debug features.
+        """
+        self._seq1_path = seq1_path
+        self._seq2_path = seq2_path
+        self._evalue = evalue
+        self._hits = None
+        self._out_columns = list(out_columns + additional_columns)
+        self._db_cache = db_cache
+        self._threads =  threads
+        self._dust = dust
+        self._task = task
+        self._max_targets = max_targets
+        self._negative_seqidlist = n_seqidlist
+        # If you really need to add extra arguments, you can do it by setting
+        # the _extra_args attribute.
+        self._extra_args = []
+        self.debug = debug
+
+    @property
+    def seq1_path(self) -> str:
+        """Return the query sequence path."""
+        return self._seq1_path
+
+    @property
+    def seq2_path(self) -> str:
+        """Return the subject sequence path."""
+        return self._seq2_path
+
+    @property
+    def evalue(self) -> float:
+        """Return the expect value used as a cutoff in the blastn search."""
+        return self._evalue
+
+    @property
+    def db_cache(self) -> Optional[BlastDBCache]:
+        """Return a cache of BLAST DBs to be used in the search."""
+        return self._db_cache
+
+    @property
+    def hits(self) -> pd.DataFrame:
+        """Return a dataframe containing this search's BLAST results."""
+        if self._hits is None:
+            self._get_hits()
+        return self._hits
+
+    @property
+    def threads(self) -> int:
+        """Return the number of threads to use for the search."""
+        return self._threads
+
+    @property
+    def dust(self) -> bool:
+        """Return whether to filter low-complexity regions."""
+        return self._dust
+
+    @property
+    def task(self) -> Optional[str]:
+        """Return the name of the parameter preset to use."""
+        return self._task
+
+    @property
+    def max_targets(self) -> int:
+        """Return the maximum number of target sequences."""
+        return self._max_targets
+
+    @property
+    def negative_seqidlist(self) -> Optional[str]:
+        """Return a path to a list of sequence IDs to ignore."""
+        return self._negative_seqidlist
+
+
+    # def __len__(self) -> int:
+    #     return len(self.hits)
+
+    # def __iter__(self):
+    #     yield from self.hits
+
+    def _build_blast_command(self):
+        command = ["blastn"]
+        if self._db_cache and self.seq1_path in self._db_cache:
+            command = command + ["-db", str(self._db_cache[self.seq1_path])]
+        else:
+            command = command + ["-subject", self.seq1_path]
+        if self._task is not None:
+            command = command + ["-task", self._task]
+        if self._negative_seqidlist is not None:
+            command = command + [
+                "-negative_seqidlist",
+                self._negative_seqidlist
+            ]
+        command = command + [
+            "-query",
+            str(self.seq2_path),
+            "-evalue",
+            str(self.evalue),
+            "-outfmt",
+            " ".join(["6"] + self._out_columns),
+            "-num_threads",
+            str(self._threads),
+            "-dust",
+            yes_no[self._dust],
+            "-max_target_seqs",
+            str(self._max_targets)
+        ] + self._extra_args
+        #print(" ".join(command), file=sys.stderr)
+        return command
+            
+
+    def _get_hits(self):
+        proc = subprocess.Popen(
+            self._build_blast_command(),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE
+        )
+        self._hits = pd.read_csv(
+            proc.stdout,
+            names=self._out_columns,
+            delim_whitespace=True
+        )
+        # from IPython import embed
+        # embed()
+        proc.communicate()
+        if proc.returncode:
+            if self.debug:
+                from IPython import embed
+                embed()
+            raise subprocess.CalledProcessError(proc.returncode, proc.args)

simple_blast-0.0.5/src/simple_blast.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: simple_blast
+Version: 0.0.5
+Summary: A simple library for executing BLAST searches with ncbi-blast+
+Author-email: Andrew Tapia <andrew.tapia@uky.edu>
+Project-URL: Homepage, https://github.com/actapia/simple_blast
+Project-URL: Bug Tracker, https://github.com/actapia/simple_blast
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5.3
+
+# simple_blast
+
+This is a library that provides a very basic wrapper around ncbi-blast+.
+Currently, the library supports searches with `blastn` only, but I may expand
+the library to include wrappers for other BLAST executables if I need them.
+
+## Requirements
+
+This library depends on Pandas for parsing BLAST output. The library has been
+tested with Pandas 1.5.3, but it likely works with other versions.
+
+Of course, this library assumes that ncbi-blast+ is installed. The library has
+been tested with ncbi-blast 2.12.0+, and it likely works with newer versions of
+the software as well.
+
+## Basic usage
+
+You can define a `blastn` search to be carried out using the `BlastnSearch`
+class. `BlastnSearch`objects are constructed with two required
+arguments&mdash;the subject sequence and the query sequence files, in that
+order. For example, to set up a `balstn` search for sequences in `seqs1.fasta`
+against those in `seqs2.fasta`, you could construct a `BlastnSearch` object like
+this:
+
+```python
+from simple_blast import BlastnSearch
+
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta")
+```
+
+The BLAST search is not carried out until you ask for the results by accessing
+the `hits` property of the search. This property returns a Pandas dataframe
+containing the HSPs identified in the BLAST search.
+
+```python
+results = search.hits
+```
+
+The columns in the output may be configured by passing either the `out_columns`
+or `additional_columns` arguments when constructing the `BlastnSearch`. The
+former argument overrides the set of output columns; the latter argument is
+added to the list of default output columns.
+
+You can also specify an e-value cutoff through the `evalue` argument.
+
+## DB caches
+
+When the same sequence file is used as a subject in multiple searches, it can be
+efficient to build a BLAST database up front. The `BlastDBCache` class can be
+used to handle this mostly automatically. To make a `BlastDBCache`, you need
+to specify the location of the on the file system.
+
+```python
+from simple_blast import BlastDBCache
+
+cache = BlastDBCache("cache_dir")
+```
+
+To add a file to the cache, use the `makedb` method.
+
+```python
+cache.makedb("seqs2.fasta")
+```
+
+When constructing a `BlastnSearch` object, give it the `BlastDBCache` as the
+`db_cache` parameter to make the `BlastnSearch` object use the cache for
+searches.
+
+```python
+search = BlastnSearch("seqs2.fasta", "seqs1.fasta", db_cache=cache)
+```
+
+Now `search` will use the database we created for `seqs2.fasta`.

simple_blast-0.0.5/src/simple_blast.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/simple_blast/__init__.py
+src/simple_blast/blastdb_cache.py
+src/simple_blast/blasting.py
+src/simple_blast.egg-info/PKG-INFO
+src/simple_blast.egg-info/SOURCES.txt
+src/simple_blast.egg-info/dependency_links.txt
+src/simple_blast.egg-info/requires.txt
+src/simple_blast.egg-info/top_level.txt

simple_blast-0.0.5/src/simple_blast.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simple_blast-0.0.5/src/simple_blast.egg-info/requires.txt

@@ -0,0 +1 @@
+pandas>=1.5.3

simple_blast-0.0.5/src/simple_blast.egg-info/top_level.txt

@@ -0,0 +1 @@
+simple_blast