Command-line Interface¶
The following is a list of the sub-commands contained in Surround’s CLI tool.
surround¶
The Surround Command Line Interface
usage: surround [-h] [-v]
{init,run,lint,store,config,experimentation,split,viz,data}
...
Named Arguments¶
-v, --version | Show the current version of Surround Default: False |
init¶
Initialize a new Surround project.
usage: surround init [-h] [-p PROJECT_NAME] [-d DESCRIPTION] [-w REQUIRE_WEB]
[path]
Positional Arguments¶
path | Path for creating a Surround project Default: “./” |
Named Arguments¶
-p, --project-name | |
Name of the project | |
-d, --description | |
A description for the project | |
-w, --require-web | |
Is web service required for the project |
run¶
Run a Surround project assembler and task.
Without any arguments, all tasks will be listed.
Assemblers are defined in the __main__.py
file of the current project. The default assembler that comes
with every project is called baseline
.
Tasks are defined in the dodo.py
file of the current project. Each project comes with a set of default tasks listed below.
Containerised Tasks:
build
- Build a Docker image for your Surround project.dev
- Run the specified assembler in a Docker container with the current source code (via drive mount, no build neccessary).prod
- Build the Docker image and run the specified assembler inside a container (no drive mounting).batch
- Run the specified assembler in a Docker container (mountinginput
andoutput
folders) set to batch mode.train
- Run the specified assembler in a Docker container (mountinginput
andoutput
folders) set to train mode.web
- Serve the specified assembler via HTTP endpoints inside a Docker container.remove
- Remove the Docker image built for this project (if any).jupyter
- Run a jupyter notebook server in a Docker container (mounting the whole project).
Local Tasks:
batchLocal
- Run the specified assembler locally set to batch-predict mode.trainLocal
- Run the specified assembler locally set to train mode.webLocal
- Serve the specified assembler via HTTP endpoints locally.
usage: surround run [-h] [task]
Positional Arguments¶
task | Task defined in dodo.py file of your project |
lint¶
Run the Surround Linter on the current project.
For more information on what this does, see linter.
usage: surround lint [-h] [-l | path]
Positional Arguments¶
path | Path for running the Surround linter Default: ./ |
Named Arguments¶
-l, --list | List all Surround checkers Default: False |
data¶
usage: surround data [-h] {create,inspect,lint} ...
subcommands¶
This tool must be called with one of the following commands
command | Possible choices: create, inspect, lint |
Sub-commands:¶
create¶
Create a data container from a file or directory
surround data create [-h] (-f FILE | -d DIRECTORY | -m) [-o OUTPUT]
[-e EXPORT_METADATA]
Named Arguments¶
-f, --file | Path to file to import into container |
-d, --directory | |
Path to directory to import into container | |
-m, --metadata-only | |
Generate metadata without a file system Default: False | |
-o, --output | Path to file to export container to (default: specified-path.data.zip) |
-e, --export-metadata | |
Path to JSON file to export metadata to |
inspect¶
Inspect the metadata and/or contents of a data container
surround data inspect [-h] [-m | -c] container_file
Positional Arguments¶
container_file | Path to the data container to inspect |
Named Arguments¶
-m, --metadata-only | |
Inspect the metadata of the container only Default: False | |
-c, --content-only | |
Inspect the contents of the container only Default: False |
lint¶
Check the validity of a data container
surround data lint [-h] [-l] [-c CHECK_ID] container_path
Positional Arguments¶
container_path | Path to the container to perform checks on |
Named Arguments¶
-l, --list | List the checks the linter will perform Default: False |
-c, --check-id | Specify a single check to perform (get id from –list) |
split¶
Tool to randomly split data into test, train, and validation sets.
Supports splitting:
- Directory of files
- CSV files
- Text files (just ensure you use the
--no-header
flag)
Example - Split a directory of images into train/test/validate:
$ surround split -d images -e png
Example - Reset a split directory:
$ surround spit --reset images
Example - Splitting and resetting a CSV file:
$ surround split -t test.csv
$ surround split --reset .
usage: surround split [-h] (-t TEXT_FILE | -d DIRECTORY | -r RESET)
[-e EXTENSION] [-tr TRAIN] [-te TEST] [-va VALIDATE]
[-nv] [-ns] [-nh]
Named Arguments¶
-t, --text-file | |
Split text file into train/test/validate sets | |
-d, --directory | |
Split directory into train/test/validate sets | |
-r, --reset | Path to directory containing train/test/validate folders to reset |
-e, --extension | |
File extension of the files to process (default: *) Default: “*” | |
-tr, --train | Percentage of files for training (default: 80%) Default: 80 |
-te, --test | Percentage of files for test (default: 10%) Default: 10 |
-va, --validate | |
Percentage of files for validate (default: 10%) Default: 10 | |
-nv, --no-validate | |
Don’t produce a validation set when splitting Default: False | |
-ns, --no-shuffle | |
Don’t randomise when splitting data Default: False | |
-nh, --no-header | |
Use this flag when the text file has no headers Default: False |