Merge pull request #73 from DerwenAI/update

Update

changelog.txt

@@ -2,20 +2,23 @@
 
 ## 0.1.5
 
-2020-12-??
+2021-01-??
 
-  * use `coverage` for unit test coverage
-  * use `mkdocs` to generate documentation
-  * type checking based on `typing` and `mypy`
-  * make `KnowledgeGraph` class GPU-aware
+  * renamed serialization methods, e.g., `save_ttl()` -- **WILL BREAK THINGS**
   * impl `load_rdf_text()` and `save_rdf_text()` to De/Ser as text
+  * type checking based on `typing` and `mypy`
   * corrected the `networkx` examples to use `DiGraph` for directed graphs
-  * integrate with `python-igraph`, `leidenalg`, `cairocffi` to support iGraph
+  * generated `meta.yml` for conda support
+  * use `mkdocs` to generate documentation
   * add method to return SPARQL query result set as a `pandas` DataFrame
+  * integrate with `python-igraph`, `leidenalg`, `cairocffi` to support iGraph
+  * provide simple `OWL-RL` inference with `infer_rdfs_closure()` and `infer_owlrl_closure()`
   * add `Subgraph` class for projecting onto `networkx`
   * add `Measure` class for measuring graphs and creating simplex generators
+  * use `coverage` for unit test coverage
+  * use `chocolate` for enhanced kwargs
+  * make `KnowledgeGraph` class GPU-aware
   * add `ShapeFactory` and related classes for evolving shape prediction
-  * provide simple `OWL-RL` inference with `infer_rdfs_closure()` and `infer_owlrl_closure()`
 
 
 ## 0.1.4

docs/biblio.md

@@ -176,7 +176,7 @@ Gradient Flow (2020)
 ### monarch2021hitl
 
 [*Human-in-the-Loop Machine Learning*](https://www.manning.com/books/human-in-the-loop-machine-learning)  
-*Robert (Munro) Monarch*  
+**Robert (Munro) Monarch**  
 Manning (2021)
 
 
@@ -188,6 +188,12 @@ Manning (2021)
 **Paco Nathan**  
 O'Reilly Media (2014)
 
+### nathan2019fifty
+
+[*Fifty Years of Data Management and Beyond*](https://www.oreilly.com/library/view/fifty-years-of/9781492057512/)  
+**Paco Nathan**  
+O'Reilly Media (2019)
+
 ### negro2021
 
 [*Graph-Powered Machine Learning*](https://www.manning.com/books/graph-powered-machine-learning)  
@@ -210,6 +216,15 @@ Manning (2021)
 *arXiv* (2020)
 
 
+## – S –
+
+### singhal2012things
+
+["Introducing the Knowledge Graph: things, not strings"](https://blog.google/products/search/introducing-knowledge-graph-things-not/)  
+**Amit Singhal**  
+Google (2012)
+
+
 ---
 
 ## Notes

docs/depend.md

@@ -7,6 +7,7 @@ Package dependencies as defined in
 include:
 
 - [cairocffi](https://cairocffi.readthedocs.io/)
+- [chocolate](https://github.com/seungjaeryanlee/chocolate)
 - [gensim](https://radimrehurek.com/gensim/)
 - [GPUtil](https://github.com/anderskm/gputil)
 - [leidenalg](https://leidenalg.readthedocs.io/)

docs/glossary.md

@@ -59,6 +59,11 @@ abbr. [Knowledge Graph Conference](#knowledge-graph-conference)
 
 ### knowledge graph
 
+One of the more concise, contemporary definitions is given in
+[[hogan2020knowledge]](../biblio/#hogan2020knowledge):
+
+> We refer to a knowledge graph as a data graph potentially enhanced with representations of schema, identity, context, ontologies and/or rules.
+
 see: <https://derwen.ai/d/knowledge_graph>
 
 ### Knowledge Graph Conference

docs/ref.md

@@ -1,7 +1,7 @@
 # Reference: `kglab` package
 ## [`KnowledgeGraph` class](#KnowledgeGraph)
 #### [`__init__` method](#kglab.KnowledgeGraph.__init__)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L46)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L47)
 
 ```python
 __init__(name="kg+lab", base_uri=None, language="en", namespaces={}, graph=None)
@@ -11,7 +11,7 @@ __init__(name="kg+lab", base_uri=None, language="en", namespaces={}, graph=None)
 
 
 #### [`merge_ns` method](#kglab.KnowledgeGraph.merge_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L84)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L85)
 
 ```python
 merge_ns(ns_set)
@@ -21,7 +21,7 @@ merge_ns(ns_set)
 
 
 #### [`add_ns` method](#kglab.KnowledgeGraph.add_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L94)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L95)
 
 ```python
 add_ns(prefix, uri)
@@ -31,7 +31,7 @@ Since rdflib converts Namespace bindings to URIRef, we'll keep references to the
 
 
 #### [`get_ns` method](#kglab.KnowledgeGraph.get_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L106)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L107)
 
 ```python
 get_ns(prefix)
@@ -43,7 +43,7 @@ return: rdflib.Namespace
 *returns:* `rdflib.namespace.Namespace`
 
 #### [`get_context` method](#kglab.KnowledgeGraph.get_context)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L117)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L118)
 
 ```python
 get_context()
@@ -54,7 +54,7 @@ Return a context needed for JSON-LD serialization
 *returns:* `dict`
 
 #### [`add` method](#kglab.KnowledgeGraph.add)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L137)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L138)
 
 ```python
 add(s, p, o)
@@ -64,7 +64,7 @@ add(s, p, o)
 
 
 #### [`type_date` classmethod](#kglab.KnowledgeGraph.type_date)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L148)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L149)
 
 ```python
 type_date(date, tz)
@@ -75,7 +75,7 @@ input `date` should be interpretable as having a local timezone
 *returns:* `rdflib.term.Literal`
 
 #### [`load_rdf` method](#kglab.KnowledgeGraph.load_rdf)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L173)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L174)
 
 ```python
 load_rdf(path, format="n3", encoding="utf-8")
@@ -85,7 +85,7 @@ load_rdf(path, format="n3", encoding="utf-8")
 
 
 #### [`load_rdf_text` method](#kglab.KnowledgeGraph.load_rdf_text)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L190)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L191)
 
 ```python
 load_rdf_text(data, format="n3", encoding="utf-8")
@@ -95,7 +95,7 @@ load_rdf_text(data, format="n3", encoding="utf-8")
 
 
 #### [`save_rdf` method](#kglab.KnowledgeGraph.save_rdf)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L202)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L203)
 
 ```python
 save_rdf(path, format="n3", encoding="utf-8")
@@ -105,7 +105,7 @@ save_rdf(path, format="n3", encoding="utf-8")
 
 
 #### [`save_rdf_text` method](#kglab.KnowledgeGraph.save_rdf_text)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L219)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L220)
 
 ```python
 save_rdf_text(format="n3", encoding="utf-8")
@@ -116,7 +116,7 @@ save_rdf_text(format="n3", encoding="utf-8")
 *returns:* `str`
 
 #### [`load_jsonld` method](#kglab.KnowledgeGraph.load_jsonld)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L230)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L231)
 
 ```python
 load_jsonld(path, encoding="utf-8")
@@ -126,7 +126,7 @@ load_jsonld(path, encoding="utf-8")
 
 
 #### [`save_jsonld` method](#kglab.KnowledgeGraph.save_jsonld)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L243)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L244)
 
 ```python
 save_jsonld(path, encoding="utf-8")
@@ -136,7 +136,7 @@ save_jsonld(path, encoding="utf-8")
 
 
 #### [`load_parquet` method](#kglab.KnowledgeGraph.load_parquet)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L262)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L263)
 
 ```python
 load_parquet(path)
@@ -146,7 +146,7 @@ load_parquet(path)
 
 
 #### [`save_parquet` method](#kglab.KnowledgeGraph.save_parquet)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L275)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L276)
 
 ```python
 save_parquet(path, compression="gzip")
@@ -156,7 +156,7 @@ save_parquet(path, compression="gzip")
 
 
 #### [`query` method](#kglab.KnowledgeGraph.query)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L292)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L293)
 
 ```python
 query(sparql, bindings={})
@@ -167,7 +167,7 @@ query(sparql, bindings={})
 *returns:* `typing.Iterable`
 
 #### [`n3fy` classmethod](#kglab.KnowledgeGraph.n3fy)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L304)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L305)
 
 ```python
 n3fy(d, nm, pythonify=True)
@@ -178,7 +178,7 @@ n3fy(d, nm, pythonify=True)
 *returns:* `dict`
 
 #### [`query_as_df` method](#kglab.KnowledgeGraph.query_as_df)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L328)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L329)
 
 ```python
 query_as_df(sparql, bindings={}, simplify=True, pythonify=True)
@@ -189,7 +189,7 @@ query_as_df(sparql, bindings={}, simplify=True, pythonify=True)
 *returns:* `pandas.core.frame.DataFrame`
 
 #### [`validate` method](#kglab.KnowledgeGraph.validate)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L352)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L353)
 
 ```python
 validate(shacl_graph=None, shacl_graph_format=None, ont_graph=None, ont_graph_format=None, advanced=False, inference=None, abort_on_error=None, serialize_report_graph="n3", debug=False, **kwargs)
@@ -200,7 +200,7 @@ validate(shacl_graph=None, shacl_graph_format=None, ont_graph=None, ont_graph_fo
 *returns:* `typing.Tuple[bool, ForwardRef('KnowledgeGraph'), str]`
 
 #### [`infer_skos_related` method](#kglab.KnowledgeGraph.infer_skos_related)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L402)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L403)
 
 ```python
 infer_skos_related()
@@ -210,7 +210,7 @@ Make sure that skos:related is stated in both directions (S23).
 
 
 #### [`infer_skos_topConcept` method](#kglab.KnowledgeGraph.infer_skos_topConcept)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L414)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L415)
 
 ```python
 infer_skos_topConcept()
@@ -220,7 +220,7 @@ Infer skos:topConceptOf/skos:hasTopConcept (S8) and skos:inScheme (S7).
 
 
 #### [`infer_skos_hierarchical` method](#kglab.KnowledgeGraph.infer_skos_hierarchical)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L432)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L433)
 
 ```python
 infer_skos_hierarchical(narrower=True)
@@ -232,7 +232,7 @@ but rather removed.
 
 
 #### [`infer_skos_transitive` method](#kglab.KnowledgeGraph.infer_skos_transitive)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L455)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L456)
 
 ```python
 infer_skos_transitive(narrower=True)
@@ -242,7 +242,7 @@ Perform transitive closure inference (S22, S24).
 
 
 #### [`infer_skos_symmetric_mappings` method](#kglab.KnowledgeGraph.infer_skos_symmetric_mappings)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L476)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L477)
 
 ```python
 infer_skos_symmetric_mappings(related=True)
@@ -255,7 +255,7 @@ skos:closeMatch and skos:exactMatch) are stated in both directions (S44).
 
 
 #### [`infer_skos_hierarchical_mappings` method](#kglab.KnowledgeGraph.infer_skos_hierarchical_mappings)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L503)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L504)
 
 ```python
 infer_skos_hierarchical_mappings(narrower=True)
@@ -267,7 +267,7 @@ skos:broader/skos:narrower (S41).
 
 
 #### [`infer_rdfs_classes` method](#kglab.KnowledgeGraph.infer_rdfs_classes)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L532)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L533)
 
 ```python
 infer_rdfs_classes()
@@ -278,7 +278,7 @@ Mark all resources with a subclass type with the upper class.
 
 
 #### [`infer_rdfs_properties` method](#kglab.KnowledgeGraph.infer_rdfs_properties)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L559)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L560)
 
 ```python
 infer_rdfs_properties()
@@ -289,7 +289,7 @@ Add superproperties where subproperties have been used.
 
 
 #### [`infer_rdfs_closure` method](#kglab.KnowledgeGraph.infer_rdfs_closure)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L586)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L587)
 
 ```python
 infer_rdfs_closure()
@@ -300,7 +300,7 @@ see <https://wiki.uib.no/info216/index.php/Python_Examples#RDFS_inference_with_R
 
 
 #### [`infer_owlrl_closure` method](#kglab.KnowledgeGraph.infer_owlrl_closure)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L598)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L599)
 
 ```python
 infer_owlrl_closure()

docs/what.md

@@ -5,6 +5,17 @@
 This material is a work in progress, at "rough draft" stage.
 
 
+First, read:
+[[hogan2020knowledge]](../biblio/#hogan2020knowledge)
+
+Some good elements for KG definition:
+<https://towardsdatascience.com/how-to-create-representations-of-entities-in-a-knowledge-graph-using-pyrdf2vec-82e44dad1a0#1f07>
+>Graphs are data structures that are useful to represent ubiquitous phenomena, such as social networks, chemical molecules and recommendation systems. One of their strengths lies in the fact that they explicitly model relations (i.e. edges) between individual units (i.e. nodes), which adds an extra dimension to the data.
+
+compare:
+[[nathan2019fifty]](../biblio/#nathan2019fifty)
+
+
 ## Just Enough Graph Theory
 
 In a pure mathematical form, where a *node* (or *vertex*) can connect

kglab/kglab.py

@@ -19,6 +19,7 @@
 
 from kglab.types import PathLike, GraphLike, RDF_Node
 
+import chocolate  # type: ignore
 import dateutil.parser as dup
 import datetime as dt
 import GPUtil  # type: ignore
@@ -376,7 +377,7 @@ def validate (
             abort_on_error=abort_on_error,
             debug=debug,
             serialize_report_graph=serialize_report_graph,
-            *kwargs,
+            **chocolate.filter_args(kwargs, pyshacl.validate),
             )
 
         namespaces = {