To walk through the Toolchest workflow, we'll use the test tool, which mimics any other tool in Toolchest. test is part of Toolchest, so you can follow along on your own environment!

You'll need to pick an example input file and an output directory, which we'll call INPUT and OUTPUT_DIR, respectively. (For test, the example input file can be anything.)

If OUTPUT_DIR doesn't exist, Toolchest will create it for you as part of the run.

Example Workflow

First, import Toolchest and set your key:

import toolchest_client as toolchest
toolchest.set_key("YOUR_TOOLCHEST_KEY")

library(toolchest)
toolchest$set_key("YOUR_TOOLCHEST_KEY")

Next, set up the function call. For test, the call looks like this:

toolchest.test(
    inputs=INPUT,
    output_path=OUTPUT_DIR,
    tool_args="",
)

toolchest$test(
    inputs = INPUT,
    output_path = OUTPUT_DIR,
    tool_args = ""
)

All other tools' calls will look very similar to this, with slight differences. Most notably, inputs and output_path may be handled differently (as separate arguments, or referring to the output file path instead of the output directory). Check the tool-specific docs page for more details.

Once the function is called, you'll see something like this printed to the terminal:

Beginning Toolchest analysis run.
Processing tool_args as:
        (no tool_args set)
Found 1 files to upload.
Spawning job #1...
Uploading INPUT
Finished spawning jobs.
Running 1 job | Duration: 0:00:05 | 1 job uploading

The bottom line will live-update as the job runs. Once the job is complete, you'll see the following message, which also contains your custom run ID.

Checking output...

Your Toolchest run is complete! The run ID and output locations are included in the return.

If you need to re-download the results, run download(run_id="{YOUR_PRINTED_RUN_ID}") within 7 days

Output

After a successful test run, you'll find a new file called test_output.txt inside of OUTPUT_DIR that reads:

success

This is the tool's output file. For actual tools, every output file from the run will be downloaded to OUTPUT_DIR.

Function return

Each Toolchest function call also returns an object that contains the run ID and local locations of your downloaded files.

You can find these in the toolchest_output object after running the slightly modified call below:

toolchest_output = toolchest.test(
    inputs=INPUT,
    output_path=OUTPUT_DIR,
    tool_args="",
)

toolchest_output <- toolchest$test(
    inputs = INPUT,
    output_path = OUTPUT_DIR,
    tool_args = ""
)