Controlled Vocabulary

CV Categories and CV Terms are the local vocabulary lists of your instance. A property or annotation is mapped to a CV Category to obtain its drop-down of allowed values.

For the bigger picture — and how these terms connect to official ontology terms — see the Vocabulary Management overview and the Ontologies page.

Adding a Vocabulary Term UI

• To add or modify a single term, go in the Vocabularies > Terms and Add Term
• To batch upload terms, go to the Vocabularies > Categories, open the category and use the Import Terms section at the top

Creating/Updating a vocabulary list

UI

The easiest way to add new Vocabularies or add new Terms is through the Admin interface.

Navigate to Vocaburalies -> Categories and Add category. On the form, enter the detail about the Category. At the bottom of the page, you can directly add the Term that will be part of this Category.

If you wish to modify an existing Category, navigate to that Category and use the form and Save.

Term renaming

Terms can be renamed using the admin interface. However, this will not update already stored values. e.g. if you change Mouse to Mus musculus, searching for musculus, will not list the Mouse items. The Update Term action available from the Term list page of the admin interface should be used for this.

CLI

Creating controlled vocabularies can be a tedious task when done through the admin interface. The alternative is the bulk creation through the commandline. For this we have two scripts, dealing with different file formats.

Both scripts are also used when creating a fresh installation and you can find their usage in the setup.sh, which is also a good reference.

Option 1. Yaml files

Create a fixture

See the files in labid-server/vocabularies/fixtures/*.yml. These files describe a Category and the related Terms. You can create or (copy and) update these files to add your own terms.

For example:

cp vocabularies/fixtures/currencies.yml vocabularies/fixture/currencies.extended.yml
# modify/extend vocabularies/fixture/currencies.extended.yml
# If you only added new terms
python scripts/management/load.py --lookup-field name --update --input vocabularies/fixture/currencies.extended.yml --current-username admin
# Or if its a completely new category
python scripts/management/load.py --input vocabularies/fixture/my_own_category.yml --current-username admin

load.py can load more than vocabulary terms

Notice the load.py can handle more than just vocabularies terms and is also used to populate a new database. Look around in the various */fixtures/*.yml files to get a feel of it.

Option 2. Text files

The txt files are a combination of some header lines, describing the Category followed by a tab delimited format listing the Terms. See labid-server/vocabularies/fixtures/*.txt for examples

This format can be loaded with:

# Make sure to activate your virtual environment. With the environment setup correctly, you can execute
python scripts/vocabularies/load_cv_terms.py --input vocabularies/fixture/currencies.extended.yml --user admin --update
# or, for creating a new one
python scripts/vocabularies/load_cv_terms.py --input vocabularies/fixture/my_own_category.yml --user admin --create