SUBSEQ.BIO
DOCS-UTILITY

Utility

Run small custom file-processing scripts against uploaded data, datasets, or previous outputs.

Overview

  • Converting, renaming, packaging, or summarizing files between jobs.
  • Running a lightweight Python or shell script before a downstream program.
  • Inspecting or reshaping result folders for scripted workflows.

Modes

ModeInput shapeWhen to use it
python_script
Run Python Script Default		 Consumes a folder or output set; useful for batches and pipeline handoffs. Run a user-supplied .py script and write any results under /outputs.
command
Run Shell Command		 Consumes a folder or output set; useful for batches and pipeline handoffs. Run one bash command and write any results under /outputs.

Canonical Job Configuration

These are the fields exposed by the default job configuration for utility. They are also returned by GET /api/v1/program/params?program=utility and submitted as the params JSON object to POST /api/v1/job/submit.

ParameterTypeModesWhat it does
script_file
Python Script		 Auxiliary file Run Python Script Choose the .py script to execute. Upload a folder if the script imports sibling modules or reads companion files. The script is mounted separately under /aux.
Required; Files: .py
command
Command		 Text Run Shell Command One bash command to run with /bin/bash -lc. Upload needed data under /inputs and write results under /outputs.
Required
output_path
Output Path		 Text Run Python Script Optional path relative to /outputs. If set, the job form passes it to the script as /outputs/<path>.
args
Arguments		 Repeatable group Run Python Script Optional argv values passed unchanged after the script and optional output path.
At most 26 item(s)
args.value
Value		 Text All modes --flag=value
Required
Advanced configuration fields
ParameterTypeModesWhat it does
argument_1
Argument 1		 Text Run Python Script Legacy optional argv value passed unchanged after the repeatable arguments.
argument_2
Argument 2		 Text Run Python Script Legacy optional argv value passed unchanged after Argument 1.
argument_3
Argument 3		 Text Run Python Script Optional argv value passed unchanged.
argument_4
Argument 4		 Text Run Python Script Optional argv value passed unchanged.

Outputs And Metrics

  • Whatever files the script writes for download, plus logs.
  • Utility does not define scientific metrics; any metrics come from the user's script.

Common Examples

  • Run a Python script that extracts selected FASTA records.
  • Zip or reorganize a result folder before downloading.
  • Create a small manifest or summary table from previous job outputs.

Example API params

{
  "mode": "command",
  "command": "printf hello > /outputs/result.txt"
}

Caveats

  • Keep scripts focused and reproducible.
  • Large custom analyses should become a proper program wrapper when they are used repeatedly.
  • Do not include secrets in scripts or uploaded files.

Advanced Submit

Advanced submit is still available for direct program arguments through POST /api/v1/job/submit-advanced. Prefer canonical configuration unless you need exact low-level arguments or are reproducing a known command line.

  • Advanced submit is natural for Utility because direct script and command arguments are the workflow.
  • Use the canonical script modes when you only need a single uploaded script or command bundle.
curl -X POST https://subseq.bio/api/v1/job/submit \
  -H "Authorization: Bearer <api_key>" \
  -F program=utility \
  -F 'params={"mode":"python_script","script_file":"main.py","arguments":""}'