QApedia package

Módulos

QApedia.generator module

O módulo generator permite ao usuário realizar buscas sobre o endpoint da dbpedia. Além disso, permite ao usuário realizar a construção de queries sparql dado um template previamente especificado.

Este arquivo pode ser importado como um módulo e contém as seguintes funções:

  • adjust_generator_query - retorna a generator_query com os rótulos correspondente a cada variável.
  • perform_query - realiza a execução da query no endpoint da dbpedia.
  • get_results_of_generator_query - similar a função perform_query, entretanto, realiza os ajustes em cima da generator_query e salva o resultado da busca na memória.
  • extract_pairs - realiza a construção dos pares de questão-sparql com base no resultado e template especificados.
QApedia.generator.adjust_generator_query(generator_query, variables, lang='pt')

Dada uma `generator_query` é retornada uma versão contendo os labels que são utilizados para preencher as lacunas presentes na pergunta.

Parâmetros:
  • generator_query (str) – Query utilizada para geração dos pares de questão-sparql.
  • variables (list) – Lista contendo as variáveis utilizadas nas lacunas da questão-sparql.
  • lang (str, optional) – Idioma do campo rdfs:label adicionado na generator_query. O valor padrão é «pt».
Retorno:

Retorna a generator_query com os campos labels de cada variável.

Tipo de retorno:
 

str

Examples

No exemplo a seguir, temos a generator_query que será utilizada futuramente para retornar recursos que tenham o campo dbo:abstract. O resultado dela é usado para preencher as lacunas do seguinte par ("o que é <A>?", "select ?a where { <A> dbo:abstract ?a "). Para preencher a lacuna da pergunta em linguagem natural, é adicionada na generator_query o campo rdfs:label correspondente as variáveis que se deseja obter informações.

>>> generator_query = "select distinct(?a) WHERE { ?a dbo:abstract []}"
>>> variables = ['a']
>>> result = adjust_generator_query(generator_query, variables)
>>> result
"select distinct(?a) ?la where { ?a rdfs:label ?la. FILTER(lang(?la) = 'pt').  ?a dbo:abstract [] }"
QApedia.generator.perform_query(query, prefixes='', endpoint='http://dbpedia.org/sparql')

Dada uma query sparql retorna uma lista correspondendo ao resultado da pesquisa se a cláusula utilizada for SELECT, CONSTRUCT ou DESCRIBE. Caso seja ASK, o valor retornado é um boolean.

Parâmetros:
  • query (str) – Sparql utilizada para realizar uma busca no endpoint especificado.
  • prefixes (str, optional) – Corresponde ao conjunto de prefixos utilizados na consulta SPARQL. Se não estiver usando prefixos, o uso desse parâmetro não é necessário, o valor padrão é «».
  • endpoint (str, optional) – Indica endpoint utilizado, o valor default é http://dbpedia.org/sparql
Retorno:

  • list of dict – Corresponde a um lista contendo bindinds retornados pela busca Sparql. Se a cláusula utiliza SELECT ou CONSTRUCT.
  • bool – Se a cláusula ASK for afirmativa retorna True, caso contrário False.

Examples

>>> from QApedia.generator import perform_query
>>> query = "SELECT * WHERE {"\
...         "?manga a dbo:Manga ."\
...         "?manga rdfs:label ?nome ."\
...         "?manga dbo:author dbr:Yoshihiro_Togashi ."\
...         "FILTER(lang(?nome) = 'pt').}"
>>> results = perform_query(query)
>>> for result in results:
...     print("%s: %s" %(result["nome"].value, result["manga"].value))
...
Level E: http://dbpedia.org/resource/Level_E
Yu Yu Hakusho: http://dbpedia.org/resource/Yu_Yu_Hakusho
Hunter × Hunter: http://dbpedia.org/resource/Hunter_×_Hunter
Raises:exc_type – Caso haja um erro que não seja proveniente do problema de acesso ao endpoint, por exemplo, uma query em um formato inválido, uma exceção é gerada.
QApedia.generator.get_results_of_generator_query(generator_query, variables, prefixes='', endpoint='http://dbpedia.org/sparql', lang='pt')

Dada uma `generator_query` é retornado um conjunto de resultados obtidos ao executar a query no endpoint especificado.

Parâmetros:
  • generator_query (str) – String representando a `generator_query`.
  • variables (list) – Lista de caracteres correspondendo as variáveis.
  • prefixes (str, optional) – Corresponde ao conjunto de prefixos utilizados na consulta SPARQL. Se não estiver usando prefixos, o uso desse parâmetro não é necessário, o valor padrão é «».
  • endpoint (str, optional) – Indica endpoint utilizado., by default «http://dbpedia.org/sparql»
  • lang (str, optional) – Idioma do campo rdfs:label adicionado na generator_query. O valor padrão é «pt».
Retorno:

  • list of dict – Corresponde a um lista contendo bindinds retornados pela busca Sparql. Se a cláusula utiliza SELECT ou CONSTRUCT.
  • bool – Se a cláusula ASK for afirmativa retorna True, caso contrário False.

QApedia.generator.extract_pairs(bindings, template, number_of_examples=500, list_of_prefixes=[])

Realiza a extração do conjunto de pares de questão-sparql correspondentes obtidos pelo método QApedia.generator.get_bindings_of_generator_query().

Parâmetros:
  • bindings (list) – Resultado obtido após a execução da query correspondendo aos «bindings»
  • template (dict) – Corresponde ao template utilizado para geração dos resultados.
  • number_of_examples (int, optional) – Número de resultados a serem considerados para o template, o valor padrão é 500.
  • list_of_prefixes (list, optional) – Corresponde a lista de prefixos obtida através do método QApedia.utils.convert_prefixes_to_list(), onde os prefixos devem ser os mesmos que foram utilizados na função que gerou os bindings. Se não estiver usando prefixos, o uso desse parâmetro não é necessário, o valor padrão é [].
Retorno:

Lista contendo os pares sparql-question do template.

Tipo de retorno:
 

list

Examples

>>> from QApedia.generator import extract_pairs
>>> from QApedia.generator import get_results_of_generator_query
>>> template = {"question": "Yoshihiro Togashi escreveu <A>?",
...             "query": "ask where {"\
...                      "dbr:Yoshihiro_Togashi ^ dbo:author <A>}",
...             "generator_query": "select ?a where{"\
...                          "dbr:Yoshihiro_Togashi ^ dbo:author ?a}",
...             "variables": ["a"]}
>>> bindings = get_results_of_generator_query(
...                                       template["generator_query"],
...                                       template["variables"])
>>> pairs = extract_pairs(bindings, template)
>>> pairs[2]["question"]
'Yoshihiro Togashi escreveu Hunter × Hunter?'
>>> pairs[2]["sparql"]
'ask where {dbr:Yoshihiro_Togashi ^ dbo:author http://dbpedia.org/resource/Hunter_×_Hunter}'

QApedia.io module

Este módulo trata das operações relacionadas a leitura e escrita do pacote QApedia.

Neste módulo, pode-se encontrar as seguintes funções:

  • load_templates - realiza a leitura do arquivo contendo o conjunto de templates utilizados para a geração de perguntas-queries.
QApedia.io.load_templates(filepath, delimiter=';')

A função load_templates, carrega o conjunto de templates a partir de um arquivo csv. O dado deve possuir um campo generator_query que servirá para realizar buscas que preencherão as lacunas presentes nos campos question e query.

Parâmetros:
  • filepath (str) – Caminho do arquivo csv que contém os templates.
  • delimiter (str, optional) – Indicar qual separador utilizado no arquivo, by default “;”
Retorno:

Retorna um dataframe contendo o conjunto de templates.

Tipo de retorno:
 

pd.DataFrame

Examples

Exemplo contendo 14 templates sendo carregado através da função load_templates.

>>> from QApedia.io import load_templates
>>> filename = "sample.csv"
>>> templates = load_templates(filename)
>>> len(templates)
14
>>> templates.head()
                                            query  ... variables
0  <A> e <B> são os municípios vizinhos de que lu...  ...    [a, b]
1                <A> e <B> pertencem a qual espécie?  ...    [a, b]
2      <A> e <B> podem ser encontrados em qual país?  ...    [a, b]
3            <A> e <B> é produzido por qual empresa?  ...    [a, b]
4      <A> e <B> é o trabalho notável de qual autor?  ...    [a, b]

[5 rows x 4 columns]

QApedia.utils module

Este módulo contém o conjunto de operações utilizadas pelos módulos principais como por exemplo, o método QApedia.io.load_templates() que utiliza o método QApedia.utils.extract_variables() desse módulo para extrair o conjunto de variáveis presentes na query geradora (generator_query).

Neste módulo, pode-se encontrar as seguintes funções:

  • extract_variables - realiza a extração das variáveis presentes no select da query geradora.
  • convert_prefixes_to_list - dado o conjunto de prefixos, converte a string em uma lista de tuplas.
  • encode - dada uma sparql realiza a codificação da query transformando alguns símbolos em texto.
  • decode - dada uma sparql transformada por meio do encode realiza a transformação de inversa, de modo a substituir o texto por operações válidas.
QApedia.utils.extract_variables(generator_query)

Extrai as variáveis correspondente presentes no “generator_query”.

Parâmetros:generator_query (str) – A “generator_query” corresponde a query que será utilizada para obter as variáveis presente nas lacunas da pergunta(query) e do sparql.
Retorno:Lista contendo as variáveis a serem respondidas.
Tipo de retorno:
 lst

Examples

>>> generator_query = "select distinct ?a where {"\
...                   "?uri <http://dbpedia.org/ontology/author> ?a }"
>>> variables = extract_variables(generator_query)
>>> print(variables)
['a']
QApedia.utils.convert_prefixes_to_list(prefixes)

Converte uma string dos prefixos em uma lista de tuplas. Onde cada par contém um identificador e a uri correspondente.

Parâmetros:prefixes (str) – string correspondendo aos prefixos utilizados na consulta SPARQL.
Retorno:Lista de tuplas, onde cada tupla contém dois itens, o primeiro corresponde ao nome dado a URI que corresponde ao segundo item.
Tipo de retorno:
 list

Examples

>>> from QApedia.utils import convert_prefixes_to_list
>>> prefixes = "PREFIX foaf: <http://xmlns.com/foaf/0.1/>\
...             PREFIX yago: <http://yago-knowledge.org/resource/>\
...             PREFIX rdfs:<http://www.w3.org/2000/01/rdf-schema#>\
...             PREFIX dbo:<http://dbpedia.org/ontology/>\
...             PREFIX dbp:<http://dbpedia.org/property/>"
>>> list_of_prefixes = convert_prefixes_to_list(prefixes)
>>> for prefix, uri in list_of_prefixes:
...     print(prefix, uri)
...
foaf: http://xmlns.com/foaf/0.1/
yago: http://yago-knowledge.org/resource/
rdfs: http://www.w3.org/2000/01/rdf-schema#
dbo: http://dbpedia.org/ontology/
dbp: http://dbpedia.org/property/
QApedia.utils.encode(sparql, prefixes)

Dada uma query sparql, essa função transforma algum de seus caracteres em texto.

Parâmetros:
Retorno:

sparql transformada.

Tipo de retorno:
 

str

Examples

>>> from QApedia.utils import encode
>>> from QApedia.utils import convert_prefixes_to_list
>>> prefixes = "PREFIX prop: <http://dbpedia.org/property/>\
...             PREFIX dbr: <http://dbpedia.org/resource/>"
>>> query = "ASK {\n\
...         <http://dbpedia.org/resource/Amazon_River> prop:length     ?amazon .\n\
...         <http://dbpedia.org/resource/Nile> prop:length ?nile .\n\
...         FILTER(?amazon > ?nile) .\n\
...         }"
>>> list_of_prefixes = convert_prefixes_to_list(prefixes)
>>> query_encoded = encode(query, list_of_prefixes)
>>> print(query_encoded)
ASK  bracket_open
        dbr_Amazon_River prop_length     var_amazon  sep_dot
        dbr_Nile prop_length var_nile  sep_dot
        FILTER(var_amazon  greater_than  var_nile)  sep_dot
        bracket_close
QApedia.utils.decode(sparql_encoded, prefixes)

Dada uma sparql que foi codificada pela função QApedia.utils.encode(). O método decode substuir os termos codificados por símbolos válidos da consulta sparql.

Parâmetros:
Retorno:

sparql com os símbolos válidos para uma consulta.

Tipo de retorno:
 

str

Examples

>>> from QApedia.utils import decode
>>> from QApedia.utils import convert_prefixes_to_list
>>> prefixes = "PREFIX prop: <http://dbpedia.org/property/>\
...             PREFIX dbr: <http://dbpedia.org/resource/>"
>>> list_of_prefixes = convert_prefixes_to_list(prefixes)
>>> query_encoded = "ASK  bracket_open \n\
...       dbr_Amazon_River prop_length var_amazon  sep_dot \n\
...       dbr_Nile prop_length var_nile  sep_dot \n\
...       FILTER(var_amazon  greater_than  var_nile)  sep_dot  \n\
...       bracket_close "
>>> print(decode(query_encoded, list_of_prefixes))
ASK {
    dbr:Amazon_River prop:length ?amazon .
    dbr:Nile prop:length ?nile .
    FILTER(?amazon > ?nile) .
    }