CLI Reference

This section documents all available CLI commands.

protein-detective COMMAND

Protein Detective CLI

Table of Contents

• --install-completion
• search
• retrieve
• filter
• powerfit
  • commands
  • run
  • report
  • fit-models
  • list-runs
• import-structures
• meta

Workflow:

• search: Search for candidate protein structures.
• retrieve: Retrieve structure files from AlphaFold and PDBe.
• filter: Filter structure files based on specified parameters.
• powerfit: PowerFit related commands

Utilities:

• meta: Generate a DuckDB metadata database for a Protein Detective session.
• import-structures: Import structures from a file or directory.
• --install-completion: Install shell completion for this application.

protein-detective --install-completion

protein-detective --install-completion [OPTIONS]

Install shell completion for this application.

This command generates and installs the completion script to the appropriate location for your shell. After installation, you may need to restart your shell or source your shell configuration file.

Parameters:

• --shell: Shell type for completion. If not specified, attempts to auto-detect current shell. [choices: zsh, bash, fish]
• --output, -o: Output path for the completion script. If not specified, uses shell-specific default.

protein-detective search

protein-detective search [OPTIONS] SESSION_DIR

Search for candidate protein structures.

• Searches for UniProt accessions, writes <session_dir>/uniprot.txt.
• If interaction partner seeds are given, searches for interaction partners. and adds partners to the list of UniProt accessions. Writes <session_dir>/interaction_partner_seeds.txt, <session_dir>/complexes.csv and <session_dir>/uniprot_with_interaction_partners.txt.
• Searches for AlphaFold structures for the UniProt accessions. Writes <session_dir>/alphafold.csv.
• Searches for PDBe structures for the UniProt accessions. Writes <session_dir>/pdbe.csv.
• Searches for PDBe validation quality reports for the found PDBe structures. Writes <session_dir>/pdbe-quality.json.
• Writes <session_dir>/ro-crate-metadata.json to keep track of used arguments and its output files.

Arguments:

• SESSION_DIR: RO-Crate session directory. [required]

UniProt sub-search:

• --taxon-id: NCBI Taxon ID to filter results by organism (for example 9606 for human).
• --reviewed, --no-reviewed: Whether to filter results by reviewed status (True for reviewed, False for unreviewed).
• --subcellular-location-uniprot: Subcellular location in UniProt format (for example "nucleus").
• --subcellular-location-go: Subcellular location in GO format. Can be a single GO term (for example, ["GO:0005634"]) or a collection of GO terms (for example, ["GO:0005634", "GO:0005737"]), which are searched with OR logic.
• --molecular-function-go: Molecular function in GO format. Can be a single GO term (for example, ["GO:0003674"]) or a collection of GO terms (for example, ["GO:0003674", "GO:0008150"]), which are searched with OR logic.
• --min-sequence-length: Minimum length of the canonical sequence.
• --max-sequence-length: Maximum length of the canonical sequence.
• --limit-uniprot: Maximum number of UniProt accessions to return. [default: 10000]

AlphaFold sub-search:

• --alphafold.limit: Maximum number of AlphaFold entries to return. Use '0' to skip the AlphaFold sub-search. [default: 10000]

PDBe sub-search:

• --pdbe.limit: Maximum number of PDBe entries to return. Use '0' to skip the PDBe sub-search. [default: 10000]
• --pdbe.min-residues: Minimum chain length for PDBe.
• --pdbe.max-residues: Maximum chain length for PDBe.
• --pdbe.top-resolution-per-uniprot-accession: Best-N PDBe per UniProt. [default: 5]

Interaction partners sub-search:

• --interaction.seed: UniProt ID to use as interaction partner seed. The search will be expanded to include structure identifiers of the found interaction partners. Can be specified multiple times. [default: {}]
• --interaction.exclude: UniProt ID to exclude as found interaction partners. Can be specified multiple times. [default: {}]
• --interaction.limit: Maximum number of interaction partners to return. [default: 10000]

Common:

• --verbose, -v: Increase verbosity (use multiple times for more detail). [default: 0]
• --quiet, -q: Decrease verbosity (use multiple times for less output). [default: 0]

protein-detective retrieve

protein-detective retrieve [OPTIONS] SESSION_DIR

Retrieve structure files from AlphaFold and PDBe.

Based on previously obtained search results.

Arguments:

• SESSION_DIR: The directory containing the search results. [required]

Parameters:

• --alphafold-db-version: The version of the AlphaFold database to use. [default: 6]

Cache:

• --no-cache: Disable caching of files to central location. [default: False]
• --cache-dir: Directory to use as cache for files. [default: /home/runner/.cache/protein-quest]
• --copy-method: How to make target file be same file as source file. By default uses hardlinks to save disk space. Note that hardlinks only work within the same filesystem and are harder to track. If you want to track cached files easily then use 'symlink'. On Windows you need developer mode or admin privileges to create symlinks. [choices: copy, symlink, hardlink] [default: hardlink]

Common:

• --verbose, -v: Increase verbosity (use multiple times for more detail). [default: 0]
• --quiet, -q: Decrease verbosity (use multiple times for less output). [default: 0]

protein-detective filter

protein-detective filter [OPTIONS] SESSION_DIR

Filter structure files based on specified parameters.

Steps:

1. Verify expected uniprot accessions are in structure files and inject uniprot accession if missing. See protein-quest convert structure --uniprots.
2. Convert PDBe structure files to single chain structure files. See protein-quest filter chain.
3. Filters processed PDBe structure files and AlphaFold structure files based on given parameters. See protein-quest filter combined.
4. If secondary structure options are given then filters passed structure files based on secondary structure. See protein-quest filter secondary-structure.

Arguments:

• SESSION_DIR: Directory where the structure files are located. [required]

Parameters:

• --min-confidence: Minimal confidence (plDDT) for AlphaFold structures to pass the filter. [default: 70.0]
• --min-residues: Min residues in chain A. [default: 0]
• --max-residues: Max residues in chain A. [default: 10000000]
• --min-geometry-quality: Minimal geometry quality score to pass the filter. [default: 50.0]
• --min-sequence-identity: Minimum sequence identity ratio to the Uniprot sequence for a structure to be passed. If not set then discards structures that are not fully identical to the Uniprot sequence. For example if set to 0.8 then structures that have sequence identity below 0.8 are discarded. [default: 1.0]
• --top-uniprot-cluster: Maximum number of files to keep for structures per cluster per Uniprot accession. Alphafold structures are excluded from this limit. [default: 1000]
• --top-non-uniprot: Maximum number of files to keep for structures without Uniprot accession. [default: 0]
• --scheduler-address: Address of the Dask scheduler to connect to. If not provided, will create a local cluster. If set to sequential will run tasks sequentially.

Secondary structure sub-filter:

• --secondary.abs-min-helix-residues: Minimum number of residues in helices (absolute).
• --secondary.abs-max-helix-residues: Maximum number of residues in helices (absolute).
• --secondary.abs-min-sheet-residues: Minimum number of residues in sheets (absolute).
• --secondary.abs-max-sheet-residues: Maximum number of residues in sheets (absolute).
• --secondary.ratio-min-helix-residues: Minimum helix residue ratio (fraction from 0 to 1).
• --secondary.ratio-max-helix-residues: Maximum helix residue ratio (fraction from 0 to 1).
• --secondary.ratio-min-sheet-residues: Minimum sheet residue ratio (fraction from 0 to 1).
• --secondary.ratio-max-sheet-residues: Maximum sheet residue ratio (fraction from 0 to 1).

Cache:

• --no-cache: Disable caching of files to central location. [default: False]
• --cache-dir: Directory to use as cache for files. [default: /home/runner/.cache/protein-quest]
• --copy-method: How to make target file be same file as source file. By default uses hardlinks to save disk space. Note that hardlinks only work within the same filesystem and are harder to track. If you want to track cached files easily then use 'symlink'. On Windows you need developer mode or admin privileges to create symlinks. [choices: copy, symlink, hardlink] [default: hardlink]

Common:

• --verbose, -v: Increase verbosity (use multiple times for more detail). [default: 0]
• --quiet, -q: Decrease verbosity (use multiple times for less output). [default: 0]

protein-detective powerfit

PowerFit related commands

protein-detective powerfit commands

protein-detective powerfit commands [OPTIONS] TARGET RESOLUTION SESSION_DIR

Generate PowerFit commands for structure files in the session directory.

See powerfit --help for more information on the available options.

Arguments:

• TARGET: Target density map to fit the model in. Data should either be in CCP4 or MRC format [required]
• RESOLUTION: Resolution of map in Angstrom [required]
• SESSION_DIR: Session directory for input and output [required]

Parameters:

• --powerfit-run-id: ID of the PowerFit run to use. If not provided, will autoincrement based on existing runs.
• --output: Output file path. If not specified, defaults to standard output.

PowerFit specific parameters:

• --angle: Rotational sampling density in degree. Increasing this number by a factor of 2 results in approximately 8 times more rotations sampled. [default: 10.0]
• --no-laplace: Do not use the Laplace pre-filter density data. [default: False]
• --no-core-weighted: Do not use core-weighted local cross-correlation score. [default: False]
• --no-resampling: Do not resample the density map. [default: False]
• --resampling-rate: Resampling rate compared to Nyquist. [default: 2.0]
• --no-trimming: Do not trim the density map. [default: False]
• --trimming-cutoff: Intensity cutoff to which the map will be trimmed. Default is 10 percent of maximum intensity.

Process parameters:

• --cpu: Use CPU for the intensive calculations. Otherwise off-loads to GPU. [default: False]
• --workers-per-gpu: Number of workers to run per GPU. [default: 1]
• --gpu-backend: Backend to use for GPU processing. [choices: opencl, cuda] [default: opencl]
• --nproc: Number of processors used during search. The number will be capped at the total number of available processors on your machine. [default: 1]
• --batch-size: GPU batch size to use. Use 0 to disable batching entirely, or a positive integer to force a specific batch size. Applies to GPU backends (CUDA/OpenCL). If set too high will cause out-of-memory errors. [default: 100]

Common:

• --verbose, -v: Increase verbosity (use multiple times for more detail). [default: 0]
• --quiet, -q: Decrease verbosity (use multiple times for less output). [default: 0]

protein-detective powerfit run

protein-detective powerfit run [OPTIONS] TARGET RESOLUTION SESSION_DIR

Run PowerFit on PDB files in the session directory and store results.

See powerfit --help for more information on the available options.

Unlike powerfit command, no cross-correlation map (lcc.mrc file) is generated. If you need the lcc.mrc file, use powerfit commands to generate the commands and run them manually.

Arguments:

• TARGET: Target density map to fit the model in. Data should either be in CCP4 or MRC format [required]
• RESOLUTION: Resolution of map in Angstrom [required]
• SESSION_DIR: Session directory for input and output [required]

Parameters:

• --powerfit-run-id: ID of the PowerFit run to use. If not provided, will autoincrement based on existing runs.

PowerFit specific parameters:

• --angle: Rotational sampling density in degree. Increasing this number by a factor of 2 results in approximately 8 times more rotations sampled. [default: 10.0]
• --no-laplace: Do not use the Laplace pre-filter density data. [default: False]
• --no-core-weighted: Do not use core-weighted local cross-correlation score. [default: False]
• --no-resampling: Do not resample the density map. [default: False]
• --resampling-rate: Resampling rate compared to Nyquist. [default: 2.0]
• --no-trimming: Do not trim the density map. [default: False]
• --trimming-cutoff: Intensity cutoff to which the map will be trimmed. Default is 10 percent of maximum intensity.

Process parameters:

• --cpu: Use CPU for the intensive calculations. Otherwise off-loads to GPU. [default: False]
• --workers-per-gpu: Number of workers to run per GPU. [default: 1]
• --gpu-backend: Backend to use for GPU processing. [choices: opencl, cuda] [default: opencl]
• --nproc: Number of processors used during search. The number will be capped at the total number of available processors on your machine. [default: 1]
• --batch-size: GPU batch size to use. Use 0 to disable batching entirely, or a positive integer to force a specific batch size. Applies to GPU backends (CUDA/OpenCL). If set too high will cause out-of-memory errors. [default: 100]
• --scheduler-address: Address of the Dask scheduler to use. Use sequential to run PowerFit sequentially without Dask cluster. If not provided, will create a local Dask cluster.

protein-detective powerfit report

protein-detective powerfit report [OPTIONS] SESSION_DIR

Generate a report of the best PowerFit solutions.

Arguments:

• SESSION_DIR: Session directory containing PowerFit results [required]

Parameters:

• --powerfit-run-id: ID of the PowerFit run to report on
• --top: Number of top solutions to report per structure. [default: 1]
• --no-group-by-structure: If absent, group solutions by structure. If present, top will be overall instead of per structure. [default: False]
• --output: Output file for solutions table. If set to '-' (default) will print to stdout.

protein-detective powerfit fit-models

protein-detective powerfit fit-models [OPTIONS] SESSION_DIR

Fit models to the best PowerFit solutions.

Arguments:

• SESSION_DIR: Session directory containing PowerFit results [required]

Parameters:

• --powerfit-run-id: ID of the PowerFit run to report on
• --top: Number of top solutions to fit per structure. [default: 1]
• --no-group-by-structure: If absent, group solutions by structure. If present, top will be overall instead of per structure. [default: False]
• --output: Output file for fitted models table. If set to '-' (default) will print to stdout.

protein-detective powerfit list-runs

protein-detective powerfit list-runs [OPTIONS] SESSION_DIR

List all PowerFit runs in the session directory.

Arguments:

• SESSION_DIR: Directory containing the session data. [required]

Parameters:

• --output: Comma separated output file for listing runs. If set to '-' (default) will print to stdout.

protein-detective import-structures

protein-detective import-structures [OPTIONS] STRUCTURES_DIR SESSION_DIR

Import structures from a file or directory.

Arguments:

• STRUCTURES_DIR: Directory containing structure files to import [required]
• SESSION_DIR: Session directory to store results [required]

Parameters:

• --copy-method: Method to use for importing files. If 'copy', files will be copied. If 'symlink', symbolic links will be created. If 'hardlink', hard links will be created (unavailable on Windows). [choices: copy, symlink, hardlink] [default: hardlink]
• --strict: Raise an error if structure files do not meet expected criteria (single chain A, single UniProt accession). Without this flag, files that do not meet these criteria are skipped with a warning. [default: False]

Common:

• --verbose, -v: Increase verbosity (use multiple times for more detail). [default: 0]
• --quiet, -q: Decrease verbosity (use multiple times for less output). [default: 0]

protein-detective meta

protein-detective meta [OPTIONS] SESSION_DIR

Generate a DuckDB metadata database for a Protein Detective session.

Arguments:

• SESSION_DIR: Session directory containing the files to include. [required]

Parameters:

• --powerfit-run-id: Optional PowerFit run ID used to restrict solutions.