Intern:Terminology Editor

The Terminology Editor (also called Term Editor, formerly Feature Editor) has been implemented into 4D to manage and structure all terms (vocabularies) of the PANGAEA Terminology Catalogue.

This Wiki page summarizes the most important functions of the Terminology Editor and shall provide starting help for working with it. For more elaborate information, the documentation can be accessed here (work in progress document).

=The Terminology Editor window=

The Terminology Editor list tab
The list tab is the first window, when the terminology editor button is clicked on the side-bar.

It consists of four sections:
 * 1) Term entry window: Lists all details about the currently chosen term.
 * 2) Relation table: Lists all outgoing relations of the currently chosen term to other terms.
 * 3) Term list: List of all terms from a query-output or within a chosen ontology
 * 4) Hierarchy tree: Showing all “has broader term” relations. If synchronize-button is checked, currently selected term from the term list is shown.

The Terminology Editor search tab
The search tab of the term editor functions the same way as for tables like the dataset or parameter table. It allows more advanced searches, than the search slit in term list of the list tab.

The search results will then be displayed in the term list of the terminology editor window.

=Elements of a term entry=
 * ID = automatically assigned identifier within PANGAEA. Can not be changed.
 * Status = curational/review status of the term (default: pending)
 * Name = name of term
 * Abbreviation = abbreviation of term. Only assigned if commonly used.
 * Semantic ID = most commonly a uniform resource identifier (URI). Often, but not necessarily represents an URL (uniform resource locator) directing to a web-entry about the term
 * Web description = human-reabable web-entry (e.g. Wikipedia)
 * Description = short definition of the term, as understood within PANGAEA. Can contain own definitions by the team or foreign definitions (other ontologies, dictionaries, wikipedia etc.)
 * Comment = additional comments (e.g. short IDs, remarks for usage etc.)
 * Ontology = original ontology the feature comes from. A feature can only relate to one ontology.
 * Category = describes kind of term
 * Created = date of feature creation and responsible user
 * Updated = Date of update and responsible user

Remark on term category:

The default term category is "class", which should be used in most of the cases.

Other categories are: "quantity" (only for measurement quantities), "systematics" (for taxon names), "grammar" (taxon categories, e.g. "genus") "instance" (mainly used for tangible objects, e.g. specific devices) and "attributes" (characteristics of a term, e.g. "mesh-size" of a net)

=Looking up terms and relations=

Searching for terms
A simple search slit for searching is given in the term list of the terminology editor.

There are three search options to be chosen from the drop down list: The full text search within the term editor functions similar to the full text search of the PANGAEA website, but does not sort the terms according to their search score. In contrast to a "contains"-search, not every query element needs to be present and the order of tokens may vary. Please note, that the full-text search only searches within the term name.
 * "contains" (term name contains a string)
 * "begins with" (term name begins with a string)
 * "full text" (full text search to find tokens within term name)

To restrict the term selection to one ontology, choose an ontology from the terminology field. The whole list of terms will appear.

Use the category field, to filter for terms belonging to the categories class, instance, systematics, grammar, attribute or quantity.

As long as a selection is done in the terminology or category field, search queries will only be performed within this selection.

The advanced search can be accessed via the search-tab of the terminology editor. Query results will be displayed within the term list.

Alternatively, the advanced search or the search slit of the terminology catalogue can be used. The terminology catalogue offers a better overview of the search results and you can configurate the columns (=term entry fields) displayed. Moreover, the search results can be ordered by any column in ascending or descending order.

Browsing through the tree
The hierarchy tree displays all "has broader term"-relations of a selected term. Other relation types like "is synonym of" are not shown.

Instead of using the search function, the hierarchical tree can be used to find terms and display their relations.

You can search for a broader term (e.g. enzymes) and display it in the tree view. Expand the tree to have a look at the subclasses. This can be especially helpful, if the allocation of the term is known, but the complex term name is not.

The hierarchy tree is only updated by a selection from the term list, as long as the "synchronize lists"-box is checked.

If you want to freeze the tree, uncheck the box!

=Term annotation= Parameters can be annotated with terms from the term catalogue. The annotated terms and their synonyms as well as broader terms are added to the PANGAEA dataset search index.

The term annotation is crucial to improve the PANGAEA search (full text search and facetted search).

There are three possible ways to add terms from the terminology catalogue to a parameter:
 * Drag and drop a term from the editor to the parameter details list
 * Click "Add" in the parameter details list (choice window will open)
 * Select parameter(s) from the parameter table and choose "change terms" from the "list specials"

The "list specials" functionality is particularly useful, if many identical terms shall be added to or deleted from a selection of parameters.

Please note: A Drag&Drop from the term catalogue to a parameter term list is currently not possible.

=Creating and updating terms and relations= The following list helps you to identify, which term fields are required for term creation:
 * Mandatory
 * Term name
 * Ontology (drop down list)
 * Category (drop down list)
 * Recommended
 * Description
 * Setting a first relation (relation table)
 * Web description
 * Optional
 * Abbreviation
 * Comment
 * Semantic ID (only required, if term comes from external ontology not implemented into 4D)

Working in 4D
In case, that only few terms shall be created or updated, using the 4D interface is the fastest option.

Click on the "new"-button at the topright corner of the term editor, fill in the term entry fields and click on "save".

If desired, term relations can be set simultaneously by drag&drop of a term from the term list or the tree into the term relation table. The term entry window is frozen, while the "new"-button is checked, so you can search for terms to set the relation.

Please note: If no term relation is set during term creation, the term will automatically be assigned to the root node of the chosen terminology/ontology. The new term will apprear on the top of the term list after saving, so you can change the relation afterwards (e.g. if you prefer to use the hierarchy tree for setting relations).

Updating terms is as easy as creating a new one. Click on the "edit"-button at the topright corner of the term editor while a term is chosen, change the term entry fields and click on "save".

As for creating a new term, your can add new relations by drag&drop of a term from the term list or the tree into the term relation table. The relation type can be changed using the drop down list. Again, the term entry window is frozen, while the "edit"-button is checked. Do not forget to click "save" for keeping your changes.

Id the "edit"-box is unchecked instead of using the "safe"-button, the changes are discarded.

Term relations can also be set using the hierarchy tree. Any changes are immediately saved.

You can perform a drag&drop-action within the tree itself, or from the term list onto a term in the tree. Please note, that a drag&drop always creates a "has broader term"-relation and that the tree can only display this relation type. To change the relation type afterwards, use "edit" and change the type within the relation table.

The following shortcuts can be useful to create multiple relations:
 * Shift-key during term selection (list or tree): "from-until"-selection
 * Crtl-key during term selection (list or tree): select several single terms
 * Drag&drop within tree: Move term(s) from A to B (=delete old relation, create new relation)
 * Drag&drop from list to tree: Add term(s) to a term (=create broader term relation)
 * Drag&drop within tree + Alt-key: Copy term(s) to new location (=create another relation)

Working with import files
Working with import files allow a fast and automated upload of new features or an update of existing ones.

The style sheet for the import file can be found here. Import files can be prepared with Microsoft Excel or a comparable program. The final import file should be saved as Unicode Text File (i.e. tab seperated) using UTF-8 character encoding.

The import file upload function can be found in 4D under: Import --> Terms. (Ontology and Category need not be specified).

ID lists
Many columns within the import file work require IDs instead of names. All neccessary ID lists can be found below.

Creating terms
For creating new terms with per import file, please use the row headers in row 5 from the import form.

The mandatory fields are: "Term", "Root Term", "Master Term", "ID Terminology", "ID Category" and "IDTermstatus". Unnecessary fields can be left empty.

You can extend the table by adding the rows "Relation Type" and "ID Term" or "Term" (see row 27) in order to set first relations to existing terms. Otherwise, the new terms will be added to the root node of the terminology.

In case, that the import routine yields an error message, please check:
 * Did you use a tab-seperated text-file?
 * Did you use UTF-8 encoding (without BOM)?
 * Did you use the right headers?
 * Are there any special character, that could not be properly interpreted?
 * Have some terms been already created? If so: Do they look correct?

Term names within one terminology need to be unique. If terms from the import file already exist, the line will be skipped and there will be no alteration of the existing term.

Updating terms and relations
If many uniform changes have to be done to a list of terms or if many terms shall be related to a limited list of other terms, the usage of an import file may be advisable.

Please use the table headers in row 9 from the import form. The provision of term IDs is mandatory, because it indicates the system, that the terms are already existing and shall be changed. Otherwise, 4D assumes the intention of creating new terms.

4D will overwrite the term entry fields with text input from the import file. Empty import file fields are ignored, not deleted.

You can add new relations by adding the columns "relation type" and "ID term".

Please note: You can not use the import file to delete terms, term fields or relations.

Useful hint:

You can download a list of terms, that you want to change, using the term catalogue in 4D (export button). Then, you can modify the contents and reupload the file to 4D.