CLOCQ API

For the given input string disambiguate KB-items and retrieve relevant KB-facts from Wikidata. Parameters essentially control the number of disambiguations per question word (k), and the amount of potentially noisier KB-facts (p).

- `question`:

the input string you want to get relevant Wikidata facts for.

- `k` - optional (default="AUTO"):

the number of disambiguations per question word. "AUTO" would set an individual k for each question word, based on a heuristic ambiguity measurement (default setting).

- `p` - optional (default=1000):

threshold that controls the amount of potentially noisier facts per disambiguated KB-item. Specifically, we divide the facts of a KB-item x into facts with [1] x as subject, [2] x as object, or [3] x as qualifier-object. If the total number of facts in [2]+[3] is higher than p, we consider only the facts in [1]. Otherwise, all facts are considered (i.e. [1]+[2]+[3]). This follows the intuition that facts with the KB-item in the subject position are more salient. p should not be misunderstood as a strict pruning threshold on the facts (i.e. if p=100, there may still be more than 100 facts in the result).

- `include_labels` - optional (default=True):

controls whether the items in the facts are represented as plain Wikidata IDs, or a dictionary with "id" and "label".

- `question`:

the input string you want to get relevant Wikidata facts for.

- `parameters` - optional (default: default parameters of CLOCQ):

the parameters of CLOCQ. You can add whatever parameters you would like to change. For parameters that are not included, the default value will be used. Is a dict with keys:

- `k` (default="AUTO"): the number of disambiguations per question word. "AUTO" would set an individual k for each question word, based on a heuristic ambiguity measurement (default setting).
- `p_setting` (default=1000): threshold that controls the amount of potentially noisier facts per disambiguated KB-item. Specifically, we divide the facts of a KB-item x into facts with [1] x as subject, [2] x as object, or [3] x as qualifier-object. If the total number of facts in [2]+[3] is higher than p, we consider only the facts in [1]. Otherwise, all facts are considered (i.e. [1]+[2]+[3]). This follows the intuition that facts with the KB-item in the subject position are more salient. p should not be misunderstood as a strict pruning threshold on the facts (i.e. if p=100, there may still be more than 100 facts in the result).
- `h_match` (default=0.4): impact of matching similarity on disambiguations.
- `h_rel` (default=0.3): impact of question relevance on disambiguations.
- `h_conn` (default=0.2): impact of item-item connectivity on disambiguations.
- `h_coh` (default=0.1): impact of item-item coherence on disambiguations.
- `d` (default=20): list depth to be considered per question word.
- `bm25_limit` (default=False): amount of total output facts, as scored by BM25. `False` will deactivate BM25 scoring.

- `include_labels` - optional (default=True):

controls whether the items in the facts are represented as plain Wikidata IDs, or a dictionary with "id" and "label".

- `kb_item_tuple`:

list of disambiguations with keys "item" (dictionary with "id" and "label"), "question_word" (KB-item mention in input text), "rank" (number) and "score" (float).

- `search_space`:

list of KB-facts. Each KB-fact is represented as a list of KB-items (dictionary with "id" and "label").

For the given KB-item, retrieve the KB-facts in which the item occurs from Wikidata.

- `item`:

the input KB-item, for which the KB-facts should be retrieved. Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

- `p` - optional (default=1000):

threshold that controls the amount of potentially noisier facts per disambiguated KB-item. Specifically, we divide the facts of a KB-item x into facts with [1] x as subject, [2] x as object, or [3] x as qualifier-object. If the total number of facts in [2]+[3] is higher than p, we consider only the facts in [1]. Otherwise, all facts are considered (i.e. [1]+[2]+[3]). This follows the intuition that facts with the KB-item in the subject position are more salient. p should not be misunderstood as a strict pruning threshold on the facts (i.e. if p=100, there may still be more than 100 facts in the result).

- `include_labels` - optional (default=True):

controls whether the items in the facts are represented as plain Wikidata IDs, or a dictionary with "id" and "label".

A list of KB-facts. Each KB-fact is represented as a list of KB-items.

For the given question, link the entity mentions to entities in the KB. The method was designed for the SMART 2022 Task, and the code for training the model on the SMART 2022 data can be found here.

- `item`:

the input question (or string), for which the entities should be linked.

- `k` - optional (default="AUTO"):

the number of entity linkings per mention. "AUTO" would set an individual k for each mention, based on a heuristic ambiguity measurement (default setting).

A dictionary with keys "linkings" and "mentions". We return the list of "linkings", each having the KB-item (dictionary with "id" and "label") and the mention the entity was linked for. In the list for the "mentions" key, the generated strings by the sequence-to-sequence model are stored. Note, that the mentions for the individual linkings may match with the generated mentions only partially.

For the given question, link the relation mentions to relations in the KB. The method was designed for the SMART 2022 Task. Unlike for the entity linking, no training is involved here. - `item`:

the input question (or string), for which the relations should be linked.

- `top_ranked` - optional (default=True):

whether only the top-ranked relation per mention should be returned or not. If this parameter is set to `False`, multiple relations found relevant for the respective mention will be returned (improves recall, but hurts precision).

A dictionary with keys "linkings" and "mentions". We return the list of "linkings", each having the KB-item (dictionary with "id" and "label") and the mention the relation was linked for. Here, the "mentions" key holds the union of all relation mentions that are linked in the "linkings" list.

Retrieve the English label for the given KB-item.

- `item`:

the input KB-item, for which the label should be retrieved.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A string.

Retrieve the English aliases for the given KB-item, in case there are any.

- `item`:

the input KB-item, for which the aliases should be retrieved.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A list of strings.

Retrieve the English description for the given KB-item, in case there is one.

- `item`:

the input KB-item, for which the description should be retrieved.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A string.

Retrieve the types for the given KB-item. For humans, in addition to the "human" type, the occupations are added (similar as in other KBs).

- `item`:

the input KB-item, for which the types should be retrieved.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A list of KB-items (the types), that are represented as dictionaries with keys "id" and "label".

Retrieves only the most frequent type for the given KB-item. This is a proxy of the most prominent type which was present in Freebase.

- `item`:

the input KB-item, for which the type should be retrieved.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A single KB-item (the type), that is represented as a dictionary with keys "id" and "label".

Returns the frequency of the KB-item. The result is separated into two parts: 1) frequency of the KB-item appearing in the subject position of a fact, frequency of the KB-item appearing in non-subject positions in a fact (e.g. object or qualifier-object).

- `item`:

the input KB-item, for which the connectivity should be computed.
Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

List of two positive integers.

Computes the KB-distance between the two KB-items. The KB-distance is defined as in the paper, i.e. two KB-items are within 1-hop if they appear in the same KB-fact. Returns either 0 (no connection within 2-hops), 0.5 (connection in 2 hops), or 1 (connection within 1-hop). The order of KB-items does not matter.

- `item1`:

the first KB-item. Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

- `item2`:

the second KB-item. Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

"0", "0.5", or "1".

Computes the shortest path(s) between the two KB-items. The KB-distance is defined as in the paper, i.e. two KB-items are within 1-hop if they appear in the same KB-fact. Returns a list of paths between the items. Paths are either simple KB-facts (in case the items are in 1-hop), or combinations of paths with a middle node m in between item1 and item2, such that the first part of the tuple gives facts with item1 and m, and the second part of the tuple gives facts with m and item2 (in case the items are in 2-hop).

- `item1`:

the first KB-item. Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

- `item2`:

the second KB-item. Examples: "Q38111" (L. DiCaprio) or "P161" (cast member).

A list of paths between the items. Paths are either simple KB-facts (in case the items are in 1-hop), or combinations of paths with a middle node m in between item1 and item2, such that the first part of the tuple gives facts with item1 and m, and the second part of the tuple gives facts with m and item2 (in case the items are in 2-hop).