3.1.1. ID filters

The most important atomic filters are those that filter mappings based on the value of an ID field (e.g. subject_id, object_id, etc.).

For example, the following filter:

predicate==skos:exactMatch

will match any mapping whose predicate ID is http://www.w3.org/2004/02/skos/core#exactMatch.

Importantly, the value of an ID filter can only be specified as a CURIE. The use of full-length IRIs is not possible. However the actual comparison is always made after expansion, on the full-length IRIs.

The value of an ID filter may end with an asterisk (*), in which case the filter will match if the corresponding slot begins with the specified value. For example:

predicate==semapv:crossSpecies*

will match any mapping that has a predicate whose ID starts with https://w3id.org/semapv/vocab/crossSpecies (after expansion of the built-in semapv prefix name).

That logic holds when the asterisk represents the entire local part of the CURIE, as in:

predicate==skos:*

This will match any mapping with a predicate in the SKOS namespace (formally, any predicate whose ID starts with http://www.w3.org/2004/02/skos/core#).

3.1.2. Filters on free-form text slots

For the filters that act on slots that contain a free-form text value (rather than an identifier, a numerical value, or an enum value), the value to filter against must be specified in single or double quotes. For example:

mapping_tool=="mira"

This also applies, by exception, to the subject_type and object_type slots, because even though they are enum-typed, the values they accept (from the EntityType enum in the SSSOM specification) contain whitespaces.

As for filters on ID fields, the value of a free-form text filter may also end with an asterisk, to select mappings if the corresponding field starts with the requested value.

3.1.3. Filters on multi-valued slots

For the filters that act on multi-valued slots (e.g. creator_id, author_id, etc.), a mapping is considered to match if at least one of the values matches the specified pattern. For example:

creator==ORCID:*

Assuming the ORCID prefix name has been duly declared, this will match a mapping if the list of its creators’ identifiers contains at least one ORCID identifier. A mapping with no creator IDs or with only creator IDs of another type than ORCIDs will not match.

3.1.4. Filters on numeric slots

For the two filters that act on numeric slots (confidence and similarity_score), in addition to the equality operator (==), it is possible to use one of the following inequality operators: >, >=, <, and <=. They have the traditional meaning you could expect. For example:

confidence>=0.8

will match any mapping with a confidence value higher than or equal to 0.8.

3.1.5. Filtering on mapping predicate

The filter on mapping predicate (predicate==….) is a bit special in that it takes into account the predicate modifier of a mapping, if present, to determine whether the mapping is a match or not. If the predicate modifier Not (currently the only legal predicate modifier defined in the SSSOM specification) is present, then the mapping will not be a match for the filter even if its predicate does correspond to the pattern that the filter is looking for.

3.1.6. Filtering on cardinality

Whenever the mapping_cardinality== filter is used, the SSSOM/T execution engine normally takes care of ensuring that the mapping_cardinality slot of mappings has been filled with the effective cardinality values, computed on the entire set just before the filter is applied.

However, any use of the infer_cardinality function anywhere in the ruleset will disable that behaviour, because it is then assumed that the ruleset is taking responsibility for computing cardinality values as required.

In addition to the cardinality values specified in the SSSOM specification (1:1, 1:n, n:1, etc.), the cardinality filter accepts a joker value on either side of the : sign. For example:

mapping_cardinality==*:1

will select mappings with a cardinality of either 1:1 or n:1.

3.1.7. Filtering on empty values

For most slots, it is possible to select mappings that do not have a value in the slot.

For all free-form text slots, this is done simply by using an empty string as the value of the filter, as in:

mapping_tool==""

That syntax is also accepted for the filters on subject_type and object_type.

When combined with a negation operator (see below), this can be used to select mappings that have any non-null value in the slot:

!mapping_tool==""

Note that this is different from using the * special value, which will accept any mapping regardless of whether they have a value or not in the slot.

For slots that expects identifiers, selecting mappings with an empty value is done by using the special value ~, as in:

author==~

That syntax is also accepted by the filters on numeric slots and on mapping_cardinality.

3.1.8. Function filters

Lastly, an atomic filter may also take the form of a call to a filter function. See the corresponding section for a list of filter functions available in the base SSSOM/T language. SSSOM/T dialects may also add their own filter functions.

6.1.1. set_var

This directive allows to define an additional placeholder name (also called a variable) that can later be used in function arguments. It expects two arguments: the name of the placeholder, and its value.

For example:

set_var("MY_VARIABLE", "its value");

defines a placeholder named MY_VARIABLE and assigns to it the value its value.

That placeholder can then be used in an argument to a function (assuming the function allows the use of placeholders generally) as any other placeholder, for example:

my_function("My variable has the value %{MY_VARIABLE}");

6.2.1. is_duplicate

This filter can be used to select mappings for which a mapping-derived value is the same as for a previous mapping. It expects one argument, which is the mapping-derived value to check against.

Whenever it is called on a given mapping, the filter obtains derives the corresponding value and records it. If the value has not been seen before, it returns false; otherwise, it returns true.

Examples:

is_duplicate(%{subject_id}) -> stop();

This will drop all mappings that have the same subject_id, except the first one.

The mapping-derived value may be more complex, as in this example:

is_duplicate("%{subject_id}%{predicate_id}%{object_id}") -> stop();

which will drop all mappings that have the same subject / object / predicate triple (again, except the first such mapping).

Use the filter with the special hash substitution to drop mappings that are completely identical:

is_duplicate(%{hash}) -> stop();

6.2.2 has_extension

This filter can be used to select mappings that have a particular extension slot. It expects one argument, which is the property associated with the extension slot whose existence must be checked.

Example:

has_extension(PROP:fooProperty) -> stop();

6.3.1. set_var

This is in fact the same function as the set_var directive above, except in a different context.

When called as the ACTION part of a rule (after a filter), it will assign a new value to the variable, only for the mappings that are selected by the corresponding filter.

For example:

predicate==skos:broadMatch -> set_var("MY_VARIABLE", "value for broad matches");

The variable MY_VARIABLE will have the value value for broad matches, only for the mappings that have a skos:broadMatch predicate. For all other mappings, the variable will retain the value that was originally declared in the set_var directive.

Of note, it is forbidden to use set_var to assign a mapping-dependent value to a variable that has not been previously declared in a set_var directive at the beginning of the ruleset.

6.3.2. infer_cardinality

This function computes the cardinality and fills the mapping_cardinality slot for all the mappings it is applied to. It accepts optional arguments, which are the mapping slots to use to define the scope that cardinality will be relative to. With no arguments, cardinality will be relative to all the mappings the function is applied to.

For example, to compute the cardinality relative to the entire set (function applied to all mappings, no scope):

predicate==* -> infer_cardinality();

To compute the cardinality on the entire set, but relatively to all mappings that have the same predicate and the same object source:

predicate==* -> infer_cardinality("predicate_id", "object_source");

6.4.1. stop

This function indicates that the mapping to which it is applied should be excluded from any remaining rules. Basically, once this function has been applied to a mapping, it is as if the mapping was removed from the mapping set for the rest of the ruleset.

The function does not take any argument.

6.4.2. invert

This function inverts the current mapping, so that the subject becomes the object and vice-versa. It takes an optional argument, which is the predicate to use for the inverted mapping. The argument may contain placeholders.

If no argument is given, the function will try inverting the mapping using some built-in knowledge about which predicates are invertible; if it fails (because the original predicate has no known inverse predicate), the mapping will be excluded from any further processing (as if it has been the target of the stop function).

See the SSSOM documentation for details about mapping inversion.

Example:

!justification===semapv:ManualMappingCuration -> stop();
subject==CL:* -> invert();

The first rule will drop all mappings that do not come from a manual curation process. The second rule (which, consequently, will only ever apply to manually curated mappings) inverts all mappings that have a subject in the CL namespace. After those two rules, the mapping set only contains manually curated mappings, and no mapping can have a CL subject (since the mappings that did were either inverted, or dropped if they could not be inverted).

Note that, on their own, these two rules are equivalent to this single one:

justification==semapv:ManualMappingCuration && subject==CL:* -> invert();

which inverts all manually curated mappings that have a CL subject. The difference lies in what may happen next: in the second case, mappings that are not manually curated are still present in the set – they have been excluded from the invert() rule, but not removed, so they will be seen be any rule that may follow.

6.4.3. assign

This function allows to modify the selected mapping by assigning a value to a given slot. It takes at least two arguments:

• the name of the slot to modify;
• the value to assign to that slot.

The second argument:

• may contain placeholders;
• may be an empty string, to indicate that the slot should have no value (any existing value for that slot would then be removed);
• may contain several values separated by a pipe character (|), when assigning a value to a multi-valued slot.

It is possible to modify more than one slots in a single call to assign() by adding extra arguments. Each supplementary pair of arguments should follow the same rules as the first pair (so, the third argument is the name of the second slot to modify, the fourth argument is the value to assign to that slot, and so on).

Examples:

This rule will modify any mapping that uses a oboInOwl:hasDbXref predicate to make it use a skos:exactMatch predicate instead:

predicate==oboInOwl:hasDbXref -> assign("predicate_id", skos:exactMatch);

This rule will add to any mapping a (somewhat useless!) comment that basically states in plain English what the mapping is about:

predicate==* -> assign("comment", "Mapping between '%{subject_label}' and '%{object_label}'");

6.4.4. replace

This function allows to modify the selected mapping by performing a search-and-replace operation within the value of a slot. It takes at least three arguments:

• the name of the slot to modify;
• the regular expression pattern to find within the value of that slot;
• the string to replaced the pattern with.

Currently, that function is only available for slots whose values are either strings or list-of-strings (including entity references).

As for the assign function, it is possible to modify more than one slot in a single call by adding extra triplets of arguments.

Example: The following rule shows how to use the replace() function to fix a bogus IRI prefix:

predicate==* -> replace("object_id", "https://meshb.nlm.nih.gov/record/ui[?]ui=", "http://id.nlm.nih.gov/mesh/");

Any object ID with a IRI starting with https://meshb.nlm.nih.gov/record/ui?ui= will be renamed so that its IRI starts with http://id.nlm.nih.gov/mesh/ instead. Note how the ? character in the original IRI prefix had to be escaped, since that character has a special meaning in regular expressions.

6.5.1. short

The short format modifier does not take any argument. It attempts to condense its input (which is expected to be a full-length IRI) into a short identifier or CURIE, based on the prefix declarations in the SSSOM/T ruleset.

For example, to insert the short form of the current mapping’s predicate ID:

"The predicate is %{predicate_id|short}."

When used on a multi-valued slot, the short modifier will attempt to shorten all items in the list. For example, to insert the (short) IDs of all the authors of a mapping:

"Authored by: %{author_id|short}."

6.5.2. list_item

The list_item modifier works specifically on multi-valued slots. It accepts an argument which is the 1-based index of an item in the list of values in the multi-valued slot, and produces the value of that item.

For example, to insert the ID of only the first author of a mapping:

"First author: %{author_id|list_item(1)}."

Likewise, but to insert the ID in its short form, by combining with the short modifier:

"First author: %{author_id|list_item(1)|short}."

6.5.3. flatten

This is another modifier that works specifically on multi-valued slots. It transforms a list of values into a single string. It accepts up to the three arguments, all optional:

• the separator to insert between each value (by default , );
• the string to insert at the beginning of the list (by default an empty string);
• the string to insert at the end of the list (also an empty string by default).

For example, to insert the list of author IDs as a semicolon-separated list enclosed in parentheses:

"Authors: %{author_id|flatten('; ', '(', ')')}."

Likewise, but with shortened IDs:

"Authors: %{author_id|short|flatten(';', '(', ')')}."

Note in that example that the short modifier must be used before the flatten modifier, since the output of the flatten modifier is a string that no longer looks like a IRI and therefore cannot be shortened; the IDs must be shortened first, and then the list of (shortened) IDs can be flattened into a string.

6.5.4. format

This modifier allows to apply arbitrary formatting to a value. It expects a single argument which should a a format string as expected by Java’s String.format() method and containing a single format specifier, which will be replaced by the value the modifier is applied to.

For example, to apply a custom formatting to the double-typed confidence slot, you could use something like:

"Confidence: %{confidence|format('%.03f')}"

6.5.5. default

This modifier allows to specify a default value to insert into a string if the original substituted value is null or empty.

For example, to insert the name of the mapping tool used to create the current mapping, or a default string indicating that the tool is unknown:

"Mapping tool: %{mapping_tool|default('unknown tool')}"