diff --git a/docs/source/api_metadata.rst b/docs/source/api_metadata.rst deleted file mode 100644 index 2cfb702d..00000000 --- a/docs/source/api_metadata.rst +++ /dev/null @@ -1,70 +0,0 @@ -============================== -API Documentation for Metadata -============================== - -The model for storing metadata is largely equivalent to the `odML`_ (open metadata Markup Laguage) model. In brief: the -model consists of so called Properties that contain Values much like a key-value pair (plus some additional fields). -These Properties can be grouped into Sections which themselves can be nested to built a tree-structure. Sections are -defined by a name and a type (e.g. a stimulus-type section will contain information that is related to a stimulus). -The basic feature of the odML approach is that it defines the model but not the items that are described or the terms -that are used in this. On the other hand where standardization is required each Section can be based on an -odML-terminology that standardizes without restricting to the terms defined within the terminology. - -.. _odML: http://www.frontiersin.org/Neuroinformatics/10.3389/fninf.2011.00016 - -Section -======= - -Metadata stored in a NIX file can be accessed directly from an open file. - -Create and delete sub sections ------------------------------- - -.. code-block:: python - :linenos: - - sub = section.create_section("a name", "type") - del section.sections[sub] - -Add and remove properties -------------------------- - -Properties can be created using the create_property method. Existing properties can be accessed and deleted -directly from the respective section. - -.. code-block:: python - :linenos: - - section.create_property("one", [1]) - section.create_property("two", [2]) - - # iterate over properties - for p in section: - print(p) - - # access by name - one = section["one"] - - # convert properties into a dict - dct = dict(section.items()) - - # delete properties - del section["one"] - del section["two"] - -Section API ------------ - -.. autoclass:: nixio.Section - :members: - :inherited-members: - :undoc-members: - -Property -======== - -.. autoclass:: nixio.Property - :members: - :inherited-members: - :undoc-members: - diff --git a/docs/source/conf.py b/docs/source/conf.py index c4c73dd5..070f63f2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,13 +21,7 @@ # html options htmlhelp_basename = 'nixio' try: - import alabaster - - html_theme_path = [alabaster.get_path()] - html_static_path = ['_static'] - extensions += ['alabaster'] - html_theme = 'alabaster' - + html_theme = 'sphinx_rtd_theme' html_sidebars = { '**': [ 'about.html', 'navigation.html', 'searchbox.html', diff --git a/docs/source/index.rst b/docs/source/index.rst index 2bb9ecae..93a6712a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,14 +2,13 @@ NIXIO Python Package for NIX Datafiles ====================================== -The nixpy module contains the python binding to the nix c++ library. In order -to use it you also have to have the nix library installed. +The NIXPy module is a reimplementation of the `NIX C++ library `_. Getting started =============== -The following sections should help you getting started with nixpy. +The following sections should help you getting started with NIXPy. .. toctree:: :maxdepth: 2 @@ -18,19 +17,24 @@ The following sections should help you getting started with nixpy. overview tutorial -API Documentation -================= -The API documentation for Data and Metadata +High Level API Reference +======================== + +User API documentation for Data and Metadata .. toctree:: :maxdepth: 2 - api_data - api_metadata + user_api + + +Advanced +======== + +Internal NIXIO API Developer Documentation +------------------------------------------ -Internal API Developer Documentation -==================================== -The API documentation of internal modules, for developers +The API documentation of internal modules, for NIXPy developers. .. toctree:: :maxdepth: 2 diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 2ebfee76..3caf9bb5 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -1,6 +1,6 @@ -======== +======== Overview -======== +======== Design Principles ================= @@ -9,7 +9,7 @@ The design of the data model tries to draw on similarities of different data types and structures and and come up with *entities* that are as generic and versatile as meaningful. At the same time we aim for clearly established links between different entities to keep the -model as expressive as possible. +model as expressive as possible. Most entities of the NIX-model have a *name* and a *type* field which are meant to provide information about the entity. While the name can @@ -64,7 +64,7 @@ unique id (UUID). Storing data -"""""""""""" +"""""""""""" The heart of our data model is an entity called **DataArray**. This is the entity that actually stores all data. It can take n-dimensional @@ -85,7 +85,7 @@ Using this call will create a **DataArray**, set name and type, set the *dataType* according to the dtype of the passed data, and store the data in the file. You can also create empty **DataArrays** to take up data-to-be-recorded. In this case you have to provide the space -that will be needed in advance. +that will be needed in advance. .. code-block:: python @@ -142,7 +142,7 @@ irregular intervals, and (iii) data that belongs to categories. dim.unit = "s" The **SampledDimension** can also be used to desribe space dimensions, -e.g. in case of images. +e.g. in case of images. If the data was sampled at irregular intervals the sample points of the x-axis are defined using the *ticks* property of a @@ -364,3 +364,17 @@ the tag's position is given in *ms*. #for compound units we can do tag.units=["mV/cm"] + + +Metadata +======== + +The model for storing metadata is largely equivalent to the `odML`_ (open metadata Markup Language) model. In brief: the +model consists of so called Properties that contain Values much like a key-value pair (plus some additional fields). +These Properties can be grouped into Sections which themselves can be nested to built a tree-structure. Sections are +defined by a name and a type (e.g. a stimulus-type section will contain information that is related to a stimulus). +The basic feature of the odML approach is that it defines the model but not the items that are described or the terms +that are used in this. On the other hand where standardization is required each Section can be based on an +odML-terminology that standardizes without restricting to the terms defined within the terminology. + +.. _odML: http://www.frontiersin.org/Neuroinformatics/10.3389/fninf.2011.00016 diff --git a/docs/source/api_data.rst b/docs/source/user_api.rst similarity index 85% rename from docs/source/api_data.rst rename to docs/source/user_api.rst index 7aa2c9e8..8089137f 100644 --- a/docs/source/api_data.rst +++ b/docs/source/user_api.rst @@ -1,8 +1,6 @@ -========================== -API Documentation for Data -========================== - -TODO write something about the data model +======================== +High Level API Reference +======================== File @@ -256,3 +254,60 @@ Group API :inherited-members: :undoc-members: + +Section +======= + +Metadata stored in a NIX file can be accessed directly from an open file. + +Create and delete sub sections +------------------------------ + +.. code-block:: python + :linenos: + + sub = section.create_section("a name", "type") + del section.sections[sub] + +Add and remove properties +------------------------- + +Properties can be created using the create_property method. Existing properties can be accessed and deleted +directly from the respective section. + +.. code-block:: python + :linenos: + + section.create_property("one", [1]) + section.create_property("two", [2]) + + # iterate over properties + for p in section: + print(p) + + # access by name + one = section["one"] + + # convert properties into a dict + dct = dict(section.items()) + + # delete properties + del section["one"] + del section["two"] + +Section API +----------- + +.. autoclass:: nixio.Section + :members: + :inherited-members: + :undoc-members: + +Property +======== + +.. autoclass:: nixio.Property + :members: + :inherited-members: + :undoc-members: + diff --git a/nixio/info.json b/nixio/info.json index d8df97bb..05f0eb31 100644 --- a/nixio/info.json +++ b/nixio/info.json @@ -3,7 +3,7 @@ "STATUS": "Release", "RELEASE": "1.5.dev Release", "AUTHOR": "Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou", - "COPYRIGHT": "2014-2019, German Neuroinformatics Node, Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou", + "COPYRIGHT": "2014-2020, German Neuroinformatics Node, Christian Kellner, Adrian Stoewer, Andrey Sobolev, Jan Grewe, Balint Morvai, Achilleas Koutsou", "CONTACT": "dev@g-node.org", "BRIEF": "Python reimplementation of NIXIO (http://g-node.github.io/nix/)", "HOMEPAGE": "https://github.com/G-Node/nixpy"