Asset class specification
Overview
Section titled “Overview”An asset class describes a kind of asset, such as fasta or bowtie2_index. It lists the asset's seek keys: the files, folders, or values a user can look up (seek) in it. Each asset is an instance of one class, and each recipe builds assets of one class.
An asset class is a YAML file with these keys:
name: (REQUIRED) A string identifying the asset class.version: (REQUIRED) A semantic version string, like0.1.0.description: (REQUIRED, may benull) A string describing the asset class.seek_keys: (REQUIRED) A dictionary of seek key names and their definitions.serving_modes: (OPTIONAL) How a server offers assets of this class: a list offile,archive, ornone. Defaults to[file].
Example asset class
Section titled “Example asset class”name: fastaversion: 0.1.0description: Sequences in the FASTA format, indexed FASTA and chromosome sizes fileserving_modes: [file, archive]seek_keys: fasta: value: "{genome}.fa" type: file description: FASTA file fai: value: "{genome}.fa.fai" type: file description: FASTA index file chrom_sizes: value: "{genome}.chrom.sizes" type: file description: Chromosome sizes fileThe refgenie-registry repository has many real asset classes.
Details
Section titled “Details”Identifies the asset class. Recipes and assets refer to it by this name.
version
Section titled “version”Tells apart versions of a changing asset class. Refgenie rejects versions that are not valid semantic versions. When a recipe names a class without a version, refgenie uses the latest one.
description
Section titled “description”Free text describing the asset class and its seek keys.
seek_keys
Section titled “seek_keys”Each seek key has three keys:
type: one of the types below.value: a template that tells refgenie how to find the file or folder in a built asset.description: free text describing the seek key.
The type decides how value is used:
| Type | How refgenie finds it |
|---|---|
file | Each {...} in the template becomes a wildcard ({genome}.fa.gz becomes *.fa.gz). Exactly one file in the asset folder must match. |
prefix | The common prefix of all files in the asset folder, as for aligner indexes. The template is not used for matching. |
directory | A folder with exactly the name in value, inside the asset folder. |
string, json | A value, not a path. The building recipe sets it in custom_seek_keys. |
After a build, refgenie checks that every path seek key matches, so a missing or extra file is caught.
serving_modes
Section titled “serving_modes”Decides what staging creates and how clients download the asset. See Serving modes.
Managing asset classes
Section titled “Managing asset classes”refgenie asset-class listrefgenie asset-class add --source /path/to/asset_class.yamlrefgenie asset-class add --source https://example.com/asset_classes/my_asset.yamlrefgenie asset-class show fastarefgenie asset-class remove my_asset_classadd --force replaces an existing class with the same name and version. show and remove take --asset-class-version to choose a version; remove needs it when more than one version exists. An asset class that is used by an asset or a recipe cannot be removed.
Syncing a data channel registers all of its asset classes at once.