[python-hdf5storage] 98/152: Created a skeleton introduction in the documentation and then moved the examples from __init__.py to it and updated them.
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Mon Feb 29 08:24:38 UTC 2016
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to annotated tag 0.1
in repository python-hdf5storage.
commit bb295d39d48ae64123364b00aaa24066fd43bdaf
Author: Freja Nordsiek <fnordsie at gmail.com>
Date: Tue Feb 4 01:18:39 2014 -0500
Created a skeleton introduction in the documentation and then moved the examples from __init__.py to it and updated them.
---
doc/source/index.rst | 1 +
doc/source/introduction.rst | 195 ++++++++++++++++++++++++++++++++++++++++++++
hdf5storage/__init__.py | 140 -------------------------------
3 files changed, 196 insertions(+), 140 deletions(-)
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e2c5d98..72078ed 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,6 +12,7 @@ Contents:
:maxdepth: 2
information
+ introduction
api
Indices and tables
diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
new file mode 100644
index 0000000..6e68008
--- /dev/null
+++ b/doc/source/introduction.rst
@@ -0,0 +1,195 @@
+============
+Introduction
+============
+
+Example: Write And Readback Including Different Metadata
+========================================================
+
+Making The Data
+---------------
+
+Make a ``dict`` containing many different types in it that we want to
+store to disk in an HDF5 file.
+
+ >>> import numpy as np
+ >>> import hdf5storage
+ >>> a = {'a': True,
+ ... 'b': None,
+ ... 'c': 2,
+ ... 'd': -3.2,
+ ... 'e': (1-2.3j),
+ ... 'f': 'hello',
+ ... 'g': b'goodbye',
+ ... 'h': ['list', 'of', 'stuff', [30, 2.3]],
+ ... 'i':{'aa': np.bool_(False),
+ ... 'bb': np.uint8(4),
+ ... 'cc': np.uint32([70, 8]),
+ ... 'dd': np.int32([]),
+ ... 'ee': np.float32([[3.3], [5.3e3]]),
+ ... 'ff': np.complex128([[3.4, 3], [9+2j, 0]]),
+ ... 'gg': np.array(['one', 'two', 'three'], dtype='str'),
+ ... 'hh': np.bytes_(b'how many?'),
+ ... 'ii': np.object_(['text', np.int8([1, -3, 0])])}}
+
+Using No Metadata
+-----------------
+
+Write it to a file at the root directory, but include no Python or
+MATLAB metadata. Then, read it back and notice that many objects come
+back quite different from what was written. Namely, everything but
+``dict`` types were converted to Numpy types. This happens because all
+other types must be converted to these types before being written to the
+HDF5 file, and without metadata, the conversion cannot be reversed.
+
+ >>> hdf5storage.write(data=a, name='/', filename='data.h5',
+ ... store_type_information=False,
+ ... matlab_compatible=False)
+ >>> hdf5storage.read(name='/', filename='data.h5')
+ {'a': array(True, dtype=bool),
+ 'b': array([], dtype=float64),
+ 'c': array(2),
+ 'd': array(-3.2),
+ 'e': array((1-2.3j)),
+ 'f': array(b'hello',
+ dtype='|S5'),
+ 'g': array(b'goodbye',
+ dtype='|S7'),
+ 'h': array([array(b'list',
+ dtype='|S4'),
+ array(b'of',
+ dtype='|S2'),
+ array(b'stuff',
+ dtype='|S5'),
+ array([array(30), array(2.3)], dtype=object)], dtype=object),
+ 'i': {'aa': array(False, dtype=bool),
+ 'bb': array(4, dtype=uint8),
+ 'cc': array([70, 8], dtype=uint32),
+ 'dd': array([], dtype=int32),
+ 'ee': array([[ 3.29999995e+00],
+ [ 5.30000000e+03]], dtype=float32),
+ 'ff': array([[ 3.4+0.j, 3.0+0.j],
+ [ 9.0+2.j, 0.0+0.j]]),
+ 'gg': array([111, 110, 101, 0, 0, 116, 119, 111, 0, 0, 116, 104, 114,
+ 101, 101], dtype=uint32),
+ 'hh': array(b'how many?',
+ dtype='|S9'),
+ 'ii': array([array(b'text',
+ dtype='|S4'), array([ 1, -3, 0], dtype=int8)], dtype=object)}}
+
+
+Including Python Metadata
+-------------------------
+
+Do the same thing, but now include Python metadata
+(``store_type_information == True``). This time, everything is read back
+the same (or at least, it should) as it was written.
+
+ >>> hdf5storage.write(data=a, name='/', filename='data_typeinfo.h5',
+ ... store_type_information=True,
+ ... matlab_compatible=False)
+ >>> hdf5storage.read(name='/', filename='data_typeinfo.h5')
+ {'a': True,
+ 'b': None,
+ 'c': 2,
+ 'd': -3.2,
+ 'e': (1-2.3j),
+ 'f': 'hello',
+ 'g': b'goodbye',
+ 'h': ['list', 'of', 'stuff', [30, 2.3]],
+ 'i': {'aa': False,
+ 'bb': 4,
+ 'cc': array([70, 8], dtype=uint32),
+ 'dd': array([], dtype=int32),
+ 'ee': array([[ 3.29999995e+00],
+ [ 5.30000000e+03]], dtype=float32),
+ 'ff': array([[ 3.4+0.j, 9.0+2.j],
+ [ 3.0+0.j, 0.0+0.j]]),
+ 'gg': array(['one', 'two', 'three'],
+ dtype='<U5'),
+ 'hh': b'how many?',
+ 'ii': array(['text', array([ 1, -3, 0], dtype=int8)], dtype=object)}}
+
+Including MATLAB Metadata
+-------------------------
+
+Do the same thing, but this time including only MATLAB metadata
+(``matlab_compatible == True``). This time, the data that is read back
+is different from what was written, but in a different way than when no
+metadata was used. The biggest differences are that everything was
+turned into an at least 2D array, all arrays are transposed, and all
+string types got converted to ``numpy.str_``. This happens because
+MATLAB can only work with 2D and higher arrays, uses Fortran array
+ordering instead of C ordering like Python does, and strings are stored
+in a subset of UTF-16 (no doublets) in the version 7.3 MAT files.
+
+ >>> hdf5storage.write(data=a, name='/', filename='data.mat',
+ ... store_type_information=False,
+ ... matlab_compatible=True)
+ >>> hdf5storage.read(name='/', filename='data.mat')
+ {'a': array([[ True]], dtype=bool),
+ 'b': array([], shape=(1, 0), dtype=float64),
+ 'c': array([[2]]),
+ 'd': array([[-3.2]]),
+ 'e': array([[ 1.-2.3j]]),
+ 'f': array([['hello']],
+ dtype='<U5'),
+ 'g': array([['goodbye']],
+ dtype='<U7'),
+ 'h': array([[array([['list']],
+ dtype='<U4'),
+ array([['of']],
+ dtype='<U2'),
+ array([['stuff']],
+ dtype='<U5'),
+ array([[array([[30]]), array([[ 2.3]])]], dtype=object)]], dtype=object),
+ 'i': {'aa': array([[False]], dtype=bool),
+ 'bb': array([[4]], dtype=uint8),
+ 'cc': array([[70, 8]], dtype=uint32),
+ 'dd': array([], shape=(1, 0), dtype=int32),
+ 'ee': array([[ 3.29999995e+00],
+ [ 5.30000000e+03]], dtype=float32),
+ 'ff': array([[ 3.4+0.j, 3.0+0.j],
+ [ 9.0+2.j, 0.0+0.j]]),
+ 'gg': array([['one\x00\x00two\x00\x00three']],
+ dtype='<U15'),
+ 'hh': array([['how many?']],
+ dtype='<U9'),
+ 'ii': array([[array([['text']],
+ dtype='<U4'),
+ array([[ 1, -3, 0]], dtype=int8)]], dtype=object)}}
+
+Including both Python And MATLAB Metadata
+-----------------------------------------
+
+Do the same thing, but now include both Python metadata
+(``store_type_information == True``) and MATLAB metadata
+(``matlab_compatible == True``). This time, everything is read back
+the same (or at least, it should) as it was written. The Python metadata
+allows the transformations done by making the stored data MATLAB
+compatible reversible.
+
+ >>> hdf5storage.write(data=a, name='/', filename='data_typeinfo.mat',
+ ... store_type_information=True,
+ ... matlab_compatible=True)
+ >>> hdf5storage.read(name='/', filename='data_typeinfo.mat')
+ {'a': True,
+ 'b': None,
+ 'c': 2,
+ 'd': -3.2,
+ 'e': (1-2.3j),
+ 'f': 'hello',
+ 'g': b'goodbye',
+ 'h': ['list', 'of', 'stuff', [30, 2.3]],
+ 'i': {'aa': False,
+ 'bb': 4,
+ 'cc': array([70, 8], dtype=uint32),
+ 'dd': array([], dtype=int32),
+ 'ee': array([[ 3.29999995e+00],
+ [ 5.30000000e+03]], dtype=float32),
+ 'ff': array([[ 3.4+0.j, 3.0+0.j],
+ [ 9.0+2.j, 0.0+0.j]]),
+ 'gg': array(['one', 'two', 'three'],
+ dtype='<U5'),
+ 'hh': b'how many?',
+ 'ii': array(['text', array([ 1, -3, 0], dtype=int8)], dtype=object)}}
+
diff --git a/hdf5storage/__init__.py b/hdf5storage/__init__.py
index 3b94f21..0129b49 100644
--- a/hdf5storage/__init__.py
+++ b/hdf5storage/__init__.py
@@ -30,146 +30,6 @@ Numpy types.
Version 0.1
-
-Examples
---------
-
-Write and read back a ``dict`` of various types, not storing any type
-information or MATLAB metadata.
-
->>> import numpy as np
->>> a = {'a': 2, 'b': 2.3, 'c': True, 'd': 'abc', 'e': b'defg',
- 'f': (1-2.3j), 'g': None, 'h':{'aa': np.uint8(1),
- 'bb': np.int16([1, 2, 3]),
- 'cc': np.float32([[1, 2, 3, 4],[5, 6, 7, 8.2]]),
- 'dd': np.complex128([[1], [2+3j], [0]]),
- 'ee': np.bytes_('adfdafa'), 'ff': np.str_('aivne12'),
- 'gg': {'123': 1}}}
->>> hdf5storage.write(data=a, name='/', filename='data.h5',
- store_type_information=False,
- matlab_compatible=False)
->>> hdf5storage.read(name='/', filename='data.h5')
-{'a': array(2),
- 'b': array(2.3),
- 'c': array(True, dtype=bool),
- 'd': array(b'abc',
- dtype='|S3'),
- 'e': array(b'defg',
- dtype='|S4'),
- 'f': array((1-2.3j)),
- 'g': array([], dtype=float64),
- 'h': {'aa': array(1, dtype=uint8),
- 'bb': array([1, 2, 3], dtype=int16),
- 'cc': array([[ 1. , 2. , 3. , 4. ],
- [ 5. , 6. , 7. , 8.19999981]],
- dtype=float32),
- 'dd': array([[ 1.+0.j],
- [ 2.+3.j],
- [ 0.+0.j]]),
- 'ee': array(b'adfdafa',
- dtype='|S7'),
- 'ff': array([ 97, 105, 118, 110, 101, 49, 50], dtype=uint32),
- 'gg': {'123': array(1)}}}
-
-Write and read back the same ``dict`` of various types, but now storing
-type information but not MATLAB metadata.
-
->>> import numpy as np
->>> a = {'a': 2, 'b': 2.3, 'c': True, 'd': 'abc', 'e': b'defg',
- 'f': (1-2.3j), 'g': None, 'h':{'aa': np.uint8(1),
- 'bb': np.int16([1, 2, 3]),
- 'cc': np.float32([[1, 2, 3, 4],[5, 6, 7, 8.2]]),
- 'dd': np.complex128([[1], [2+3j], [0]]),
- 'ee': np.bytes_('adfdafa'), 'ff': np.str_('aivne12'),
- 'gg': {'123': 1}}}
->>> hdf5storage.write(data=a, name='/', filename='data_typeinfo.h5',
- store_type_information=True,
- matlab_compatible=False)
->>> hdf5storage.read(name='/', filename='data_typeinfo.h5')
-{'a': 2,
- 'b': 2.3,
- 'c': True,
- 'd': 'abc',
- 'e': b'defg',
- 'f': (1-2.3j),
- 'g': None,
- 'h': {'aa': 1,
- 'bb': array([1, 2, 3], dtype=int16),
- 'cc': array([[ 1. , 5. , 2. , 6. ],
- [ 3. , 7. , 4. , 8.19999981]], dtype=float32),
- 'dd': array([[ 1.+0.j],
- [ 2.+3.j],
- [ 0.+0.j]]),
- 'ee': b'adfdafa',
- 'ff': 'aivne12',
- 'gg': {'123': 1}}}
-
-Write and read back the same ``dict`` of various types, but now storing
-MATLAB metadata (making it a MAT v7.3 file) but not type information.
-
->>> import numpy as np
->>> a = {'a': 2, 'b': 2.3, 'c': True, 'd': 'abc', 'e': b'defg',
- 'f': (1-2.3j), 'g': None, 'h':{'aa': np.uint8(1),
- 'bb': np.int16([1, 2, 3]),
- 'cc': np.float32([[1, 2, 3, 4],[5, 6, 7, 8.2]]),
- 'dd': np.complex128([[1], [2+3j], [0]]),
- 'ee': np.bytes_('adfdafa'), 'ff': np.str_('aivne12'),
- 'gg': {'123': 1}}}
->>> hdf5storage.write(data=a, name='/', filename='data.mat',
- store_type_information=False,
- matlab_compatible=True)
->>> hdf5storage.read(name='/', filename='data.mat')
-{'a': array([[2]]),
- 'b': array([[ 2.3]]),
- 'c': array([[ True]], dtype=bool),
- 'd': 'abc',
- 'e': 'defg',
- 'f': array([[ 1.-2.3j]]),
- 'g': array([], dtype=float64),
- 'h': {'aa': array([[1]], dtype=uint8),
- 'bb': array([[1, 2, 3]], dtype=int16),
- 'cc': array([[ 1. , 2. , 3. , 4. ],
- [ 5. , 6. , 7. , 8.19999981]], dtype=float32),
- 'dd': array([[ 1.+0.j],
- [ 2.+3.j],
- [ 0.+0.j]]),
- 'ee': 'adfdafa',
- 'ff': 'aivne12',
- 'gg': {'123': array([[1]])}}}
-
-Write and read back the same ``dict`` of various types, but now storing
-both type information and MATLAB metadata (making it a MAT v7.3 file).
-
->>> import numpy as np
->>> a = {'a': 2, 'b': 2.3, 'c': True, 'd': 'abc', 'e': b'defg',
- 'f': (1-2.3j), 'g': None, 'h':{'aa': np.uint8(1),
- 'bb': np.int16([1, 2, 3]),
- 'cc': np.float32([[1, 2, 3, 4],[5, 6, 7, 8.2]]),
- 'dd': np.complex128([[1], [2+3j], [0]]),
- 'ee': np.bytes_('adfdafa'), 'ff': np.str_('aivne12'),
- 'gg': {'123': 1}}}
->>> hdf5storage.write(data=a, name='/', filename='data_typeinfo.mat',
- store_type_information=True,
- matlab_compatible=True)
->>> hdf5storage.read(name='/', filename='data_typeinfo.mat')
-{'a': 2,
- 'b': 2.3,
- 'c': True,
- 'd': 'abc',
- 'e': b'defg',
- 'f': (1-2.3j),
- 'g': None,
- 'h': {'aa': 1,
- 'bb': array([1, 2, 3], dtype=int16),
- 'cc': array([[ 1. , 2. , 3. , 4. ],
- [ 5. , 6. , 7. , 8.19999981]], dtype=float32),
- 'dd': array([[ 1.+0.j],
- [ 2.+3.j],
- [ 0.+0.j]]),
- 'ee': b'adfdafa',
- 'ff': 'aivne12',
- 'gg': {'123': 1}}}
-
"""
__version__ = "0.1"
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/python-hdf5storage.git
More information about the debian-science-commits
mailing list