This document describes the command-line interface (CLI) as a development reference and to track implementation status.
We use symbols to indicate the status of implementation (see table below). For planned or in-progress work, we might include signatures, docstrings, and pseudocode to clarify the design. Once the interface is implemented, these are replaced by links to the reference documentation.
| Status | Description |
|---|---|
| Interface that has been implemented. | |
| Interface that is currently being worked on. | |
| Interface that is planned, but isn’t being worked on currently. |
seedcase-sproutseedcase-sprout has the following signature:
When used on its own, seedcase-sprout shows the help message as a shorthand for --help:
As a convenience, we provide the command sprout as a shorthand for seedcase-sprout. It can be used in place of seedcase-sprout in all instances.
seedcase-sprout has several commands: extract-metadata, init-metadata, build-metadata, and build-resources. These commands are described below.
extract-metadataThe extract-metadata command extracts metadata from a Parquet file and outputs a Python script with the ResourceProperties() dataclass filled in with the extracted metadata. It is meant to be used with Parquet files in the staging/ directory that have the same schema (columns and data types) as the final resource. It has the signature:
flowchart LR
parquet[/"Parquet path<br>[PARQUET-PATH]"/]
output_opt[/"Output path<br>[--output]"/]
extract["extract-metadata"]
output[/"Python script<br>[File]"/]
parquet --> extract
output_opt --> extract
extract --> output
extract-metadata command.
init-metadataThe init-metadata command creates a Python script with metadata fields that haven’t been filled in yet. It creates a Python script with empty *Properties() dataclasses. It has the signature:
The output-path is the path to the file that will be created (e.g. package_properties.py or resource1_properties.py) so that there is full flexibility and control about where and what name the file will have. The --type determines whether to make a file with metadata for the package overall (top-level metadata) or for a resource file. The default is the package overall.
Unlike extract-metadata when --type is resource, the output is a Python script with a ResourceProperties() class listing all fields but nothing filled in yet (all commented out). For resource metadata, the script will have be manually imported into the package metadata file (since the PackageProperties() contains a field for the ResourceProperties()).
flowchart LR
output_path[/"Path<br>[OUTPUT-PATH]"/]
type[/"Metadata type<br>[TYPE]"/]
init["init-metadata"]
output[/"Python script<br>[File]"/]
output_path --> init
type --> init
init --> output
init-metadata command.
build-resourcesThe build-resources command converts a set of “staging” Parquet files and converts them into the final resources, along with other additional functionality (described below). It has the signature:
The PROJECT-DIR defaults to the current working directory. While setting the --config-file is optional, the file itself is required. Because converting staging Parquet files into the final resources is a bit complex, this file is used to ensure a reproducible build with clear instructions on what files go into what resource. If the --config-file argument is not set, build-resources and will look in this order for these files:
.config/sprout.tomlsprout.toml or .sprout.tomlpyproject.toml (under [tool.sprout.*])The configurations for the build-resources command are under the [build-resources] table. This contains a field and a sub-table:
delete-obs-units-file for a csv file with a list of “observational units” to exclude/delete from the final resources (this is for legal and privacy compliance). The filepath is relative to the data package root. The file must contain the column name or names that have the IDs for the observational unit and the value(s) to exclude. The column(s) should be the base unit used across all resources that represents entity of interest. For example, the participant ID for the person who has had their data collected for the research study. In order for the deletion to work correctly for all resources, the given units’ columns must also be present in order for the unit to be removed.resources is a list of tables with the resource name, the directory where the staging Parquet files are kept in input-dir, and the final output directory where the new, e.g. <resource-name>.parquet file will be created with output-dir. The name field is used in place of <resource-name>. To allow for additional extensions, there is also a (for now) placeholder extras field.``toml {.filename="sprout.toml"} # While top level for Sprout, is also needed forbuild-resources`. metadata-file = “”
[build-resources] delete-obs-units-file = “”
[[build-resources.resources]] name = “demographics” input-dir = “staging/demographics/” output-dir = “resources/” # E.g. for making partition or for storing images. extras = {…}
[[build-resource.resources]] name = “blood” input-dir = “staging/blood/” output-dir = “resources/”
For the `units-file`, it should be in a [tidy format](inputs.qmd). It might look
something like:
```text
participant_id,date_id
1,2020-01-01
1,2020-06-01
2,2020-12-31flowchart LR
config_file[/"Configuration file<br>with build instructions<br>[--config-file]"/]
project_dir[/"Project directory<br>[PROJECT-DIR]"/]
build_resources["build-resources"]
output[/"Resource files<br>[Parquet]"/]
config_file & project_dir --> build_resources
build_resources --> output
build-resources command.