Tbtools

TBtools

Overview

TBtools-II is a Java-based bioinformatics toolkit that runs on Windows and macOS. Prefer TBtools' own bundled Java/RPC/CLI tools. Do not introduce Python, R, Conda, or other dependencies unless the user explicitly asks.

Honor TBTOOLS_HOME or TBTOOLS_JAR if set; fall back to the platform default.

Setup

Windows (PowerShell)

$TbtoolsHome = if ($env:TBTOOLS_HOME) { $env:TBTOOLS_HOME } else { "C:\Program Files\TBtools" }
$TbtoolsJar = if ($env:TBTOOLS_JAR) { $env:TBTOOLS_JAR } else { Join-Path $TbtoolsHome "TBtools_JRE1.6.jar" }
$env:Path = "$(Join-Path $TbtoolsHome 'bin');$env:Path"

Test-Path $TbtoolsJar
java -version

macOS / Linux (bash)

TBTOOLS_HOME="${TBTOOLS_HOME:-/Applications/TBtools-II}"
TBTOOLS_JAR="${TBTOOLS_JAR:-$(find "$TBTOOLS_HOME" -name 'TBtools*.jar' -maxdepth 4 2>/dev/null | head -1)}"
export PATH="$TBTOOLS_HOME/bin:$PATH"

[ -f "$TBTOOLS_JAR" ] && echo "jar: $TBTOOLS_JAR" || echo "TBtools jar not found — set TBTOOLS_JAR"
java -version

Use bin/ (bin\ on Windows) tools directly when the task is a standard external tool workflow:

blastn -query query.fa -db db_prefix -out results.tsv -outfmt 6
muscle -in input.fa -out aligned.fa
iqtree -s aligned.fa -m MFP -bb 1000 -nt AUTO
diamond blastp -d proteins.dmnd -q query.fa -o matches.tsv

RPC Server

Windows (PowerShell)

.\scripts\start_rpc_server.ps1 -Background

Direct form:

java -cp $TbtoolsJar biocjava.rpc.RpcServer

macOS / Linux (bash)

java -cp "$TBTOOLS_JAR" biocjava.rpc.RpcServer &

Default URLs:

rpcPort is configurable in TBtools config. rpcBindAddress is normalized to loopback only (127.0.0.1 or ::1); do not expose the RPC server on 0.0.0.0.

RPC Helper

Windows (PowerShell)

function Invoke-TBtoolsRpc {
    param(
        [Parameter(Mandatory=$true)][string]$Method,
        [hashtable]$Params = @{},
        [string]$Uri = "http://127.0.0.1:8765/rpc",
        [int]$TimeoutSec = 600
    )

    $body = @{
        jsonrpc = "2.0"
        method = $Method
        params = $Params
        id = [guid]::NewGuid().ToString()
    } | ConvertTo-Json -Depth 50

    $response = Invoke-RestMethod -Method Post -Uri $Uri -ContentType "application/json" -Body $body -TimeoutSec $TimeoutSec
    if ($null -ne $response.error) {
        $reason = if ($response.error.data -and $response.error.data.reason) { " ($($response.error.data.reason))" } else { "" }
        throw "TBtools RPC error $($response.error.code): $($response.error.message)$reason"
    }
    return $response.result
}

macOS / Linux (bash + curl)

tbtools_rpc() {
    local method="$1"
    local params="${2:-{}}"
    local uri="${TBTOOLS_RPC_URI:-http://127.0.0.1:8765/rpc}"
    curl -s --max-time 600 -X POST "$uri" \
        -H "Content-Type: application/json" \
        -d "{\"jsonrpc\":\"2.0\",\"method\":\"$method\",\"params\":$params,\"id\":\"1\"}"
}

Discovery:

# Windows
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8765/health
Invoke-TBtoolsRpc -Method system.ping
$methods = (Invoke-TBtoolsRpc -Method system.listMethods).methods
$methods | Where-Object { $_ -like "*Fasta*" }
Invoke-TBtoolsRpc -Method system.describeMethod -Params @{ method = "FastaStat.process" }
Invoke-TBtoolsRpc -Method system.toolsJson

# macOS / Linux
curl -s http://127.0.0.1:8765/health
tbtools_rpc system.ping
tbtools_rpc system.listMethods | python3 -c "import sys,json; [print(m) for m in json.load(sys.stdin)['result']['methods']]"
tbtools_rpc system.describeMethod '{"method":"FastaStat.process"}'

RPC Workflow

1. Create deterministic workspace folders and pass absolute host-local file paths. RPC bodies carry paths, not file content.
2. Call system.listMethods and system.describeMethod for candidate methods. Use system.toolsJson when many method schemas are needed.
3. Prefer a matching *.validateParams or *.validateInput before *.process when available.
4. Treat validation failures carefully: validate methods may return result.ok = false / validated = false with structured errors instead of a JSON-RPC error.
5. For long BLAST, tree, heatmap, NCBI, or large file jobs, raise client timeout and reduce concurrency.
6. If JSON-RPC error -32603 has error.data.reason = rpc pool busy, back off and retry with lower concurrency.

RPC Protocol Notes

Common error codes: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32000 timeout.

Common RPC Methods

Examples

FASTA statistics (Windows PowerShell):

Invoke-TBtoolsRpc -Method FastaStat.process -Params @{
    inputPath = "D:/data/genome.fa"
    outputPath = "D:/data/out/genome_stat.xls"
    options = @{ getLengthOnly = $false }
}

FASTA statistics (macOS / Linux bash):

tbtools_rpc FastaStat.process \
  '{"inputPath":"/data/genome.fa","outputPath":"/data/out/genome_stat.xls","options":{"getLengthOnly":false}}'

Extract FASTA records with a prewritten ID list (Windows PowerShell):

Invoke-TBtoolsRpc -Method AmazingFastaExtract.process -Params @{
    inputPath = "D:/data/genome.fa"
    idListPath = "D:/data/ids.txt"
    outputPath = "D:/data/out/extracted.fa"
    options = @{
        usePattern = $false
        caseInsensitive = $true
        dontTreatSpaceAsColSep = $false
        wholeWordMatch = $false
    }
}

Validate then run a tree pipeline (Windows PowerShell):

$params = @{
    inputPath = "D:/data/sequences.fa"
    outputPath = "D:/data/out/tree"
    options = @{ ultraFastBS = $true; bbTime = 5000; model = "Auto"; threads = 2 }
}
$check = Invoke-TBtoolsRpc -Method OneStepBuildATree.validateParams -Params $params
if ($check.ok -eq $false -or $check.validated -eq $false) { $check.errors; throw "TBtools validation failed" }
Invoke-TBtoolsRpc -Method OneStepBuildATree.process -Params $params -TimeoutSec 7200

Validate then run a tree pipeline (macOS / Linux bash):

tbtools_rpc OneStepBuildATree.validateParams \
  '{"inputPath":"/data/sequences.fa","outputPath":"/data/out/tree","options":{"ultraFastBS":true,"bbTime":5000,"model":"Auto","threads":2}}'
tbtools_rpc OneStepBuildATree.process \
  '{"inputPath":"/data/sequences.fa","outputPath":"/data/out/tree","options":{"ultraFastBS":true,"bbTime":5000,"model":"Auto","threads":2}}'

Operating Rules

• Detect the platform first: use PowerShell helpers on Windows, bash + curl on macOS/Linux.
• Use TBtools bundled bin/ tools before suggesting external installs.
• Keep stderr/error details visible for external tools and RPC errors.
• Do not assume a method exists from memory; discover it through system.listMethods.
• Do not assume system.listMethods returns a raw array; the canonical result is an object with methods.
• Do not use Python helpers for normal TBtools work in this environment.
• Use forward-slash paths (/data/...) in RPC calls even on Windows — TBtools accepts them.