{ "cells": [ { "cell_type": "markdown", "id": "43a96960-2d31-4489-8582-b6ae07a4c133", "metadata": {}, "source": [ "# Working with a Convention\n", "\n", "This section will take you through the steps of using, hence you are very likely a pure user in the project as defined before.\n", "\n", "We'll be using the built-in convention \"h5tbx\":" ] }, { "cell_type": "code", "execution_count": 1, "id": "6f7c1069-7603-4dc9-8367-c58e2d3a7f77", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "using(\"h5tbx\")" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from h5rdmtoolbox import convention\n", "import h5rdmtoolbox as h5tbx\n", "\n", "h5tbx.use('h5tbx')" ] }, { "cell_type": "markdown", "id": "b2efa609-b122-4ed5-ab78-36d26e90a955", "metadata": {}, "source": [ "Without checking which attributes are standardized, let's try to create a dataset in a new file:" ] }, { "cell_type": "code", "execution_count": 2, "id": "8bd409fa-63a3-4de5-93d3-eedf1c5897cf", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Convention \"h5tbx\" expects standard attribute \"units\" to be provided as an argument during dataset creation.\n" ] } ], "source": [ "with h5tbx.File() as h5:\n", " try:\n", " h5.create_dataset('ds', shape=(3, ))\n", " except convention.errors.StandardAttributeError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "id": "7ba067be-37e9-45a1-bba0-0cf667a7f83a", "metadata": {}, "source": [ "The error message tells us, that (at least) \"units\" is missing. So it is time to check which other standard attributes are defined in the convention. The easiest is to print the convention object.\n", "\n", "The string representation of the `Convention` objects tells us which attributes are expected for which method. In this example, the following is defined:\n", "- For the **root group**, indicated by `File.__init__()`: \"creation_mode\"\n", "- For any dataset, indicated by `Group.create_dataset()`: \"units\" and \"symbol\". *Note that units is obligatory and \"symbol\" is optional*\n", "\n", "This means, that we *can* provide \"creation_mode\" during file creation and we *must* provide the attribute \"units\" during dataset creation. We will test this in the next section." ] }, { "cell_type": "code", "execution_count": 3, "id": "bb8c6fb7-1e23-466b-971e-296da4994fda", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1mConvention(\"h5tbx\")\u001b[0m\n", "contact: https://orcid.org/0000-0001-8729-0482\n", " File.__init__():\n", " * \u001b[3mcreation_mode\u001b[0m:\n", "\t\tCreation mode of the data. Specific for engineering.\n", " Group.create_dataset():\n", " * \u001b[1munits (obligatory)\u001b[0m :\n", "\t\tThe physical unit of the dataset. If dimensionless, the unit is ''.\n", " * \u001b[3msymbol\u001b[0m:\n", "\t\tThe mathematical symbol of the dataset.\n", "\n" ] } ], "source": [ "cv = convention.get_current_convention()\n", "print(cv)" ] }, { "cell_type": "markdown", "id": "c5df8aca-6278-4a54-84bb-47168ebf253c", "metadata": {}, "source": [ "But there is more to it: Standard attributes **validate the values**! Let's now pass the attribute \"units\" but purposely set an invalid value. Normally, we can set any value to attributes. But standard attributes can have a validator implemented. This is the case for the attribute \"units\". We will find out later how this is done." ] }, { "cell_type": "code", "execution_count": 4, "id": "28288ca8-b35b-4b7f-88c8-ada348118f01", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Validation of \"invalid\" for standard attribute \"units\" failed.\n", "Pydantic error: 1 validation error for units\n", "value\n", " Parameter error, Units cannot be understood using ureg package: invalid. Original error: 'invalid' is not defined in the unit registry [type=value_error, input_value='invalid', input_type=str]\n", " For further information visit https://errors.pydantic.dev/2.5/v/value_error\n" ] } ], "source": [ "with h5tbx.File() as h5:\n", " try:\n", " h5.create_dataset('ds', shape=(3, ), units='invalid')\n", " except convention.errors.StandardAttributeError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "id": "779a589b-e9c1-4b15-a2be-c76f7f4df593", "metadata": {}, "source": [ "The error tells us, that \"invalid\" is not understood by the validator.\n", "\n", "Finally, we provide a valid SI unit:" ] }, { "cell_type": "code", "execution_count": 5, "id": "58a9c16b-979c-4b4f-a356-18b2fcae5789", "metadata": {}, "outputs": [], "source": [ "with h5tbx.File() as h5:\n", " h5.create_dataset('ds', shape=(3, ), units='m/s')" ] }, { "cell_type": "markdown", "id": "35127696-965d-40e4-b93a-eb87be4f3ddf", "metadata": {}, "source": [ "We can also access all registered standard attributes of the convention like so:" ] }, { "cell_type": "code", "execution_count": 6, "id": "ff5b898a-14f9-4b52-a3a5-84671a3f3359", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'creation_mode': ,\n", " 'symbol': ,\n", " 'units': }\n" ] } ], "source": [ "from pprint import pprint\n", "pprint(cv.registered_standard_attributes)" ] }, { "cell_type": "markdown", "id": "c424b007-c22c-423b-8133-f10790c49d6b", "metadata": {}, "source": [ "To find out how to create a new convention, please go to the [next section](./creating_a_new_convention.ipynb)." ] }, { "cell_type": "code", "execution_count": null, "id": "253f073b-abe4-4ea2-9973-4d944083cae1", "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.8.19" } }, "nbformat": 4, "nbformat_minor": 5 }