tomato.ketchup package

ketchup: command line interface to tomato

Code author: Peter Kraus

Module of functions to interact with tomato. Includes job management functions:

submit() to submit a job to queue
status() to query the status of tomato’s pipelines, its queue, or a job
cancel() to cancel a queued or kill a running job
snapshot() to create an up-to-date FAIR data archive of a running job
search() to find a jobid of a job from jobname

Also includes sample/pipeline management functions:

load() to load a sample into a pipeline
eject() to remove any sample present in a pipeline
ready() to mark a pipeline as ready

Submodules

tomato.ketchup.functions.submit(args)

Job submission function. Usage:

ketchup [-t] [-v] [-q] submit <payload> [--jobname JOBNAME]

Attempts to open the yaml/json file specified in the <payload> argument, and submit it to tomato’s queue.

The supplied argparse.Namespace has to contain the path to the payload. Optional arguments include an optional --jobname/-j parameter for supplying a job name for the queue, the verbose/quiet switches (-v/-q) and the testing switch (-t).

Examples

>>> # Submit a job:
>>> ketchup submit .\dummy_random_2_0.1.yml
jobid: 2
jobname: null

>>> # Increased verbosity:
>>> ketchup -v submit .\dummy_random_2_0.1.yml
INFO:tomato.ketchup.functions:Output path not set. Setting output path to 'C:\[...]'
INFO:tomato.ketchup.functions:queueing 'payload' into 'queue'
INFO:tomato.dbhandler.sqlite:inserting a new job into 'state'
jobid: 4
jobname: null

>>> # With a job name:
>>> ketchup submit .\dummy_random_2_0.1.yml -j dummy_random_2_0.1
jobid: 5
jobname: dummy_random_2_0.1

Return type: None

tomato.ketchup.functions.status(args)

Job, queue and pipeline status query function. Usage:

ketchup [-t] [-v] [-q] status
ketchup [-t] [-v] [-q] status [queue|state]
ketchup [-t] [-v] [-q] status <jobid>

The argparse.Namespace has to contain the <jobid> the status of which is supposed to be queried. Alternatively, the status of the queue or state of tomato can be queried. Optional arguments include the verbose/ quiet switches (-v/-q) and the testing switch (-t).

Examples

>>> # Get pipeline status of tomato:
>>> ketchup status
pipeline             ready jobid  (PID)     sampleid
===================================================================
dummy-10             no    3      1035      dummy_sequential_1_0.05
dummy-5              no    None             None

>>> # Get queue status with queued & running jobs:
>>> ketchup status queue
jobid  status (PID)     pipeline
==========================================
3      r      1035      dummy-10
4      q

>>> # Get queue status with all jobs:
>>> ketchup -v status queue
jobid  jobname              status (PID)     pipeline
==============================================================
1      None                 c
2      custom_name          cd
3      None                 r      1035      dummy-10
4      other_name           q

Note

Calling ketchup status with a single jobid will return a yaml list, even though status of only one element was queried.

>>> # Get status of a given job
>>> ketchup status 1
- jobid: 1
  jobname: null
  status:  c
  submitted: 2022-06-02 06:49:00.578619+00:00
  executed: 2022-06-02 06:49:02.966775+00:00
  completed: 2022-06-02 06:49:08.229213+00:00

Return type: None

tomato.ketchup.functions.cancel(args)

Job cancellation function. Usage:

ketchup [-t] [-v] [-q] cancel <jobid>

The argparse.Namespace has to contain the <jobid> of the job to be cancelled. Optional arguments include the verbose/quiet switches (-v/-q) and the testing switch (-t).

Note

The cancel() only sets the status of the running job to rd; the actual job cancellation is performed in the tomato.daemon.main.main_loop().

Examples

>>> # Cancel a job:
>>> ketchup cancel 1

Warning

Cancelling a running job will generate a warning. Output FAIR data should be created as requested in the <payload>.

>>> # Cancel a running job:
>>> ketchup cancel 1
WARNING:tomato.ketchup.functions:cancelling a running job 1 with pid 17584

Note

Cancelling a completed job will do nothing.

Return type: None

tomato.ketchup.functions.load(args)

Load a sample into a pipeline. Usage:

ketchup [-t] [-v] [-q] load <samplename> <pipeline>

Assigns the sample with the provided samplename into the pipeline. Checks whether the pipeline exists and whether it is empty before loading sample.

Return type: None

tomato.ketchup.functions.eject(args)

Eject a sample into a pipeline. Usage:

ketchup [-t] [-v] [-q] eject <pipeline>

Marks the pipeline as empty. Checks whether the pipeline exists, and whether it is currently running.

Return type: None

tomato.ketchup.functions.ready(args)

Mark pipeline as ready. Usage:

ketchup [-t] [-v] [-q] ready <pipeline>

Marks the pipeline as ready. Checks whether the pipeline exists, and whether it is currently running.

tomato.ketchup.functions.snapshot(args)

Create a snapshot of job data. Usage:

ketchup [-t] [-v] [-q] snapshot <jobid>

Requests an up-to-date snapshot of the data of the job identified by jobid. Checks whether the job is running, raises a warning if job has been finished.

Examples

>>> # Create a snapshot in current working directory:
>>> ketchup snapshot 1
>>> ls
snapshot.1.json
snapshot.1.zip

Return type: None

tomato.ketchup.functions.search(args)

Search the queue for a job that matches a given jobname. Usage:

ketchup [-t] [-v] [-q] [-c] search <jobname>

Searches the queue for a job that matches the jobname, returns the job status and jobid. If the option -c/--complete is specified, the completed jobs will also be searched.

Examples

>>> # Create a snapshot in current working directory:
>>> ketchup submit .\dummy_random_2_0.1.yml -j dummy_random_2_0.1
>>> ketchup search dummy_random_2
- jobid: 1
  jobname: dummy_random_2_0.1
  status: r

Return type: None