Module:Wikidata/Chemin/Documentation

Ceci est la page de documentation de Module:Wikidata/Chemin [modifier] [purger].

Cette sous-page contient les instructions et les catégories de son module d'origine et elle n'est pas destinée à être visualisée directement.

Cette page est en cours de réécriture ou de restructuration importante (indiquez la date de pose grâce au paramètre date).

Un utilisateur prévoit de modifier cet article pendant plusieurs jours. Vous êtes invité(e) à en discuter en page de discussion et à participer à son amélioration de préférence en concertation pour des modifications de fond.

Le module Wikidata/Chemin est une implémentation un peu adaptée des PropertyPath de Q54871 (« SPARQL ») en Lua poun Wikidata et les clients Wikibase.

Il existe cependant quelques différences entre les chemins de propriétés sparql et cette implémentation:

la syntaxe est étendue pour gérer les qualificatifs des déclarations (opérateur >)
contrairement au cas de l’implémentation sparql, il est nécessaire de fournir un point de départ pour le calcul des valeurs possibles au bout du chemin
il est possible d’utiliser les identifiants Wikidata des propriétés sans préfixe d’uri, et il est également possible d’utiliser les intitulés des propriétés dans la langue principale du wiki (par exemple il est possible d’utiliser père pour la propriété P22 (« père »)
l’opérateur ^ ne peut pas fonctionner en lua avec l’API mw.wikibase actuelle (mai 2019)

Chemins

Exemple introductif

Un chemin pour trouver les petits-enfants "enfant/enfant" sera notre premier chemin. Nous allons l’utiliser en paramètre d’un modèle de démonstration capable d’utiliser des chemins, à partir d’un élément choisi, prenons l’élément du Dieu Grec Zeus (Q34201 (« Zeus ») : {{Liste valeur chemin wikidata|Q34201|enfant/enfant}}

Le modèle liste en premier résultat (au moment de l’écriture de ces lignes) Q572133 (« Antéros »). La raison de sa présence est l’existence d’une déclaration Wikidata

Q34201 (« Zeus »)

P22 (« père ») : Q40901 (« Arès »)

puis sur Q40901 (« Arès ») d’une déclaration

Q40901 (« Arès »)

P22 (« père ») : Q572133 (« Antéros ») .

En réalité Zeus à de nombreux autres petits enfants qui ne sont par montrés parce que le modèle se limite par défaut à un certain nombre de résultats.

De manière similaire, si nous voulons lister les mères des enfants de Zeus nous pouvons utiliser le chemin enfant/P25 grâce à la propriété P25 (« mère ») :

Ces exemples n’utilisent qu’un seul connecteur, / qui permet d’exprimer une séquence de déclarations. Il en existe d’autre que nous allons décrire brièvement dans la section suivante, qui peuvent se combiner pour créer des chemins plus complexes.

Opérateurs

Dans ce qui suit, un chemin d’entités sera une séquence d’éléments et de propriétés. Un chemin d’entités sera potentiellement terminé par une valeur Wikidata comme une date ou une quantité. Voici un exemple de chemin d’entités Q1001 (« Mahatma Gandhi ») → P31 (« nature de l’élément ») → Q5 (« être humain ») → P279 (« sous-classe de ») → Qhttps://www.wikidata.org/wiki/Q215627 (« ») ou Q34201 (« Zeus ») → la propriété child n’existe pas. Remplacez par un identifiant ou un intitulé de propriété en français existant → Q40901 (« Arès ») → la propriété child n’existe pas. Remplacez par un identifiant ou un intitulé de propriété en français existant → Q572133 (« Antéros ») will be paths. It's possible to create item paths from Wikidata statements starting from an item and following the statements' main property and main values, but also as we will see later by following the qualifiers snaks of some property. In this case our item paths could look like Q991 (« Fiodor Dostoïevski ») → P19 (« lieu de naissance ») → Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début ») →

We will discover the operation of "matching" an item path with a path. First we need to define and operation beetween a property and an item path : "eating". We will say that a property can "eat" WD P' a path if the first property of a path is WD P'. The result will be a path shortened up to this property - takin a property and a path :

Path = Q991 (« Fiodor Dostoïevski ») → P19 (« lieu de naissance ») → Q656 (« Saint-Pétersbourg ») → la propriété official name n’existe pas. Remplacez par un identifiant ou un intitulé de propriété en français existant → P580 (« date de début ») →
WD P'=P19 (« lieu de naissance »)

P can "eat" the path which will result to Q656 (« Saint-Pétersbourg ») → P1448 (« nom officiel ») → P580 (« date de début »). Another property could not eat this path. The operation of "eating" is used to construct the operation of "matching" an item path to a property path - it finds all the item paths we can construct on Wikidata following statements from a starting item that matches a part.

A path matches an item path if the components of a path can entirely eat the item path - except for one item or value.

This module performs the operation of finding the item paths in Wikidata that can be totally eaten by a path pattern. Additionally, all parts of a path must eat something in the sense defined in the following section.

For example : the path Mexico → shares border with → USA → shares border with → Canada will be a match for the pattern shares border with/shares border with but won't be a match for shares border with nor for shares border with/shares border with/shares border with. The first one because there will be parts of the path that are not eaten, and the second because the third shares border with has nothing to eat.

We will extend this "eating" operation to more complex path in the following.

A path is constructed using the following operators and properties :

simple property: A simple property is either a property Pid or a property label like P31 or instance of. A property "eats" a path as explained above. If using the label of the property like in "instance of", only the label of a property can be used and not an alias. The language of the label also matters : it must be written in the language of the main wiki (english for wikidata, french for french wikipedia, ...)
/: The sequence operator. See the initial example. This operator is one basic operation to build a complex path from simpler path. if P1 is a path and P2 is a path then P1/P2 is also a path. P1/P2 will eat an item path IP if P1 eats IP at first, then if P2 eats the result of P1 eating IP.
|: The alternative operator. This operator is one other basic operation to build a complex path from simpler path. if P1 is a path and P2 is a path then P1|P2 is also a path. P1|P2 will eat an item path IP if either P1 eats IP or P2 eats IP.
?: an operator that make the preceding path optional. It always eats something. For example the pattern share borders with? starting from Mexico will match both the Mexico path and the Mexico → shares border with → USA one.
*: an operator that, like preceding one, always matches. It allows to match a path of indefinite size if it can be eaten by repeating the "eat" operation as many times as we like on the path that is preceded by the operator. For example the code (father|mother)* will find all the ancestors of the starting point in a genealogical tree, including itself. It will find the parents of someone (the father and the mother) then the parents of the parents and so on.
+: P+ is equivalent to P/P*. Like the * operator except it must be at least one math of P.
>: This operator is related to qualifier snaks matching. For example the path union of>of will eat the qualifier "of" snaks of the statements "union of" of an item. The values from which the next operator of the path will start is the value of the snak.; It also can be used either at the very beginning of the path, if the starting point of the path is a statement and not an item.
!: This operator is a way to define property that will not be eaten. It is followed by either a single property or a list of properties separated by a | put into parenthesis. for example !(instance of|subclass of) will eat any (one-propertied) path like Donald Duck → Father → Picsou, but neither Ghandi → instance of → human nor human → subclass of → animal. It can also be used with the > operator to exclude a set of qualifiers for matching.
{number} and {min, max}: This operator is used to specify that a path can match several times, but with a bound. P{4} is equivalent to P/P/P/P, that is P must eat exactly four times something, and P{4,6} must match between 4 and six times. It's equivalent to P/P/P/P/P?/P?

Results

This module manipulates and generate a datastructure called "ResultNode" that represent nodes on a matching path (a path that is totally eaten by a path pattern).

The path is designed such as the result is a linked list of Nodes. Those nodes represents a path (say <human> → <P31> → <Q5> → <P279> → <Q42> ) in backward order. Actually each node can be interpreted as either a snak or a statement (like the <P279> → <Q42>) in the usual lua Wikidata data model (it's actually a snak or a statement which is adjoined a few functions and attributes. So a result node can be used as a snak or a statement in the functions of Module:Wikidata.

The previous snak or statement can be retrieved thanks trough the "parent" field of the node.

Interface

Main functions
iterate

path (string), start_item (string, entity object) -> iterator (on result node)

function that takes a path and a start item and returns an iterable object, usable in lua for loops that iterates over the set of paths matching the pattern, each represented by a ResultNode (see above)

Utilisation

Fonctions exportables :

fonction(frame) – description (courte description de fonction(frame) et autres informations pertinentes).
fonction2() – description2 (courte description de fonction2() et autres informations pertinentes).

Autres fonctions :

fonction() – description2 (courte description de fonction() et autres informations pertinentes).

Modules externes et autres éléments dont ce module a besoin pour fonctionner :

mw.title – description (courte description expliquant la dépendance de ce module externe).

Exemples

Pour des exemples, voir la page de test permettant de tester diverses modifications apportées.

Projet Scribunto