Skip to content

Commit d163205

Browse files
yoavnashyoavnash
authored
Merge pull request #155 from simphony/147-Tutorial_for_RDF_import/export
Tutorial for RDF import/export
2 parents 1293160 + b9ea512 commit d163205

File tree

3 files changed

+323
-14
lines changed

3 files changed

+323
-14
lines changed

‎docs/source/api_ref.md‎

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -81,18 +81,7 @@ This document is for developers and/or advanced users of OSP-core, it contains a
8181

8282
## Utilities
8383
```eval_rst
84-
.. autoclass:: osp.core.utils.cuds2dot.Cuds2dot
85-
:members:
86-
87-
.. automodule:: osp.core.utils.general
88-
:members:
89-
90-
.. automodule:: osp.core.utils.pretty_print
91-
:members:
92-
93-
.. automodule:: osp.core.utils.simple_search
94-
:members:
95-
96-
.. automodule:: osp.core.utils.wrapper_development
97-
:members:
84+
.. automodule:: osp.core.utils
85+
:imported-members:
86+
:members:
9887
```

‎docs/source/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ SimPhoNy is an ontology-based [open-source](./license.md) Python framework that
8181
jupyter/sessions_and_vars.ipynb
8282
utils.md
8383
jupyter/multiple_wrappers.ipynb
84+
jupyter/import_export.ipynb
8485
jupyter/simlammps.ipynb
8586
jupyter/quantum_espresso.ipynb
8687

‎docs/source/jupyter/import_export.ipynb‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "boxed-professional",
6+
"metadata": {},
7+
"source": [
8+
"# Tutorial: Import and export"
9+
]
10+
},
11+
{
12+
"cell_type": "markdown",
13+
"id": "operational-honey",
14+
"metadata": {},
15+
"source": [
16+
"<figure style=\"display: table; text-align:center; margin-left: auto; margin-right:auto\">\n",
17+
" \n",
18+
"[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/master?filepath=docs%2Fsource%2Fjupyter%2Fimport_export.ipynb \"Click to run the tutorial yourself!\")\n",
19+
" \n",
20+
"</figure>\n",
21+
"\n",
22+
"In this tutorial we will be covering the import and export capabilities of OSP-core. The utility functions that provide these functionalities are `import_cuds` and `export_cuds`, respectively."
23+
]
24+
},
25+
{
26+
"cell_type": "markdown",
27+
"id": "qualified-works",
28+
"metadata": {},
29+
"source": [
30+
"<div class=\"admonition important\">\n",
31+
"<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Tip</div></div>\n",
32+
" \n",
33+
"The full API specifictions of the import and export functions can be found in the\n",
34+
"[utilities API reference page](../api_ref.html#osp.core.utils.export_cuds).\n",
35+
" \n",
36+
"</div>\n",
37+
"</div>\n"
38+
]
39+
},
40+
{
41+
"cell_type": "markdown",
42+
"id": "driving-injury",
43+
"metadata": {},
44+
"source": [
45+
"For our running example, we'll be using the *city ontology* that was already introduces in the [cuds API tutorial](./cuds_api.html). First, make sure the city ontology is installed. If not, run the following command:"
46+
]
47+
},
48+
{
49+
"cell_type": "code",
50+
"execution_count": 1,
51+
"id": "dying-accreditation",
52+
"metadata": {},
53+
"outputs": [
54+
{
55+
"name": "stderr",
56+
"output_type": "stream",
57+
"text": [
58+
"INFO 2021-05-31 10:55:51,839 [osp.core.ontology.installation]: Will install the following namespaces: ['city']\n",
59+
"INFO 2021-05-31 10:55:51,879 [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file c:\\users\\yoav\\anaconda3\\envs\\osp\\lib\\site-packages\\osp\\core\\ontology\\docs\\city.ontology.yml\n",
60+
"INFO 2021-05-31 10:55:51,995 [osp.core.ontology.yml.yml_parser]: You can now use `from osp.core.namespaces import city`.\n",
61+
"INFO 2021-05-31 10:55:51,996 [osp.core.ontology.parser]: Loaded 7396 ontology triples in total\n",
62+
"INFO 2021-05-31 10:55:52,437 [osp.core.ontology.installation]: Installation successful\n"
63+
]
64+
}
65+
],
66+
"source": [
67+
"!pico install city"
68+
]
69+
},
70+
{
71+
"cell_type": "markdown",
72+
"id": "lonely-listening",
73+
"metadata": {},
74+
"source": [
75+
"Next we create a few CUDS objects:"
76+
]
77+
},
78+
{
79+
"cell_type": "code",
80+
"execution_count": 2,
81+
"id": "considered-leonard",
82+
"metadata": {},
83+
"outputs": [
84+
{
85+
"data": {
86+
"text/plain": [
87+
"<city.Citizen: 98f8ac8c-713d-4406-bc36-e0152f9e2ea3, CoreSession: @0x221b0a05250>"
88+
]
89+
},
90+
"execution_count": 2,
91+
"metadata": {},
92+
"output_type": "execute_result"
93+
}
94+
],
95+
"source": [
96+
"from osp.core.namespaces import city\n",
97+
"\n",
98+
"c = city.City(name=\"Freiburg\", coordinates=[47, 7])\n",
99+
"p1 = city.Citizen(name=\"Peter\")\n",
100+
"p2 = city.Citizen(name=\"Anne\")\n",
101+
"c.add(p1, rel=city.hasInhabitant)\n",
102+
"c.add(p2, rel=city.hasInhabitant)"
103+
]
104+
},
105+
{
106+
"cell_type": "markdown",
107+
"id": "worth-province",
108+
"metadata": {},
109+
"source": [
110+
"Now we can use the `export_cuds` methods to export the data into a file:"
111+
]
112+
},
113+
{
114+
"cell_type": "code",
115+
"execution_count": 3,
116+
"id": "monthly-anxiety",
117+
"metadata": {},
118+
"outputs": [],
119+
"source": [
120+
"from osp.core.utils import export_cuds\n",
121+
"\n",
122+
"export_cuds(c, file='./data.ttl', format='turtle')"
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"id": "determined-nursing",
128+
"metadata": {},
129+
"source": [
130+
"This will create the file `data.ttl` with the following content:"
131+
]
132+
},
133+
{
134+
"cell_type": "code",
135+
"execution_count": 4,
136+
"id": "outstanding-wound",
137+
"metadata": {},
138+
"outputs": [
139+
{
140+
"name": "stdout",
141+
"output_type": "stream",
142+
"text": [
143+
"@prefix city: <http://www.osp-core.com/city#> .\n",
144+
"@prefix cuba: <http://www.osp-core.com/cuba#> .\n",
145+
"@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .\n",
146+
"@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n",
147+
"\n",
148+
"cuba:_serialization rdf:first \"47398674-720b-4765-9047-b5351ed175c0\" .\n",
149+
"\n",
150+
"<http://www.osp-core.com/cuds#8a90e2b3-7cca-4103-9eba-aab55e5903b1> a city:Citizen ;\n",
151+
" city:INVERSE_OF_hasInhabitant <http://www.osp-core.com/cuds#47398674-720b-4765-9047-b5351ed175c0> ;\n",
152+
" city:age 25 ;\n",
153+
" city:name \"Peter\" .\n",
154+
"\n",
155+
"<http://www.osp-core.com/cuds#98f8ac8c-713d-4406-bc36-e0152f9e2ea3> a city:Citizen ;\n",
156+
" city:INVERSE_OF_hasInhabitant <http://www.osp-core.com/cuds#47398674-720b-4765-9047-b5351ed175c0> ;\n",
157+
" city:age 25 ;\n",
158+
" city:name \"Anne\" .\n",
159+
"\n",
160+
"<http://www.osp-core.com/cuds#47398674-720b-4765-9047-b5351ed175c0> a city:City ;\n",
161+
" city:coordinates \"[47, 7]\"^^<http://www.osp-core.com/cuba#_datatypes/VECTOR-INT-2> ;\n",
162+
" city:hasInhabitant <http://www.osp-core.com/cuds#8a90e2b3-7cca-4103-9eba-aab55e5903b1>,\n",
163+
" <http://www.osp-core.com/cuds#98f8ac8c-713d-4406-bc36-e0152f9e2ea3> ;\n",
164+
" city:name \"Freiburg\" .\n",
165+
"\n"
166+
]
167+
}
168+
],
169+
"source": [
170+
"from sys import platform\n",
171+
"\n",
172+
"if platform == 'win32':\n",
173+
" !more data.ttl\n",
174+
"else:\n",
175+
" !cat data.ttl"
176+
]
177+
},
178+
{
179+
"cell_type": "markdown",
180+
"id": "offshore-cotton",
181+
"metadata": {},
182+
"source": [
183+
"You can change the format by entering a different value for the parameter `format`. The supported formats are “xml”, “n3”, “turtle”, “nt”, “pretty-xml”, “trix”, “trig” and “nquads”."
184+
]
185+
},
186+
{
187+
"cell_type": "markdown",
188+
"id": "derived-advancement",
189+
"metadata": {},
190+
"source": [
191+
"To import data, we can use the `import` method. Let's assume we wish to import data into an SQLite session. The following code will help us to achieve our aim:"
192+
]
193+
},
194+
{
195+
"cell_type": "code",
196+
"execution_count": 5,
197+
"id": "stable-session",
198+
"metadata": {},
199+
"outputs": [],
200+
"source": [
201+
"from osp.wrappers.sqlite import SqliteSession\n",
202+
"from osp.core.utils import import_cuds\n",
203+
"\n",
204+
"with SqliteSession(\"test.db\") as session:\n",
205+
" wrapper = city.CityWrapper(session=session)\n",
206+
" c = import_cuds('./data.ttl')\n",
207+
" wrapper.add(c)\n",
208+
" session.commit()"
209+
]
210+
},
211+
{
212+
"cell_type": "markdown",
213+
"id": "higher-short",
214+
"metadata": {},
215+
"source": [
216+
"Now we can verify the data was indeed imported:"
217+
]
218+
},
219+
{
220+
"cell_type": "code",
221+
"execution_count": 6,
222+
"id": "suspended-albert",
223+
"metadata": {},
224+
"outputs": [
225+
{
226+
"name": "stdout",
227+
"output_type": "stream",
228+
"text": [
229+
"- Cuds object:\n",
230+
" uid: 03015cb9-f88c-4ab1-9df9-bb52743b99de\n",
231+
" type: city.CityWrapper\n",
232+
" superclasses: city.CityWrapper, cuba.Entity, cuba.Wrapper\n",
233+
" description: \n",
234+
" To Be Determined\n",
235+
"\n",
236+
" |_Relationship city.hasPart:\n",
237+
" - city.City cuds object named <Freiburg>:\n",
238+
" . uid: 72595bc4-1b68-46a3-97e9-8f3de2650f2c\n",
239+
" . coordinates: [47 7]\n",
240+
" . |_Relationship city.hasInhabitant:\n",
241+
" . - city.Citizen cuds object named <Anne>:\n",
242+
" . . uid: 92a00459-0927-438c-a305-a26512ac7f03\n",
243+
" . . age: 25\n",
244+
" . - city.Citizen cuds object named <Peter>:\n",
245+
" . uid: 27d1e83b-4ee9-4f4f-adb5-0b01a3cc2c1b\n",
246+
" . age: 25\n",
247+
" - city.City cuds object named <Freiburg>:\n",
248+
" . uid: 47398674-720b-4765-9047-b5351ed175c0\n",
249+
" . coordinates: [47 7]\n",
250+
" . |_Relationship city.hasInhabitant:\n",
251+
" . - city.Citizen cuds object named <Anne>:\n",
252+
" . . uid: 98f8ac8c-713d-4406-bc36-e0152f9e2ea3\n",
253+
" . . age: 25\n",
254+
" . - city.Citizen cuds object named <Peter>:\n",
255+
" . uid: 8a90e2b3-7cca-4103-9eba-aab55e5903b1\n",
256+
" . age: 25\n",
257+
" - city.City cuds object named <Freiburg>:\n",
258+
" uid: d886f8ce-1326-40f5-a98b-c4c893b8c085\n",
259+
" coordinates: [47 7]\n",
260+
" |_Relationship city.hasInhabitant:\n",
261+
" - city.Citizen cuds object named <Anne>:\n",
262+
" . uid: 2b5d0a3f-81a5-4746-aab9-40adcb65e71f\n",
263+
" . age: 25\n",
264+
" - city.Citizen cuds object named <Peter>:\n",
265+
" uid: 766b320a-7e9a-43ec-a696-96b4f9ee494d\n",
266+
" age: 25\n"
267+
]
268+
}
269+
],
270+
"source": [
271+
"from osp.core.utils import pretty_print\n",
272+
"\n",
273+
"with SqliteSession(\"test.db\") as session:\n",
274+
" wrapper = city.CityWrapper(session=session)\n",
275+
" pretty_print(wrapper) "
276+
]
277+
},
278+
{
279+
"cell_type": "markdown",
280+
"id": "virgin-river",
281+
"metadata": {},
282+
"source": [
283+
"<div class=\"admonition important\">\n",
284+
"<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Notes</div></div>\n",
285+
" \n",
286+
"1. The format is automatically inferred from the file extension. To specify it explicitly, you can add the `format` parameter, like so: `import_cuds('./data.ttl', format='turtle')`.\n",
287+
"1. The `session` parameter is optional and inferred automatically from the context that created by the `with` statement (see the [tutorial on multiple wrappers](./multiple_wrappers.html) for more information). You can specify the session explicitly like so: `import_cuds('./data.ttl', session=session)`.\n",
288+
" \n",
289+
"</div>"
290+
]
291+
}
292+
],
293+
"metadata": {
294+
"kernelspec": {
295+
"display_name": "Python 3.7.4 64-bit",
296+
"language": "python",
297+
"name": "python37464bit7e5bfc198a4544d1be12f13215aed90d"
298+
},
299+
"language_info": {
300+
"codemirror_mode": {
301+
"name": "ipython",
302+
"version": 3
303+
},
304+
"file_extension": ".py",
305+
"mimetype": "text/x-python",
306+
"name": "python",
307+
"nbconvert_exporter": "python",
308+
"pygments_lexer": "ipython3",
309+
"version": "3.8.5"
310+
},
311+
"metadata": {
312+
"interpreter": {
313+
"hash": "301cd6007de04cbbf15bca26f0bc1cb48004d089278091d760363de622bdd0c8"
314+
}
315+
}
316+
},
317+
"nbformat": 4,
318+
"nbformat_minor": 5
319+
}

0 commit comments

Comments
 (0)