GitHub

IgBLAST

A Julia package for running IgBLAST (v1.22.0) on immunoglobulin (Ig) and T cell receptor (TCR) sequences.

prepare builds BLAST databases, then runs your do block with an IgBLASTSession. The temporary databases are deleted when the block returns — the same resource pattern as mktempdir / open.

Installation

using Pkg
Pkg.add("IgBLAST")

Quick start

Binaries install automatically on first using IgBLAST.

using IgBLAST

dbs = VDJGermlines("V.fasta", "D.fasta", "J.fasta")
params = Dict("organism" => "human", "domain_system" => "imgt")

prepare(IgBLASTn, dbs; additional_params=params) do ig
    ig("query.fasta", "output.tsv")
end

# Gzip query and/or output (autodetected)
prepare(IgBLASTn, dbs; additional_params=params) do ig
    ig("query.fasta.gz", "output.tsv.gz")
end

# Custom auxiliary file
prepare(IgBLASTn, dbs; aux="human_gl.aux", additional_params=params) do ig
    ig("query.fasta", "output.tsv")
end

Timing the IgBLAST command

makeblastdb runs before the do block. For uncompressed files, command is NCBI IgBLAST writing a plain file:

seconds = prepare(IgBLASTn, dbs; additional_params=params, num_threads=8) do ig
    @elapsed run(command(ig, "query.fasta", "output.tsv"))
end

Do not use .gz paths here — gzip is Julia-side and would be included in the clock.

IgBLASTp

Only the V germline is used:

prepare(IgBLASTp, VGermlines("V_nucleotide.fasta");
        additional_params=Dict("organism" => "human")) do ig
    ig("query_protein.fasta", "output.tsv")
end

API

IgBLAST.IgBLAST — Module
IgBLAST

A Julia package for running IgBLAST analyses on immunoglobulin (Ig) and T cell receptor (TCR) sequences.

Prepare BLAST databases once with prepare, then run IgBLAST inside the do block. Temporary databases are deleted when the block returns.

Exports

  • install_igblast, is_igblast_installed
  • prepare, command, IgBLASTSession
  • AbstractIgBLAST, IgBLASTn, IgBLASTp
  • AbstractAuxiliary, NoAuxiliary, noauxiliary, AuxiliaryFile
  • AbstractGermlines, VGermlines, VDJGermlines, germlines_for

Examples

using IgBLAST

dbs = VDJGermlines("V.fasta", "D.fasta", "J.fasta")
params = Dict("organism" => "human", "domain_system" => "imgt")

prepare(IgBLASTn, dbs; additional_params=params) do ig
    ig("query.fasta", "out.tsv")
end

# Time only igblastn (plain files; databases already prepared)
t = prepare(IgBLASTn, dbs; additional_params=params) do ig
    @elapsed run(command(ig, "query.fasta", "out.tsv"))
end
source
IgBLAST.IgBLASTSession — Type
IgBLASTSession{T,DBs,A,E,N,O,D,W}

Prepared IgBLAST databases and run settings for variant T.

Created only inside prepare; BLAST databases live for the do block and are deleted when it returns. Call the session on a query/output path, or command to get the raw igblastn/igblastp Cmd.

source
IgBLAST.IgBLASTSession — Method
(session::IgBLASTSession)(query, output)

Run IgBLAST. Gzip query/output (.gz) is staged around the command; plain paths are passed through to IgBLAST unchanged.

source
IgBLAST.append_param — Method
append_param(cmd, key, value)

Append one IgBLAST CLI argument. An empty value is a flag (-key). Emptiness is string content, not a type, so it cannot be dispatched.

source
IgBLAST.build_command — Method
build_command(exe, query, dbs, aux, output, num_threads, outfmt, params)

Build an IgBLAST Cmd, dispatching on the prepared database kind.

source
IgBLAST.command — Method
command(session, query, output) -> Cmd

Build the IgBLAST command for uncompressed query and output paths.

This is the timing surface: run(command(ig, query, output)) is NCBI IgBLAST writing a plain file, with no gzip, progress monitor, or extra copies.

source
IgBLAST.executable — Method
executable(::Type{<:AbstractIgBLAST})

Return the IgBLAST executable basename for the given variant.

source
IgBLAST.executable_path — Method
executable_path(::Type{T}) where T <: AbstractIgBLAST

Absolute path to the IgBLAST executable for variant T.

source
IgBLAST.finalize_output — Method
finalize_output(igblast_path, user_output, ::GzipEncoding)

Compress IgBLAST's plain output into the user-requested gzip path.

source
IgBLAST.germlines_for — Method
germlines_for(::Type{IgBLASTn}, v, d, j)
germlines_for(::Type{IgBLASTp}, v)

Build the germline collection appropriate for the IgBLAST variant.

source
IgBLAST.install_igblast — Method
install_igblast(; kwargs...)

Install the IgBLAST binary artifact declared in Artifacts.toml via ensure_artifact_installed, then verify igblastn is present.

Keyword hooks (for testing):

  • already_installed
  • artifact_toml
  • ensure_fn
  • artifact_hash_fn
  • artifact_path_fn
source
IgBLAST.molecule — Method
molecule(::Type{<:AbstractIgBLAST})

Molecule kind required by germline databases for this variant.

source
IgBLAST.open_session — Method
open_session(f, ::Type{T}, germlines, aux, num_threads, outfmt, params)

Prepare databases and call f(session). aux is a concrete AbstractAuxiliary so the session type is known at compile time.

source
IgBLAST.prepare — Method
prepare(f, ::Type{T}, germlines; kwargs...)

Prepare BLAST databases, call f(session), then delete the temporary databases. Use do-block syntax:

prepare(IgBLASTn, VDJGermlines(v, d, j); additional_params=Dict("organism"=>"human")) do ig
    ig("query.fasta", "out.tsv")
end

Returns the value of f. Setup (makeblastdb) is outside the session body, so @elapsed ig(query, output) or @elapsed run(command(ig, query, output)) times only IgBLAST.

IgBLASTn requires VDJGermlines; IgBLASTp requires VGermlines.

Keywords

  • aux: NoAuxiliary (default), AuxiliaryFile, or a path string
  • num_threads: IgBLAST -num_threads (default Threads.nthreads())
  • outfmt: IgBLAST -outfmt (default 19 for IgBLASTn, 7 for IgBLASTp)
  • additional_params: extra CLI flags (Dict; empty value = flag)
source
IgBLAST.prepare_db — Method
prepare_db(makeblastdb, db_file, db_type, temp_dir, molecule)

Build a BLAST database in temp_dir. Returns the database prefix.

source
IgBLAST.source_fasta — Method
source_fasta(db_file, temp_dir, db_type, molecule)

FASTA path to feed makeblastdb, dispatching on molecule kind. Nucleotide germlines are used in place; protein germlines are translated.

source
IgBLAST.stage_query — Method
stage_query(input_file, output_file, ::GzipEncoding)

Decompress a gzip FASTA into output_file for IgBLAST.

source