Visualização e Qualidade de Dados no Wikidata/Avaliação de Qualidade no Wikidata/Recoin/script

Recoin-logo

O Recoin é uma ferramenta baseada no Wikidata que estima a completude relativa de um item comparando-o com itens semelhantes (por classe ou profissão) e destaca propriedades relevantes que ainda estão ausentes. Uma barra de classificação com cinco níveis (de “muito básico” a “muito detalhado”) e listas expansíveis de propriedades/IDs ausentes são exibidas diretamente na página do item para orientar editores e informar consumidores de dados sobre o grau de informação disponível.

Como funciona

O Recoin consulta o serviço SPARQL do Wikidata e utiliza tabelas de frequências pré-computadas (no Toolforge) para identificar, por classe/profissão, quais propriedades são mais comuns e quais faltam no item atual. O cálculo agrega as frequências em um escore de completude (níveis 1 a 5) e retorna, em JSON (ou JSONP), as principais propriedades/IDs ausentes, que a ferramenta renderiza na interface.

Classificação de completude

A escala do Recoin resume a completude relativa pela média de frequência das 5 principais propriedades ausentes para itens comparáveis. Em linhas gerais: nível 5 (0–5%), 4 (5–10%), 3 (10–25%), 2 (25–50%), 1 (50%+).

Ativação do Recoin

Para usar o Recoin na interface do Wikidata, ative a ferramenta (extensão de usuário/gadgets) em: Preferências → Gadgets → Recoin: Relative Completeness Indicator.

API pública

Além do gadget, há uma API no Toolforge que retorna JSON (ou JSONP) com o escore de completude e as propriedades/IDs ausentes:

Propriedades

https://recoin.toolforge.org/getmissingattributes.php?lang=

xx&subject=QID&n=10..100

Identificadores externos (IDs)

https://recoin.toolforge.org/getmissingattributes_id.php?lang=

xx&subject=QID&n=10..100

Por classe (lista de propriedades mais frequentes de uma classe)

https://recoin.toolforge.org/getbyclassid.php?subject=

QID_da_classe&n=200

Parâmetros principais: subject (Q-id), lang (código ISO da interface), n (quantos atributos/IDs listar). A API também aceita callback para JSONP (ver explicação abaixo).

O que é JSONP?

JSONP (JSON with Padding) é uma técnica pré-CORS para contornar a política de mesma origem em requisições cross-domain usando uma tag <script>. O servidor envolve o JSON em uma chamada de função (p.ex., callback({...})), e bibliotecas como jQuery interpretam automaticamente a resposta quando você usa callback=? em $.getJSON. Observações: funciona somente com GET, não suporta cabeçalhos personalizados, com limitações de segurança em comparação ao CORS. A API do Recoin oferece JSON puro (sem callback) e JSONP (com callback=...), o que facilita o uso direto no gadget.

Exemplos de uso do Recoin em Python

1) Obter e imprimir o JSON bruto (inclui tratamento de JSONP quando houver)

# Exemplo didático: consulta à API do Recoin com tolerância a JSONP
# Requisitos: requests

import requests, json, re

def fetch_recoin(endpoint, subject="Q569965", lang="pt", n=20, timeout=30):
"""
endpoint: 'attributes' para propriedades ausentes ou 'ids' para identificadores externos ausentes.
subject: QID (ex.: 'Q569965').
lang: código de idioma (ex.: 'pt', 'en').
n: número máximo de itens sugeridos.
Retorno: dicionário Python com o payload JSON.
Observação: se o servidor responder em JSONP (callback(...)), removemos o 'wrapper'.
"""
base = (
"https://recoin.toolforge.org/getmissingattributes.php
"
if endpoint == "attributes"
else "https://recoin.toolforge.org/getmissingattributes_id.php
"
)
params = {"subject": subject, "lang": lang, "n": int(n)}
# Dica: deixe SEM 'callback' para priorizar JSON puro; o gadget usa JSONP, mas a API aceita ambos.
headers = {"User-Agent": "RecoinDocsExample/1.0 (+https://pt.wikiversity.org/)"}

r = requests.get(base, params=params, timeout=timeout, headers=headers)
r.raise_for_status()
txt = r.text.strip()

# Remoção robusta de JSONP: callbackName({...})
m = re.match(r'^[a-zA-Z_$][\w$]*\((.*)\)$', txt, flags=re.S)
if m:
    txt = m.group(1)

return json.loads(txt)

# Consultas: propriedades ausentes e IDs ausentes

data_props = fetch_recoin("attributes", subject="Q569965", lang="pt", n=20)
data_ids = fetch_recoin("ids", subject="Q569965", lang="pt", n=20)

print("Chaves disponíveis (propriedades):", list(data_props.keys()))

# Em algumas versões, a lista vem em 'missing_properties'

exemplo = (data_props.get("missing_properties")
or data_props.get("missing")
or data_props.get("attributes")
or [])[:1]
print("Exemplo de registro:", exemplo)

2) DataFrame com as principais propriedades ausentes

# Requisitos: pandas

import pandas as pd

def to_df_missing(data):
"""
Normaliza diferentes variações de chaves para uma mesma estrutura tabular.
Principais campos observados na API: 'missing_properties' (lista), e em cada item:
- 'property' (PXXX), 'label' (rótulo), 'base_frequency' (frequência na classe),
'data_type' (tipo de valor), possivelmente 'present' (booleano), 'score'/'weight'.
"""
missing = (data.get("missing_properties")
or data.get("missing_attributes")
or data.get("missing")
or data.get("attributes")
or [])
rows = []
for m in missing:
rows.append({
"property": m.get("property") or m.get("pid") or m.get("p"),
"label": m.get("label") or m.get("name"),
"freq": m.get("base_frequency") or m.get("frequency") or m.get("support"),
"present": m.get("present"),
"score": m.get("score") or m.get("weight"),
"data_type": m.get("data_type")
})
return pd.DataFrame(rows)

df_props_pt = to_df_missing(data_props)
print(df_props_pt.head(10))

3) Comparar interface em dois idiomas (português vs inglês)

# Obter payloads em PT e EN

data_pt = fetch_recoin("attributes", subject="Q569965", lang="pt", n=20)
data_en = fetch_recoin("attributes", subject="Q569965", lang="en", n=20)

df_pt = to_df_missing(data_pt).assign(lang="pt")
df_en = to_df_missing(data_en).assign(lang="en")

# Junção por propriedade para ver interseções, rótulos e frequências por idioma

merged = df_pt.merge(df_en, on="property", how="outer", suffixes=("_pt", "_en"))
print(merged[["property","label_pt","label_en","freq_pt","freq_en"]].head(15))

4) Listar identificadores externos ausentes (IDs)

ids_pt = fetch_recoin("ids", subject="Q569965", lang="pt", n=20)
df_ids = to_df_missing(ids_pt)
print(df_ids.head(10))

Observações:

• API pode aplicar rate limits e ocasionalmente responder via JSONP; o código acima remove o wrapper do callback, quando presente.

• O número e a nomenclatura de chaves no JSON podem variar com atualizações (p.ex., missing_properties, missing, attributes); os exemplos são tolerantes a nomes de campos.

• Valores do score de completude são relativos e não mede correção das afirmações; ele prioriza propriedades frequentes entre itens comparáveis.

Boas práticas e limitações

Comparabilidade: resultados mais úteis ao editar itens de uma mesma classe/profissão (p.ex., comparar especialidades acadêmicas entre si).

Múltiplas classes/profissões: o cálculo pondera frequências quando o item pertence a mais de uma classe/profissão.

IDs externos: há um endpoint específico para sugerir identificadores ausentes (útil para enriquecer ligações a bases externas).