{ "cells": [ { "cell_type": "markdown", "id": "0694f7a3-0067-430c-809b-356296f40df7", "metadata": {}, "source": [ "# Standard Name" ] }, { "cell_type": "code", "execution_count": 1, "id": "4ea80d82-7157-4d6f-b86d-ea8735353447", "metadata": {}, "outputs": [], "source": [ "import ssnolib" ] }, { "cell_type": "markdown", "id": "4ba9ae64-28d0-49e3-90af-615354333769", "metadata": {}, "source": [ "## Create a standard name\n", "\n", "As a minimum, `standard_name`, `unit` and `description` must be provided. You can also assign the standard name table, it is associated with. Let's start with the core properties, though:" ] }, { "cell_type": "code", "execution_count": 2, "id": "90e8645c-e92c-4dc9-80c2-0878d95ae1bd", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "@prefix ssno: .\n", "\n", "[] a ssno:StandardName ;\n", " ssno:description \"Die Geschwindigeit in x-Richtung des Koordinatensystems.\"@de,\n", " \"The velocity in x-axis direction.\"@en ;\n", " ssno:standardName \"x_velocity\" ;\n", " ssno:unit .\n", "\n", "\n" ] } ], "source": [ "sn = ssnolib.StandardName(\n", " standardName='x_velocity',\n", " unit='m/s',\n", " description=['The velocity in x-axis direction.@en', 'Die Geschwindigeit in x-Richtung des Koordinatensystems.@de']\n", ")\n", "print(sn.serialize(format=\"ttl\"))" ] }, { "cell_type": "markdown", "id": "38a434b1-5db5-4fee-b9f5-f22f55882c0a", "metadata": {}, "source": [ "We automatically get an ID assigned, with is a blank URI:" ] }, { "cell_type": "code", "execution_count": 3, "id": "3aa16432-872d-4ace-b100-107f14f5f063", "metadata": {}, "outputs": [ { "data": { "text/html": [ "StandardName(id=_:N9c18868e08504b1c874767e9516fa6fe, standardName=x_velocity, unit=http://qudt.org/vocab/unit/M-PER-SEC, description=[LangString(value='The velocity in x-axis direction.', lang='en'), LangString(value='Die Geschwindigeit in x-Richtung des Koordinatensystems.', lang='de')])" ], "text/plain": [ "StandardName(id=_:N9c18868e08504b1c874767e9516fa6fe, standardName=x_velocity, unit=http://qudt.org/vocab/unit/M-PER-SEC, description=[LangString(value='The velocity in x-axis direction.', lang='en'), LangString(value='Die Geschwindigeit in x-Richtung des Koordinatensystems.', lang='de')])" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "sn" ] }, { "cell_type": "markdown", "id": "9aed31d9-b0bc-4004-80c5-cc6277f71dfa", "metadata": {}, "source": [ "## Aliases" ] }, { "cell_type": "markdown", "id": "5a839249-e4d4-4e73-a031-e62f44f22178", "metadata": {}, "source": [ "Note, that we used the field names according to the URI of the ontology. E.g. we used \"standardName\" for \"https://matthiasprobst.github.io/ssno#standardName\" and \"unit\" for \"\"https://matthiasprobst.github.io/ssno#unit\". However, this is unusual syntax for *pythonic* naming. In Python, we prefer using lowercase with underscores (snake_case) for variable names, whereas the ontology preferred camelCase. As The Python object connects both worlds, both versions are allowed to be used interchangible:" ] }, { "cell_type": "code", "execution_count": 4, "id": "b8b9423d-2e96-40fb-a8ea-53195e01ea76", "metadata": {}, "outputs": [ { "data": { "text/html": [ "StandardName(id=_:N1fe2fa066aa249b7a82c6b1bbfe5cbd6, standardName=x_velocity, unit=http://qudt.org/vocab/unit/M-PER-SEC, description=The velocity in x-axis direction)" ], "text/plain": [ "StandardName(id=_:N1fe2fa066aa249b7a82c6b1bbfe5cbd6, standardName=x_velocity, unit=http://qudt.org/vocab/unit/M-PER-SEC, description=The velocity in x-axis direction)" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "sn = ssnolib.StandardName(\n", " standard_name='x_velocity',\n", " unit='m/s',\n", " description='The velocity in x-axis direction'\n", ")\n", "sn" ] }, { "cell_type": "markdown", "id": "05485515-768b-4121-917a-3d4a0c1adae6", "metadata": {}, "source": [ "Side note: Invalid fields are not allowed and are reported:" ] }, { "cell_type": "code", "execution_count": 5, "id": "f4efa3a8-7bf8-482f-9336-947c6b3eaf27", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2 validation errors for StandardName\n", "standard_name\n", " Field required [type=missing, input_value={'name': 'x_velocity', 'u...in x-axis direction@en'}, input_type=dict]\n", " For further information visit https://errors.pydantic.dev/2.10/v/missing\n", "unit\n", " Field required [type=missing, input_value={'name': 'x_velocity', 'u...in x-axis direction@en'}, input_type=dict]\n", " For further information visit https://errors.pydantic.dev/2.10/v/missing\n" ] } ], "source": [ "import pydantic\n", "try:\n", " sn = ssnolib.StandardName(\n", " name='x_velocity',\n", " units='m/s',\n", " description='The velocity in x-axis direction@en'\n", " )\n", "except pydantic.ValidationError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "id": "115aff9a-1a8a-4287-8869-402153674685", "metadata": {}, "source": [ "## Validation\n", "\n", "Fields are validated by their types and sometimes downstream validator functions. This means, that it is not possible to assign an integer to the definition. The standard name is validated mostly using regex. The units value is translated to a URI using the [QUDT](https://qudt.org/) ontology. Here are some examples:" ] }, { "cell_type": "code", "execution_count": 6, "id": "d83f0d1a-37ef-4596-95a2-d68a80707ed9", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "2 validation errors for StandardName\n", "description.LangString\n", " Input should be a valid dictionary or instance of LangString [type=model_type, input_value=123, input_type=int]\n", " For further information visit https://errors.pydantic.dev/2.10/v/model_type\n", "description.list[LangString]\n", " Input should be a valid list [type=list_type, input_value=123, input_type=int]\n", " For further information visit https://errors.pydantic.dev/2.10/v/list_type\n" ] } ], "source": [ "# Wrong type for definition:\n", "try:\n", " sn = ssnolib.StandardName(\n", " standard_name='x_velocity',\n", " unit='m/s',\n", " description=123\n", " )\n", "except pydantic.ValidationError as e:\n", " print(e)" ] }, { "cell_type": "code", "execution_count": 7, "id": "d83e315a-bc4e-4665-9fac-dfacc0ee60c2", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "1 validation error for StandardName\n", "standard_name\n", " Value error, Invalid standard name 'X_velocity_' according to the core pattern '^[a-z0-9]+(?:_[a-z0-9]+)*$'. [type=value_error, input_value='X_velocity_', input_type=str]\n", " For further information visit https://errors.pydantic.dev/2.10/v/value_error\n" ] } ], "source": [ "# Incorrect standard name that does not match the basic pattern:\n", "try:\n", " sn = ssnolib.StandardName(\n", " standard_name='X_velocity_',\n", " unit='m/s',\n", " description=\"invalid standard name\"\n", " )\n", "except pydantic.ValidationError as e:\n", " print(e)" ] }, { "cell_type": "code", "execution_count": 8, "id": "3ef6eb35-bd80-40a2-a21f-17e8e69acf33", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "1 validation error for StandardName\n", "unit.unit\n", " Value error, your_message Unable to parse: \"meterprosec\" of standard name \"x_velocity\" [type=value_error, input_value='meterprosec', input_type=str]\n", " For further information visit https://errors.pydantic.dev/2.10/v/value_error\n" ] } ], "source": [ "# Cannot parse unit\n", "try:\n", " sn = ssnolib.StandardName(\n", " standard_name='x_velocity',\n", " unit='meterprosec',\n", " description=\"invalid standard name\"\n", " )\n", "except pydantic.ValidationError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "id": "20887de4-dc48-4f45-b5cc-495655898431", "metadata": {}, "source": [ "## Representations\n", "\n", "A standard name object can be represented in various formats, such as TTL (turtle), XML or JSON-LD (or any serialization defined by `rdflib`, which is used under the hood, see [here for more](https://rdflib.readthedocs.io/en/stable/plugin_serializers.html))" ] }, { "cell_type": "markdown", "id": "19d9a552-fbbc-4095-8002-4b04c0dd4466", "metadata": {}, "source": [ "### TTL/Turtle" ] }, { "cell_type": "code", "execution_count": 9, "id": "b05e551f-9cf6-41aa-9d1a-ed0e2888cc68", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "@prefix ssno: .\n", "\n", "[] a ssno:StandardName ;\n", " ssno:description \"The velocity in x-axis direction\" ;\n", " ssno:standardName \"x_velocity\" ;\n", " ssno:unit .\n", "\n", "\n" ] } ], "source": [ "print(sn.serialize(format=\"ttl\"))" ] }, { "cell_type": "markdown", "id": "7719491c-1670-4bd5-b97f-d6353aeb90ea", "metadata": {}, "source": [ "### XML" ] }, { "cell_type": "code", "execution_count": 10, "id": "f3114e62-8553-4e58-ac9d-28ac2b1eac0d", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "\n", " \n", " \n", " x_velocity\n", " \n", " The velocity in x-axis direction\n", " \n", "\n", "\n" ] } ], "source": [ "print(sn.serialize(format=\"xml\"))" ] }, { "cell_type": "markdown", "id": "4cc3fe47-6707-4b4a-9a4e-2a190e724557", "metadata": {}, "source": [ "### JSON-LD" ] }, { "cell_type": "code", "execution_count": 11, "id": "ae3a9df3-b98d-4f3b-9afd-85d4b65bb9a4", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"@context\": {\n", " \"dcat\": \"http://www.w3.org/ns/dcat#\",\n", " \"dcterms\": \"http://purl.org/dc/terms/\",\n", " \"owl\": \"http://www.w3.org/2002/07/owl#\",\n", " \"rdfs\": \"http://www.w3.org/2000/01/rdf-schema#\",\n", " \"schema\": \"https://schema.org/\",\n", " \"skos\": \"http://www.w3.org/2004/02/skos/core#\",\n", " \"ssno\": \"https://matthiasprobst.github.io/ssno#\"\n", " },\n", " \"@id\": \"_:N1fe2fa066aa249b7a82c6b1bbfe5cbd6\",\n", " \"@type\": \"ssno:StandardName\",\n", " \"ssno:description\": \"The velocity in x-axis direction\",\n", " \"ssno:standardName\": \"x_velocity\",\n", " \"ssno:unit\": {\n", " \"@id\": \"http://qudt.org/vocab/unit/M-PER-SEC\"\n", " }\n", "}\n" ] } ], "source": [ "print(sn.serialize(format=\"json-ld\"))" ] }, { "cell_type": "code", "execution_count": null, "id": "3015b634-7b18-4c35-8b93-f040ea4f6d43", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.11" } }, "nbformat": 4, "nbformat_minor": 5 }