Merge pull request #241 from DerwenAI/update_docs

update docs

CITATION

@@ -3,6 +3,6 @@
   title = {{kglab: a simple abstraction layer in Python for building knowledge graphs}},
   year = 2020,
   publisher = {Derwen},
-  doi = {10.5281/zenodo.4602403},
+  doi = {10.5281/zenodo.6360664},
   url = {https://github.com/DerwenAI/kglab}
 }

README.md

@@ -1,6 +1,6 @@
 # kglab
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4717287.svg)](https://doi.org/10.5281/zenodo.4717287)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6360664.svg)](https://doi.org/10.5281/zenodo.6360664)
 ![Licence](https://img.shields.io/github/license/DerwenAI/kglab)
 ![Repo size](https://img.shields.io/github/repo-size/DerwenAI/kglab)
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/w/DerwenAI/kglab?style=plastic)
@@ -187,7 +187,7 @@ this library.
   title = {{kglab: a simple abstraction layer in Python for building knowledge graphs}},
   year = 2020,
   publisher = {Derwen},
-  doi = {10.5281/zenodo.4717287},
+  doi = {10.5281/zenodo.6360664},
   url = {https://github.com/DerwenAI/kglab}
 }
 ```

changelog.txt

@@ -1,8 +1,15 @@
 # `kglab` changelog
 
+## 0.5.?
+
+2022-03-?
+
+  * ?
+
+
 ## 0.5.2
 
-2022-03-??
+2022-03-15
 
   * bump up versions of dependencies to fit Py 3.7+
   * improve testing based on pytest; kudos @Mec-iS

docs/ack.md

@@ -93,12 +93,12 @@ it in your research or software:
   title = {{kglab: a simple abstraction layer in Python for building knowledge graphs}},
   year = 2020,
   publisher = {Derwen},
-  doi = {10.5281/zenodo.4717287},
+  doi = {10.5281/zenodo.6360664},
   url = {https://github.com/DerwenAI/kglab}
 }
 ```
 
-**DOI:** <https://doi.org/10.5281/zenodo.4717287>
+**DOI:** <https://doi.org/10.5281/zenodo.6360664>
 
 
 ## License and Copyright

docs/ref.md

@@ -16,10 +16,10 @@ Core feature areas include:
 
 ---
 #### [`__init__` method](#kglab.KnowledgeGraph.__init__)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L81)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L77)
 
 ```python
-__init__(name="generic", base_uri=None, language="en", use_gpus=True, import_graph=None, namespaces=None)
+__init__(name="generic", base_uri=None, language="en", store=None, use_gpus=True, import_graph=None, namespaces=None)
 ```
 Constructor for a `KnowledgeGraph` object.
 
@@ -32,6 +32,9 @@ the default [*base URI*](https://tools.ietf.org/html/rfc3986#section-5.1) for th
   * `language` : `str`  
 the default [*language tag*](https://www.w3.org/TR/rdf11-concepts/#dfn-language-tag), e.g., used for [*language indexing*](https://www.w3.org/TR/json-ld11/#language-indexing)
 
+  * `store` : `str`  
+optionally, string representing an `rdflib.Store` plugin to use.
+
   * `use_gpus` : `bool`  
 optionally, use the NVidia GPU devices with [RAPIDS](https://rapids.ai/) if these libraries have been installed and the devices are available; defaults to `True`
 
@@ -43,9 +46,20 @@ a dictionary of [*namespace*](https://rdflib.readthedocs.io/en/stable/apidocs/rd
 
 
 
+---
+#### [`build_blank_graph` method](#kglab.KnowledgeGraph.build_blank_graph)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L141)
+
+```python
+build_blank_graph()
+```
+Build a new `rdflib.Graph` object, based on storage plugin configuration.
+
+
+
 ---
 #### [`rdf_graph` method](#kglab.KnowledgeGraph.rdf_graph)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L140)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L155)
 
 ```python
 rdf_graph()
@@ -59,7 +73,7 @@ the [`rdflib.Graph`](https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.html
 
 ---
 #### [`add_ns` method](#kglab.KnowledgeGraph.add_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L165)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L180)
 
 ```python
 add_ns(prefix, iri, override=True, replace=False)
@@ -84,7 +98,7 @@ replace any existing prefix with the new namespace
 
 ---
 #### [`get_ns` method](#kglab.KnowledgeGraph.get_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L209)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L224)
 
 ```python
 get_ns(prefix)
@@ -101,7 +115,7 @@ the RDFlib [`Namespace`](https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.
 
 ---
 #### [`get_ns_dict` method](#kglab.KnowledgeGraph.get_ns_dict)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L225)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L240)
 
 ```python
 get_ns_dict()
@@ -115,7 +129,7 @@ a `dict` describing the namespaces in this RDF graph
 
 ---
 #### [`describe_ns` method](#kglab.KnowledgeGraph.describe_ns)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L247)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L262)
 
 ```python
 describe_ns()
@@ -129,7 +143,7 @@ a [`pandas.DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/ap
 
 ---
 #### [`get_context` method](#kglab.KnowledgeGraph.get_context)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L274)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L289)
 
 ```python
 get_context()
@@ -144,7 +158,7 @@ context needed for JSON-LD serialization
 
 ---
 #### [`encode_date` method](#kglab.KnowledgeGraph.encode_date)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L293)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L308)
 
 ```python
 encode_date(dt, tzinfos)
@@ -164,7 +178,7 @@ timezones as a dict, used by
 
 ---
 #### [`add` method](#kglab.KnowledgeGraph.add)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L315)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L330)
 
 ```python
 add(s, p, o)
@@ -187,7 +201,7 @@ To prepare for upcoming **kglab** features, **this is the preferred method for a
 
 ---
 #### [`remove` method](#kglab.KnowledgeGraph.remove)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L349)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L364)
 
 ```python
 remove(s, p, o)
@@ -237,7 +251,7 @@ this `KnowledgeGraph` object – used for method chaining
 
 ---
 #### [`load_rdf_text` method](#kglab.KnowledgeGraph.load_rdf_text)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L541)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L558)
 
 ```python
 load_rdf_text(data, format="ttl", base=None, **args)
@@ -263,7 +277,7 @@ this `KnowledgeGraph` object – used for method chaining
 
 ---
 #### [`save_rdf` method](#kglab.KnowledgeGraph.save_rdf)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L584)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L601)
 
 ```python
 save_rdf(path, format="ttl", base=None, encoding="utf-8", **args)
@@ -287,7 +301,7 @@ optional text encoding value, defaults to `"utf-8"`, must be in the [Python code
 
 ---
 #### [`save_rdf_text` method](#kglab.KnowledgeGraph.save_rdf_text)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L649)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L666)
 
 ```python
 save_rdf_text(format="ttl", base=None, encoding="utf-8", **args)
@@ -333,7 +347,7 @@ this `KnowledgeGraph` object – used for method chaining
 
 ---
 #### [`save_jsonld` method](#kglab.KnowledgeGraph.save_jsonld)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L736)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L753)
 
 ```python
 save_jsonld(path, encoding="utf-8", **args)
@@ -373,7 +387,7 @@ this `KnowledgeGraph` object – used for method chaining
 
 ---
 #### [`save_parquet` method](#kglab.KnowledgeGraph.save_parquet)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L825)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L842)
 
 ```python
 save_parquet(path, compression="snappy", storage_options=None, **kwargs)
@@ -396,7 +410,7 @@ extra options parsed by [`fsspec`](https://github.com/intake/filesystem_spec) fo
 
 ---
 #### [`load_csv` method](#kglab.KnowledgeGraph.load_csv)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L870)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L887)
 
 ```python
 load_csv(url)
@@ -413,7 +427,7 @@ this `KnowledgeGraph` object – used for method chaining
 
 ---
 #### [`materialize` method](#kglab.KnowledgeGraph.materialize)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L891)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L908)
 
 ```python
 materialize(config)
@@ -458,7 +472,7 @@ a list of identifiers for the top-level nodes added from the Roam Research graph
 
 ---
 #### [`query` method](#kglab.KnowledgeGraph.query)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1021)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1038)
 
 ```python
 query(sparql, bindings=None)
@@ -478,7 +492,7 @@ initial variable bindings
 
 ---
 #### [`query_as_df` method](#kglab.KnowledgeGraph.query_as_df)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1049)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1066)
 
 ```python
 query_as_df(sparql, bindings=None, simplify=True, pythonify=True)
@@ -504,7 +518,7 @@ the query result set represented as a [`pandas.DataFrame`](https://pandas.pydata
 
 ---
 #### [`visualize_query` method](#kglab.KnowledgeGraph.visualize_query)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1093)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1110)
 
 ```python
 visualize_query(sparql, notebook=False)
@@ -524,7 +538,7 @@ PyVis network object, to be rendered
 
 ---
 #### [`n3fy` method](#kglab.KnowledgeGraph.n3fy)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1114)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1131)
 
 ```python
 n3fy(node, pythonify=True)
@@ -544,7 +558,7 @@ text (or Python objects) for the serialized node
 
 ---
 #### [`n3fy_row` method](#kglab.KnowledgeGraph.n3fy_row)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1140)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1157)
 
 ```python
 n3fy_row(row_dict, pythonify=True)
@@ -564,7 +578,7 @@ a dictionary of serialized row bindings
 
 ---
 #### [`validate` method](#kglab.KnowledgeGraph.validate)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1169)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1186)
 
 ```python
 validate(shacl_graph=None, shacl_graph_format=None, ont_graph=None, ont_graph_format=None, advanced=False, inference=None, inplace=True, abort_on_first=None, **kwargs)
@@ -601,7 +615,7 @@ a tuple of `conforms` (RDF graph passes the validation rules) + `report_graph` (
 
 ---
 #### [`infer_owlrl_closure` method](#kglab.KnowledgeGraph.infer_owlrl_closure)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1247)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1264)
 
 ```python
 infer_owlrl_closure()
@@ -614,7 +628,7 @@ See <https://wiki.uib.no/info216/index.php/Python_Examples#RDFS_inference_with_R
 
 ---
 #### [`infer_rdfs_closure` method](#kglab.KnowledgeGraph.infer_rdfs_closure)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1260)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1277)
 
 ```python
 infer_rdfs_closure()
@@ -627,7 +641,7 @@ See <https://wiki.uib.no/info216/index.php/Python_Examples#RDFS_inference_with_R
 
 ---
 #### [`infer_rdfs_properties` method](#kglab.KnowledgeGraph.infer_rdfs_properties)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1273)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1290)
 
 ```python
 infer_rdfs_properties()
@@ -640,7 +654,7 @@ Adapted from [`skosify`](https://github.com/NatLibFi/Skosify) which wasn't being
 
 ---
 #### [`infer_rdfs_classes` method](#kglab.KnowledgeGraph.infer_rdfs_classes)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1301)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1318)
 
 ```python
 infer_rdfs_classes()
@@ -653,7 +667,7 @@ Adapted from [`skosify`](https://github.com/NatLibFi/Skosify) which wasn't being
 
 ---
 #### [`infer_skos_related` method](#kglab.KnowledgeGraph.infer_skos_related)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1334)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1351)
 
 ```python
 infer_skos_related()
@@ -667,7 +681,7 @@ Adapted from [`skosify`](https://github.com/NatLibFi/Skosify) which wasn't being
 
 ---
 #### [`infer_skos_concept` method](#kglab.KnowledgeGraph.infer_skos_concept)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1349)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1366)
 
 ```python
 infer_skos_concept()
@@ -684,7 +698,7 @@ Adapted from [`skosify`](https://github.com/NatLibFi/Skosify) which wasn't being
 
 ---
 #### [`infer_skos_hierarchical` method](#kglab.KnowledgeGraph.infer_skos_hierarchical)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1373)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1390)
 
 ```python
 infer_skos_hierarchical(narrower=True)
@@ -701,7 +715,7 @@ if false, `skos:narrower` will be removed instead of added
 
 ---
 #### [`infer_skos_transitive` method](#kglab.KnowledgeGraph.infer_skos_transitive)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1400)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1417)
 
 ```python
 infer_skos_transitive(narrower=True)
@@ -722,7 +736,7 @@ also infer transitive closure for `skos:narrowerTransitive`
 
 ---
 #### [`infer_skos_symmetric_mappings` method](#kglab.KnowledgeGraph.infer_skos_symmetric_mappings)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1429)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1446)
 
 ```python
 infer_skos_symmetric_mappings(related=True)
@@ -739,7 +753,7 @@ infer the `skos:related` super-property for all `skos:relatedMatch` relations
 
 ---
 #### [`infer_skos_hierarchical_mappings` method](#kglab.KnowledgeGraph.infer_skos_hierarchical_mappings)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1460)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L1477)
 
 ```python
 infer_skos_hierarchical_mappings(narrower=True)

setup.py

@@ -113,13 +113,13 @@ def parse_requirements_file (
 
         url = "https://derwen.ai/docs/kgl/",
         project_urls = {
-            "Source Code": "https://github.com/DerwenAI/kglab",
-            "Issue Tracker": "https://github.com/DerwenAI/kglab/issues",
-            "Hands-on Tutorial": "https://derwen.ai/docs/kgl/tutorial/",
+            "DOI": "https://doi.org/10.5281/zenodo.6360664",
+            "Community Survey": "https://forms.gle/FMHgtmxHYWocprMn6",
             "Discussion Forum": "https://www.linkedin.com/groups/6725785/",
             "DockerHub": "https://hub.docker.com/r/derwenai/kglab",
-            "Community Survey": "https://forms.gle/FMHgtmxHYWocprMn6",
-            "DOI": "https://doi.org/10.5281/zenodo.4717287",
+            "Hands-on Tutorial": "https://derwen.ai/docs/kgl/tutorial/",
+            "Issue Tracker": "https://github.com/DerwenAI/kglab/issues",
+            "Source Code": "https://github.com/DerwenAI/kglab",
         },
 
         entry_points = {