Profile Searches

pyinfernal.infernal.cmsearch(queries, sequences, cpus=0, callback=None, backend='threading', parallel=None, **options)

Search CM profiles against a sequence database.

In Infernal many-to-many comparisons, a search is the operation of querying with profile CMs a database of sequences.

The cmsearch function offers two ways of managing the database that will be selected based on the type of the sequences argument. If sequences is a SequenceFile object, cmsearch will reopen the file in each thread, and load targets iteratively to scan with the query. Otherwise, it will pre-fetch the target sequences into a DigitalSequenceBlock collection, and share them across threads without copy. The pre-fetching gives much higher performance at the cost of extra startup time and much higher memory consumption. You may want to check how much memory is available (for instance with psutil.virtual_memory) before trying to load a whole sequence database, but it is really recommended to do so whenever possible.

Parameters:

• queries (iterable of CM) – The query CMs or profiles to search for in the database. Note that passing a single object is supported, but the function will always return an iterator.

• sequences (iterable of DigitalSequence) – A database of sequences to query. If you plan on using the same sequences several times, consider storing them into a DigitalSequenceBlock directly. If a SequenceFile is given, profiles will be loaded iteratively from disk rather than prefetched.

• cpus (int) – The number of threads to run in parallel. Pass 1 to run everything in the main thread, 0 to automatically select a suitable number (using psutil.cpu_count), or any positive number otherwise.

• callback (callable) – A callback that is called everytime a query is processed with two arguments: the query, and the total number of queries. This can be used to display progress in UI.

• backend (str) – The parallel backend to use for workers to be executed. Supports threading to use thread-based parallelism, or multiprocessing to use process-based parallelism.

• parallel (str) – The parallel strategy to use. Supports queries to run queries in parallel, or targets to parallelize on targets while running one query at a time. If None given, use queries by default unless we can detect that there is a single or a small number of queries. Note that parallelization on targets does not work with SequenceFile targets.

Yields:

TopHits – An object reporting top hits for each query, in the same order the queries were passed in the input. The number of included hits depends on the incE threshold passed as an option to the internal Pipeline.

Raises:

• AlphabetMismatch – When any of the query CMs and the sequences do not share the same alphabet.

• RuntimeError – When attempting to use targets parallel strategy with targets from a SequenceFile.

Note

Any additional arguments passed to the cmsearch function will be passed transparently to the Pipeline to be created. For instance, to run a cmsearch using a bitscore cutoffs of 5 instead of the default E-value cutoff, use:

>>> hits = next(cmsearch(trna, sequences, T=5))
>>> hits[0].score
12.06...

mypy should be able to detection which keywords can be passed to cmsearch using a TypedDict annotation.