Skip to content

Commit df8526e

Browse files
kysrpexkysrpex
authored
Merge pull request #159 from simphony/dev
Merge sprint #3.
2 parents 7482140 + d163205 commit df8526e

File tree

12 files changed

+359
-24
lines changed

12 files changed

+359
-24
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/fundamentals.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ CUDS, or Common Universal Data Structure, is the ontology compliant data format
139139
- **CUDS is an ontology individual**: each CUDS object is an instantiation of a class in the ontology.
140140
If we assume a food ontology that describes classes like pizza or pasta, a CUDS object could represent one specific pizza or pasta dish, that exists in the real world.
141141
Similar to ontology individuals, CUDS objects can be related with other individuals/CUDS by relations defined in the ontology. Like a _pizza_ that 'hasPart' _tomato sauce_
142-
- **CUDS is API**: To allow users to interact with the ontology individuals and their data, CUDS provide a CRUD API.
142+
- **CUDS is API**: To allow users to interact with the ontology individuals and their data, CUDS provides a CRUD API.
143143
- **CUDS is a container**: Depending on the relationship connecting two CUDS objects, a certain instance can be seen as a container of other instances.
144144
We call a relationship that express containment an 'active relationship'.
145145
In the pizza example, 'hasPart' would be an 'active relationship'. If one would like to share the pizza CUDS object with others, one would like to share also the tomato sauce.

‎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+
}

‎docs/source/jupyter/ontology_interface.ipynb‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,28 @@
201201
"- When the keyword `reference_by_label` is set to `False` (disabled) or not set, the dot notation is a shorthand for fetching by suffix instead. This keyword is **disabled** in the `city` namespace."
202202
]
203203
},
204+
{
205+
"cell_type": "markdown",
206+
"metadata": {},
207+
"source": [
208+
"To get a list of all the entities available within a namespace, run `list(namespace)`."
209+
]
210+
},
211+
{
212+
"cell_type": "markdown",
213+
"metadata": {},
214+
"source": [
215+
"<div style=\"background: #D3D3D3\">\n",
216+
"<div class=\"admonition important\" style=\"padding: 6px 12px\">\n",
217+
"<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Tip</div></div>\n",
218+
" \n",
219+
"The dot notation supports IPython autocompletion. For example, when working on a Jupyter notebook, once the namespace has been imported, it is possible to get suggestions for the entity names by writing <code class=\"pre\">`namespace.`</code> and pressing TAB.\n",
220+
"\n",
221+
"</div>\n",
222+
"</div>\n",
223+
"</div>"
224+
]
225+
},
204226
{
205227
"cell_type": "markdown",
206228
"metadata": {},

‎docs/source/links.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,8 @@ The following table describes the compatibilities between of SimPhoNy docs and O
4848
============= ==========
4949
SimPhoNy docs OSP-core
5050
============= ==========
51-
2.4.x 3.5.2-beta
51+
2.4.1 3.5.3.1-beta
52+
2.4.0 3.5.2-beta
5253
2.3.x 3.4.0-beta
5354
2.2.x 3.3.5-beta
5455
2.1.x 3.3.0-beta

0 commit comments

Comments
 (0)