local-cd-search

A command-line tool for local protein domain annotation using NCBI's Conserved Domain Database (CDD).

Background

NCBI CD-Search is a widely used tool for functional annotation of proteins. It uses RPS-BLAST to search protein sequences against position-specific scoring matrices (PSSMs) from the CDD database. PSSMs offer higher sensitivity for detecting distant homologs than searches against individual protein sequences, while remaining substantially faster than HMM-based annotation.

While the CD-Search web interface is convenient for small queries, it is not well suited for large-scale annotation. local-cd-search enables local protein annotation and automates the entire workflow: downloading PSSM databases from CDD, running RPS-BLAST, post-processing results with rpsbproc to filter hits using CDD's curated bit-score thresholds.

Installation

The easiest way to install local-cd-search is with Pixi, which will manage dependencies automatically and make local-cd-search available for execution from anywhere.

pixi global install -c conda-forge -c bioconda local-cd-search

Alternatively, you can install it from PyPI. In this case, rpsblast and rpsbproc must be installed separately. To install local-cd-search from PyPI using uv, run:

uv tool install local-cd-search

Quick start

Download PSSM databases

Download the full CDD database, which is a collection of six individual databases (see table below):

local-cd-search download database cdd

Or download individual databases. For example:

# COG database
local-cd-search download database cog

# Multiple databases
local-cd-search download database cog pfam tigr

The databases available for download are:

Annotate proteins

To run annotation on a FASTA file of protein sequences (in this example, proteins.faa) and save results to results.tsv, run the following command:

local-cd-search annotate proteins.faa results.tsv database

The local-cd-search will automatically detect which databases are available and will them for annotation.

Output

The output of local-cd-search annotate is a tab-separated file with hits filtered by CDD's curated bit-score thresholds. The following columns are included:

hit_type

• Specific: The top-ranking RPS-BLAST hit (compared to other hits in overlapping intervals) that meets or exceeds a domain-specific E-value threshold. It represents a very high confidence that the query sequence belongs to the same protein family as the sequences used to create the domain model.
• Non-specific: Hits that meet or exceed the RPS-BLAST threshold for statistical significance (default E-value cutoff of 0.01).
• Superfamily: The domain cluster to which the specific and/or non-specific hits belong. This is a set of conserved domain models that generate overlapping annotation on the same protein sequences and are assumed to represent evolutionarily related domains.

incomplete

Indicates if there are more than 20% missing from the N- or C- terminal compared to the original domain. Possible values are:

• -: No more than 20% shorter on either terminals.
• N: N-terminal has 20% or more missing.
• C: C-terminal has 20% or more missing.
• NC: Both terminals have 20% or more missing.

Functional sites output

If --sites-output is specified, an additional tab-separated file is created with functional site annotations. The following columns are included:

Usage

download subcommand

local-cd-search download [OPTIONS] DB_DIR DATABASE...

annotate subcommand

local-cd-search annotate [OPTIONS] INPUT_FILE OUTPUT_FILE DB_DIR