Skip to content

divbase-cli query

Run queries on the VCF files stored in the project's data store on DivBase. Queries are run on the DivBase API

Usage:

$ divbase-cli query [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • tsv: Query the tsv sidecar metadata file for...
  • vcf: Submit a VCF query to run on the DivBase API.
  • get-vcf-results: Wait for a 'divbase-cli query vcf' job to...

divbase-cli query tsv

Query the tsv sidecar metadata file for the VCF files in the project's data store on DivBase. Returns the sample IDs and filenames that match the query.

Usage:

$ divbase-cli query tsv [OPTIONS] TSV_FILTER

Arguments:

  • TSV_FILTER: String consisting of keys:values in the tsv file to filter on. The syntax is 'Key1:Value1,Value2;Key2:Value3,Value4', where the keys are the column header names in the tsv, and values are the column values. Multiple values for a key are separated by commas, and multiple keys are separated by semicolons. When multiple keys are provided, an intersect query will be performed. E.g. 'Area:West of Ireland,Northern Portugal;Sex:F'. [required]

Options:

  • --show-sample-results / --no-show-sample-results: Print sample_ID and Filename results from the query. [default: no-show-sample-results]
  • --metadata-tsv-name TEXT: Name of the sample metadata TSV file in the project's data store on DivBase. [default: sample_metadata.tsv]
  • -p, --project TEXT: Name of the DivBase project, if not provided uses the default in your DivBase config file
  • --help: Show this message and exit.

divbase-cli query vcf

Submit a VCF query to run on the DivBase API. A single, merged VCF file with the query results will be added to the project on success.

Exactly one sample-selection mode is required: --tsv-filter | --samples | --samples-file | --all-samples.

Usage:

$ divbase-cli query vcf [OPTIONS]

Options:

  • --tsv-filter TEXT: This option calculates the samples to filter the VCFs on based on a sample metadata query. String consisting of keys:values in the tsv file to filter on. The syntax is 'Key1:Value1,Value2;Key2:Value3,Value4', where the keys are the column header names in the tsv, and values are the column values. Multiple values for a key are separated by commas, and multiple keys are separated by semicolons. When multiple keys are provided, an intersect query will be performed. E.g. 'Area:West of Ireland,Northern Portugal;Sex:F'.

Mutually exclusive with --samples, --samples-file, and --all-samples. * --samples TEXT: Comma-separated list of sample IDs. Mutually exclusive with --tsv-filter, --samples-file, and --all-samples. * --samples-file FILE: Path to a UTF-8 text file with one sample ID per line. Blank lines and lines starting with # are ignored. Mutually exclusive with --tsv-filter, --samples, and --all-samples. * --all-samples: Use all samples in the project for the query. Mutually exclusive with --tsv-filter, --samples, and --samples-file. * --command TEXT: String consisting of the bcftools view command(s) to run. E.g. "view -r 21:15000000-25000000" or "view -s". The string cannot be empty; if you only want to subset on the selected samples, use: --command "view -s" [required] * --metadata-tsv-name TEXT: Name of the sample metadata TSV file in the project's data store on DivBase. [default: sample_metadata.tsv] * -p, --project TEXT: Name of the DivBase project, if not provided uses the default in your DivBase config file * --help: Show this message and exit.

divbase-cli query get-vcf-results

Wait for a 'divbase-cli query vcf' job to complete and download the results file when complete. Similar to running 'divbase-cli task-history id <TASK_ID>' but with the added benefit of polling for the terminal state of the job (SUCCESS/FAILED). Designed to be of particular use in scripts and other automated workflows. Error codes (e.g. for scripts): 0 — task succeeded and file downloaded; 1 — task failed; 2 — unsupported task type

Usage:

$ divbase-cli query get-vcf-results [OPTIONS] TASK_ID

Arguments:

  • TASK_ID: Task ID of the query job to poll for results from. [required]

Options:

  • -d, --download-dir TEXT: Directory to download the files to. If not provided, defaults to what you specified in your user config. If also not specified in your user config, downloads to the current directory. You can also specify "." to download to the current directory.
  • -p, --project TEXT: Name of the DivBase project, if not provided uses the default in your DivBase config file
  • --max-wait-mins INTEGER: Maximum number of minutes to poll for task completion. Must be between 1 and 600. [default: 120]
  • --help: Show this message and exit.