Polish notes in notebooks on what runs with what (Model / Store) (#37)

* Add notes in notebooks on what runs with what (Model / Store) * Fix some of RdfModel failing tests * Address reviews
vishalbelsare · Jul 14, 2020 · 1f1c47b · 1f1c47b
1 parent 7e4d6c5
commit 1f1c47b
Show file tree

Hide file tree

Showing 13 changed files with 123 additions and 38 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ docs/build
 **/.ipynb_checkpoints/*
 version.py
 examples/notebooks/getting-started/mappings/
+examples/notebooks/getting-started/downloaded/
 .gitreview
 examples/configurations/forge.yml
 examples/models/neuroshapes/
diff --git a/examples/notebooks/getting-started/00 - Initialization.ipynb b/examples/notebooks/getting-started/00 - Initialization.ipynb
@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note: If you are on Binder, you don't need to execute the follwing command."
+    "Note: If you are on Binder, you don't need to execute the following command."
    ]
   },
   {

diff --git a/examples/notebooks/getting-started/02 - Datasets.ipynb b/examples/notebooks/getting-started/02 - Datasets.ipynb
@@ -166,7 +166,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(associations)"
@@ -290,7 +292,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(dataset)"
@@ -410,7 +414,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(dataset)"
@@ -498,7 +504,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(dataset)"

diff --git a/examples/notebooks/getting-started/04 - Querying.ipynb b/examples/notebooks/getting-started/04 - Querying.ipynb
@@ -209,15 +209,6 @@
     "jane_v1 == jane_v1_tag"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "print(jane_v1)"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -240,7 +231,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(resource)"
+    "resource is None"
    ]
   },
   {
@@ -254,7 +245,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note: DemoModel and RdfModel schemas have not been synchronized yet. This section is to be run with RdfModel."
+    "Note: DemoModel and RdfModel schemas have not been synchronized yet. This section is to be run with RdfModel. Commented lines are for DemoModel."
    ]
   },
   {
@@ -281,6 +272,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# association_jane = Resource(type=\"Association\", agent=jane)\n",
     "association_jane = Resource(type=\"Dataset\", contribution=jane)"
    ]
   },
@@ -290,6 +282,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# association_john = Resource(type=\"Association\", agent=john)\n",
     "association_john = Resource(type=\"Dataset\", contribution=john)"
    ]
   },
@@ -315,7 +308,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`Entity` is a known type by the Model, and the `paths` method will load the data structure for the given type. Refer to the `11 - Modeling.ipynb` notebook to learn about Modeling and Types."
+    "The `paths` method load the data structure for the given type.\n",
+    "\n",
+    "Please refer to the [Modeling.ipynb](11%20-%20Modeling.ipynb) notebook to learn about modeling and types."
    ]
   },
   {
@@ -324,6 +319,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# p = forge.paths(\"Association\")\n",
     "p = forge.paths(\"Dataset\")"
    ]
   },
@@ -334,12 +330,20 @@
     "You have autocompletion on `p` and this can be used to build a search."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: There is a known issue for RdfModel which requires using `p.type.id` instead of `p.type`."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
+    "# resources = forge.search(p.type == \"Association\")\n",
     "resources = forge.search(p.type.id == \"Dataset\", limit=3)"
    ]
   },
@@ -402,13 +406,21 @@
     "You have autocompletion on `p` but also on nested properties like `p.agent`."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: There is a known issue for RdfModel which prevents from searching on the name."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "resources = forge.search(p.type.id == \"Dataset\", p.contribution.name == \"John Smith\", limit=3)"
+    "# resources = forge.search(p.type == \"Association\", p.agent.name == \"John Smith\")\n",
+    "resources = forge.search(p.type.id == \"Dataset\", p.contribution.type == \"Person\", limit=3)"
    ]
   },
   {
@@ -423,10 +435,12 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
-    "print(resources[0])"
+    "forge.as_dataframe(resources)"
    ]
   },
   {
@@ -435,11 +449,27 @@
    "source": [
     "## Graph traversing\n",
     "\n",
-    "SPARQL is used to traverse the graph. The user can provide simplified queries: no prefixes, no compacted URIs, nor full URIs is required, only the term (property) available in the Model to the user.  Refer to the `11 - Modeling.ipynb` notebook to learn about Templates.\n",
+    "SPARQL is used as a query language.\n",
     "\n",
+    "A SPARQL query rewriting strategy lets users write simplified queries without using prefix declarations, prefix names or long IRIs. With this strategy, the user could only provides type and property names. For a given entity, these names could be seen in its template.\n",
+    "\n",
+    "Please refer to the [Modeling.ipynb](11%20-%20Modeling.ipynb) notebook to learn about templates."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "Note: DemoStore doesn't implement SPARQL operations yet. Please use another store for this section."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: DemoModel and RdfModel schemas have not been synchronized yet. This section is to be run with RdfModel. Commented lines are for DemoModel."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -464,6 +494,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# association = Resource(type=\"Association\", agent=[jane, john])\n",
     "association = Resource(type=\"Dataset\", contribution=[jane, john])"
    ]
   },
@@ -479,9 +510,12 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
+    "# forge.template(\"Association\")\n",
     "forge.template(\"Dataset\")"
    ]
   },
@@ -491,11 +525,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# query = \"\"\"\n",
+    "#     SELECT ?id ?name\n",
+    "#     WHERE {\n",
+    "#         ?id a Association ;\n",
+    "#             agent ?agent .\n",
+    "#         ?agent name ?name .\n",
+    "#     }\n",
+    "# \"\"\"\n",
     "query = \"\"\"\n",
-    "    SELECT ?x ?name\n",
+    "    SELECT ?id ?name\n",
     "    WHERE {\n",
-    "        ?x a Dataset ;\n",
-    "           contribution ?contributor .\n",
+    "        ?id a Dataset ;\n",
+    "            contribution ?contributor .\n",
     "        ?contributor name ?name .\n",
     "    }\n",
     "\"\"\""
@@ -537,6 +579,15 @@
     "type(resources[0])"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "forge.as_dataframe(resources)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -550,7 +601,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "forge.sparql(query, debug=True)"
+    "resources = forge.sparql(query, limit=3, debug=True)"
    ]
   },
   {

diff --git a/examples/notebooks/getting-started/05 - Versioning.ipynb b/examples/notebooks/getting-started/05 - Versioning.ipynb
@@ -219,7 +219,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(association)"
@@ -265,7 +267,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(association)"

diff --git a/examples/notebooks/getting-started/07 - DataFrame IO.ipynb b/examples/notebooks/getting-started/07 - DataFrame IO.ipynb
@@ -129,7 +129,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(john)"

diff --git a/examples/notebooks/getting-started/10 - Reshaping.ipynb b/examples/notebooks/getting-started/10 - Reshaping.ipynb
@@ -230,7 +230,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "print(jane)"

diff --git a/examples/notebooks/getting-started/11 - Modeling.ipynb b/examples/notebooks/getting-started/11 - Modeling.ipynb
@@ -410,6 +410,13 @@
     "### error handling"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: DemoModel and RdfModel schemas have not been synchronized yet. This section is to be run with RdfModel. Commented lines are for DemoModel."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -430,7 +437,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "resource = Resource(type=\"Entity\", agent=mistake)"
+    "# resource = Resource(type=\"Association\", agent=mistake)\n",
+    "resource = Resource(type=\"Dataset\", contribution=mistake)"
    ]
   },
   {

diff --git a/examples/notebooks/getting-started/12 - Mapping.ipynb b/examples/notebooks/getting-started/12 - Mapping.ipynb
@@ -107,6 +107,13 @@
     "### basics"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note: DemoModel and RdfModel schemas have not been synchronized yet. The following cell is to be run with DemoModel."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -262,7 +269,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note: RdfModel doesn't implement managed mappings operations yet. Please use another model for this section."
+    "Note: RdfModel doesn't implement managed mappings operations yet. Please use DemoModel for this section."
    ]
   },
   {
@@ -348,7 +355,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note: RdfModel doesn't implement managed mappings operations yet. Please use another model for this section."
+    "Note: RdfModel doesn't implement managed mappings operations yet. Please use DemoModel for this section."
    ]
   },
   {

diff --git a/examples/notebooks/getting-started/13 - JSON-LD IO.ipynb b/examples/notebooks/getting-started/13 - JSON-LD IO.ipynb
@@ -134,7 +134,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "pp(forge.as_jsonld(jane))"