|PyPI version| |Docs badge| |License|
DBDREADER
=========
Synopsis
--------
Slocum ocean gliders are autonomous underwater vehicles, used for
making oceanographic measurements. The data that these devices and
their sensors collect, are stored in binary data files. The python
module *dbdreader* provides the utilities to extract the data from the
binary files, so that they can be further analysed.
Change log
----------
version 0.5.8
* Changes default location for cache files on linux from
$HOME/.dbdreader to $HOME/.local/share/dbdreader
* Introduces new class DBDCache to manage the location where cache
files are looked up. Constructing an object with an arguments (re-)sets a
default path, avoiding the need to use the keyword cacheDir when
creating objects of DBD and MultiDBD classes.
* Fixes an issue with MultiDBD when a parameter is requested that is
not present in all files, but in at least one. The get() method
returns just those data that are present. In case of get_sync and
friends, data are interpolated if possible, or padded with nans.
Version 0.5.7
* Drops dependency on python 3.10+, introduced in 0.5.6, and should
work still with python 3.9.
Version 0.5.6
* Moves data directory under dbdreader, making these files accessible
after an pip install
Version 0.5.5
* Makes MultiDBD's get_CTD_sync method compatible with RBR CTD data.
Version 0.5.4
* Adds support for reading compressed data files for windows platform.
* Improved building environment
Version 0.5.1
* Adds support for reading compressed data files
* dbdrename.py now accepts -x and -X options to rename compressed data files as uncompressed data files
Version 0.4.15
* Modifies sorting key algorithm to the DBDList class. This fixes a
bug when glider data filenames are composed of a glider name that
contains a dash. For example, filenames such as hereon-amadeus-2019-3-1.sbd
would fail, but are valid now.
Version 0.4.14
* Adds a new option to the get() method of the MultiDBD class, where
if the keyword include_sources=True, for each parameter an
additional list is returned that has for each data point a reference
to the DBD instance that produced the data point. This allows to
query the source of a specific data point.
This merges the (modified) pull request #14 by MCazaly.
Version 0.4.13
* Modifies behaviour when the user requests a parameter that has no
data. If the requested parameter is not a valid glider sensor name,
assume a user-error and raise an exception, otherwise return an
empty array.
This behaviour fixes a bug for MultiDBD:
each file opened with MultiDBD would fail to produce any data if one or
more parameters that are asked for, are not present in the file.
New behaviour returns data for the exisiting parameters (only); empty
array for the missing parameters (or nans if return_nans=True)
Concludes pull request #16 by jklymak.
Version 0.4.12
* PatternSelect now accepts the option of a non-standard cache
directory.
Thanks to hawesie.
* MultiDBD's get_sync() now returns nan's for those parameters for
which no data exist, provided that at least one of the requested
parameters contains data.
Version 0.4.11
* Version 0.4.9 introduced a bug that in some rare circumstances caused
segmentation faults. This has been fixed.
* Merged pull request by roje-bodc with improved error handling in
case of missing cache files. If a DbdError occurs due to a missing
cache file, detailed information can be obtained from the .data
property of the exception instance.
Version 0.4.10
* Includes pull request by jklymak, which allows dbdreader to deal
with empty files, and files capitalised file extensions, as well as
a check on the encoding version.
* Includes a bug fix when raising an exception when handling a prior
exception in case of reading problematic files.
* Assumes that if the first parameter given to MultiDBD is a string,
the user did not mean to provide a list of filename strings, but a
pattern. An error is raised if pattern is specified explicitly when
filenames is given as a string.
Version 0.4.9
* Bug fix for handling inf values correctly (issue #8). Thanks to jr3cermak for spotting this bug.
* Bug fix for incorrect behaviour when reading the time parameter explicitly for example xxx.get("m_present_time").
Version 0.4.8
* Support for reading {demnst}bd files from G3S gliders (issue #6). (Thanks to Owain Jones)
* Bug fix for correctly throwing an exception when cache file is missing(issue #5)
Version 0.4.7
* Bug fix for reading dbd files on Windows.
* a wheel provided for CPython 3.9 on Windows 64 bit.
Version 0.4.6
* Added get_CTD_sync, a convenience method to retrieve CTD data, and other parameters mapped on the CTD time stamps. Also ensures time stamps are monotonically increasing.
* Adds bounds to what values of latitude and longitude are considered valid.
Version 0.4.5
* dbdreader now ignores the first line of data in each binary file
* dbdreader checks whether the value of the parameters read are finite, ignoring them if they are not.
Installation (linux)
--------------------
The python module *dbdreader* can be installed from source, using the
standard method to install python code. Note that this method requires
an C-extension to be build. (The actual reading from files is done in
C for speed.) In order to build the extension successfully, you would
need a C-compiler. On Linux, this can be gcc, with supporting
development/header files for python. On Fedora you would do ``sudo dnf
install python3-devel``, or ``sudo apt-get install python3-dev`` on
Ubuntu.
Furthermore, as of version 0.5, which adds support for reading
compressed files, a dependency on the lz4 library is introduced. If
available, the system-wide library will be used (recommended
approach). Alternatively, the lz4.[ch] files from the original source
(https://github.com/lz4/lz4), and included in this package, will be
compiled into the C-extension. To install the system-wide lz4 library
on Fedora you would do ``sudo dnf install lz4-devel lz4-libs``. On
Ubuntu this can be achieved by ``sudo apt-get install liblz4-dev
liblz4-1``.
Alternatively, dbdreader can also be installed from PyPi, using ``pip3
install dbdreader``.
Installation on Windows
-----------------------
If you want to install dbdreader from source, you will need a C
compiler as well to compile the C-extension. Besides the Python
environment you will need to install the Microsoft Visual Studio
Compiler. The community edition will do. When installing MVSC, make sure
you tick the box *python development* during the setup. Once installed
dbdreader can be installed, and the C-extension should be compiled
automatically.
Installiation using pip, for example as in ``py -m pip install
dbdreader`` also requires the C compiler. For Python version 3.9,
however, a wheel is provided, which can be installed adding the option
``--only-binary :all:`` to the pip command: ::
$ pip install --only-binary :all: dbdreader
Documentation
-------------
Comprehensive documentation is provided at https://dbdreader.readthedocs.io/en/latest/
Quick-start
-----------
For the impatient...
The dbdreader module implements a class DBD() which provides the
machinery to read a single dbd file. The most commonly used methods
are:
* get(parametername)
* get_sync(parametername, \*other_parameternames)
The first method returs a tuple with time and values for requested
parameter. The second method, returns a tuple with time and values of
the first parameter requested, and of all further listed parameters,
all interpolated on the time base of the first parameter.
Mostly, it is not one file that is required to be processed, but a
number of them. This interface is implemented by the MultiDBD
class. Files can either be specified as a list of filenames, or as a
pattern using wildcards.
Examples
^^^^^^^^
To read a single file::
>>> dbd = DBD("00010010.dbd")
>>> t, pitch = dbd.get("m_pitch")
>>> t, hdg, ptch, roll = dbd.get_sync("m_heading", "m_pitch", "m_roll)
Or, doing the same, but using both dbd and ebd files::
>>> dbd = DBD(pattern="00010010.[de]bd")
>>> t, pitch = dbd.get("m_pitch")
>>> t, hdg, ptch, roll = dbd.get_sync("m_heading", "m_pitch", "m_roll")
>>> t, p_ctd, p_nav = dbd.get_sync("sci_water_pressure", "m_water_pressure")
Python 2
--------
Python 2.7 is not supported anymore. However, you should be able to
make the code able to run on python2.7 using the *future* package.
* pip install future
* pasteurize dbdreader.
For details see http://python-future.org/pasteurize.html.
.. |PyPI version| image:: https://badgen.net/pypi/v/dbdreader
:target: https://pypi.org/project/dbdreader
.. |Docs badge| image:: https://readthedocs.org/projects/dbdreader/badge/?version=latest
:target: https://dbdreader.readthedocs.io/en/latest/
.. |License| image:: https://img.shields.io/badge/License-GPLv3-blue.svg
:target: https://www.gnu.org/licenses/gpl-3.0
Raw data
{
"_id": null,
"home_page": "https://dbdreader.readthedocs.io/en/latest/",
"name": "dbdreader",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Lucas Merckelbach",
"author_email": "lucas.merckelbach@hereon.de",
"download_url": "https://files.pythonhosted.org/packages/62/39/9c94c107ad14475fc2664f4d0816bdfb82f05c7c6e86d52f658f988797c4/dbdreader-0.5.8.tar.gz",
"platform": null,
"description": "|PyPI version| |Docs badge| |License|\n\nDBDREADER\n=========\n\nSynopsis\n--------\nSlocum ocean gliders are autonomous underwater vehicles, used for\nmaking oceanographic measurements. The data that these devices and\ntheir sensors collect, are stored in binary data files. The python\nmodule *dbdreader* provides the utilities to extract the data from the\nbinary files, so that they can be further analysed.\n\nChange log\n----------\n\nversion 0.5.8\n\n* Changes default location for cache files on linux from\n $HOME/.dbdreader to $HOME/.local/share/dbdreader\n\n* Introduces new class DBDCache to manage the location where cache\n files are looked up. Constructing an object with an arguments (re-)sets a\n default path, avoiding the need to use the keyword cacheDir when\n creating objects of DBD and MultiDBD classes.\n\n* Fixes an issue with MultiDBD when a parameter is requested that is\n not present in all files, but in at least one. The get() method\n returns just those data that are present. In case of get_sync and\n friends, data are interpolated if possible, or padded with nans.\n\nVersion 0.5.7\n\n* Drops dependency on python 3.10+, introduced in 0.5.6, and should\n work still with python 3.9.\n\nVersion 0.5.6\n\n* Moves data directory under dbdreader, making these files accessible\n after an pip install\n\nVersion 0.5.5\n\n* Makes MultiDBD's get_CTD_sync method compatible with RBR CTD data.\n\nVersion 0.5.4\n\n* Adds support for reading compressed data files for windows platform.\n* Improved building environment\n\nVersion 0.5.1\n\n* Adds support for reading compressed data files\n* dbdrename.py now accepts -x and -X options to rename compressed data files as uncompressed data files\n\nVersion 0.4.15\n\n* Modifies sorting key algorithm to the DBDList class. This fixes a \n bug when glider data filenames are composed of a glider name that \n contains a dash. For example, filenames such as hereon-amadeus-2019-3-1.sbd\n would fail, but are valid now.\n\nVersion 0.4.14\n\n* Adds a new option to the get() method of the MultiDBD class, where\n if the keyword include_sources=True, for each parameter an\n additional list is returned that has for each data point a reference\n to the DBD instance that produced the data point. This allows to\n query the source of a specific data point.\n\n This merges the (modified) pull request #14 by MCazaly.\n\nVersion 0.4.13\n\n* Modifies behaviour when the user requests a parameter that has no\n data. If the requested parameter is not a valid glider sensor name,\n assume a user-error and raise an exception, otherwise return an\n empty array.\n\n This behaviour fixes a bug for MultiDBD:\n each file opened with MultiDBD would fail to produce any data if one or\n more parameters that are asked for, are not present in the file.\n \n New behaviour returns data for the exisiting parameters (only); empty\n array for the missing parameters (or nans if return_nans=True)\n\n Concludes pull request #16 by jklymak.\n\nVersion 0.4.12\n\n* PatternSelect now accepts the option of a non-standard cache\n directory.\n Thanks to hawesie.\n\n* MultiDBD's get_sync() now returns nan's for those parameters for\n which no data exist, provided that at least one of the requested\n parameters contains data. \n \nVersion 0.4.11\n\n* Version 0.4.9 introduced a bug that in some rare circumstances caused\n segmentation faults. This has been fixed.\n\n* Merged pull request by roje-bodc with improved error handling in\n case of missing cache files. If a DbdError occurs due to a missing\n cache file, detailed information can be obtained from the .data\n property of the exception instance.\n\n\nVersion 0.4.10\n\n* Includes pull request by jklymak, which allows dbdreader to deal\n with empty files, and files capitalised file extensions, as well as\n a check on the encoding version.\n\n* Includes a bug fix when raising an exception when handling a prior\n exception in case of reading problematic files.\n\n* Assumes that if the first parameter given to MultiDBD is a string,\n the user did not mean to provide a list of filename strings, but a\n pattern. An error is raised if pattern is specified explicitly when\n filenames is given as a string.\n\nVersion 0.4.9\n\n* Bug fix for handling inf values correctly (issue #8). Thanks to jr3cermak for spotting this bug.\n* Bug fix for incorrect behaviour when reading the time parameter explicitly for example xxx.get(\"m_present_time\").\n\nVersion 0.4.8\n\n* Support for reading {demnst}bd files from G3S gliders (issue #6). (Thanks to Owain Jones)\n\n* Bug fix for correctly throwing an exception when cache file is missing(issue #5)\n\nVersion 0.4.7\n\n* Bug fix for reading dbd files on Windows.\n\n* a wheel provided for CPython 3.9 on Windows 64 bit. \n\nVersion 0.4.6\n\n* Added get_CTD_sync, a convenience method to retrieve CTD data, and other parameters mapped on the CTD time stamps. Also ensures time stamps are monotonically increasing.\n\n* Adds bounds to what values of latitude and longitude are considered valid.\n\nVersion 0.4.5\n\n* dbdreader now ignores the first line of data in each binary file\n \n* dbdreader checks whether the value of the parameters read are finite, ignoring them if they are not.\n\n\n\nInstallation (linux)\n--------------------\n\nThe python module *dbdreader* can be installed from source, using the\nstandard method to install python code. Note that this method requires\nan C-extension to be build. (The actual reading from files is done in\nC for speed.) In order to build the extension successfully, you would\nneed a C-compiler. On Linux, this can be gcc, with supporting\ndevelopment/header files for python. On Fedora you would do ``sudo dnf\ninstall python3-devel``, or ``sudo apt-get install python3-dev`` on\nUbuntu.\n\nFurthermore, as of version 0.5, which adds support for reading\ncompressed files, a dependency on the lz4 library is introduced. If\navailable, the system-wide library will be used (recommended\napproach). Alternatively, the lz4.[ch] files from the original source\n(https://github.com/lz4/lz4), and included in this package, will be\ncompiled into the C-extension. To install the system-wide lz4 library\non Fedora you would do ``sudo dnf install lz4-devel lz4-libs``. On\nUbuntu this can be achieved by ``sudo apt-get install liblz4-dev\nliblz4-1``.\n\nAlternatively, dbdreader can also be installed from PyPi, using ``pip3\ninstall dbdreader``.\n\n\nInstallation on Windows\n-----------------------\nIf you want to install dbdreader from source, you will need a C\ncompiler as well to compile the C-extension. Besides the Python\nenvironment you will need to install the Microsoft Visual Studio\nCompiler. The community edition will do. When installing MVSC, make sure\nyou tick the box *python development* during the setup. Once installed\ndbdreader can be installed, and the C-extension should be compiled\nautomatically.\n\n\nInstalliation using pip, for example as in ``py -m pip install\ndbdreader`` also requires the C compiler. For Python version 3.9,\nhowever, a wheel is provided, which can be installed adding the option\n``--only-binary :all:`` to the pip command: ::\n\n $ pip install --only-binary :all: dbdreader\n\n\nDocumentation\n-------------\nComprehensive documentation is provided at https://dbdreader.readthedocs.io/en/latest/\n\nQuick-start\n-----------\nFor the impatient...\n\nThe dbdreader module implements a class DBD() which provides the\nmachinery to read a single dbd file. The most commonly used methods\nare:\n\n* get(parametername)\n* get_sync(parametername, \\*other_parameternames)\n\nThe first method returs a tuple with time and values for requested\nparameter. The second method, returns a tuple with time and values of\nthe first parameter requested, and of all further listed parameters,\nall interpolated on the time base of the first parameter.\n\nMostly, it is not one file that is required to be processed, but a\nnumber of them. This interface is implemented by the MultiDBD\nclass. Files can either be specified as a list of filenames, or as a\npattern using wildcards.\n\nExamples\n^^^^^^^^\n\nTo read a single file::\n\n >>> dbd = DBD(\"00010010.dbd\")\n >>> t, pitch = dbd.get(\"m_pitch\")\n >>> t, hdg, ptch, roll = dbd.get_sync(\"m_heading\", \"m_pitch\", \"m_roll)\n\nOr, doing the same, but using both dbd and ebd files::\n \n >>> dbd = DBD(pattern=\"00010010.[de]bd\")\n >>> t, pitch = dbd.get(\"m_pitch\")\n >>> t, hdg, ptch, roll = dbd.get_sync(\"m_heading\", \"m_pitch\", \"m_roll\")\n >>> t, p_ctd, p_nav = dbd.get_sync(\"sci_water_pressure\", \"m_water_pressure\")\n\n \n\nPython 2\n--------\nPython 2.7 is not supported anymore. However, you should be able to\nmake the code able to run on python2.7 using the *future* package.\n\n* pip install future\n* pasteurize dbdreader.\n\nFor details see http://python-future.org/pasteurize.html.\n\n\n.. |PyPI version| image:: https://badgen.net/pypi/v/dbdreader\n :target: https://pypi.org/project/dbdreader\n.. |Docs badge| image:: https://readthedocs.org/projects/dbdreader/badge/?version=latest\n :target: https://dbdreader.readthedocs.io/en/latest/\n.. |License| image:: https://img.shields.io/badge/License-GPLv3-blue.svg\n :target: https://www.gnu.org/licenses/gpl-3.0\n\n\t \n",
"bugtrack_url": null,
"license": null,
"summary": "A python module to access binary data files generated by Teledyne WebbResearch gliders",
"version": "0.5.8",
"project_urls": {
"Homepage": "https://dbdreader.readthedocs.io/en/latest/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62399c94c107ad14475fc2664f4d0816bdfb82f05c7c6e86d52f658f988797c4",
"md5": "df30d015b49d69e4b308ac32cc6a510a",
"sha256": "b3e5225027222e208cdc5aecd30d5c4daec3811eab411e90e691742c454256a9"
},
"downloads": -1,
"filename": "dbdreader-0.5.8.tar.gz",
"has_sig": false,
"md5_digest": "df30d015b49d69e4b308ac32cc6a510a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1642467,
"upload_time": "2024-10-23T16:55:33",
"upload_time_iso_8601": "2024-10-23T16:55:33.354963Z",
"url": "https://files.pythonhosted.org/packages/62/39/9c94c107ad14475fc2664f4d0816bdfb82f05c7c6e86d52f658f988797c4/dbdreader-0.5.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 16:55:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dbdreader"
}
JSON