# PyDapsys - Read DAPSYS recordings with Python
[](https://pypi.org/project/pydapsys/)
PyDapsys is a package to read neurography recordings made with [DAPSYS](http://dapsys.net/) (Data Acquisition Processor System). It is based on a reverse-engineered specification of the binary data format used by the latest DAPSYS version.
Optionally, the library provides functionality to store loaded data into [Neo](https://github.com/NeuralEnsemble/python-neo) datastructures, from where they can be exported into various other formats.
## Installation
Either download the wheel file for offline installation or use pypi.
### Basic functionalities
Will only offer the data representation of PyDapsys, without ability to convert to Neo. Has only numpy as sole dependency.
`pip install pydapsys`
`pip install {name_of_downloaded_wheel}.whl`
### With Neo converters
Install base library with additional dependencies required to load data into Neo datastructures. Writing Neo datastructures to some formats may require additional dependencies. Please see the Neo documentation for further information.
`pip install pydapsys[neo]`
`pip install {name_of_downloaded_wheel}.whl[neo]`
## Usage
### Quickstart
A DAPSYS file is made up of two parts: A sequential list of blocks or **pages**, which store either a text with a timestamp or a waveform with associated timestamps, and a table of contents (toc). The toc consists of **folders** and **streams**. Each page has an id unique in the context of the file. Streams in the toc have an array of ids of the pages belonging to the stream. A stream is either a text stream (referring only to text pages) or a data stream (referring only to recording pages).
#### Load a file
Use `File.from_binary` to read from a BinaryIO object.
```python
from pydapsys import read_file
from pathlib import Path
MY_DAPSYS_FILE = Path(".")/"to"/"my"/"dapsys_file.dps"
with open(MY_DAPSYS_FILE, 'rb') as file:
file = read_file(file)
```
The `File` object has two fields, the root of the table of contents and a dictionary mapping the page ids to their respective pages.
##### Inspect file structure
To inspect the ToC structure of a loaded file, use the `structure` property of the toc `Root`, preferable together with `pprint`:
```python
import pprint
pprint.PrettyPrinter(indent=4).pprint(file.toc.structure)
```
This will print the structure, names and types of all elements in the table of contents. For Streams, the number of associated pages it also printed after their type.
#### Access data from a file
To access data, use the `File.get_data` method. The method takes a path from the toc structure (WITHOUT THE NAME OF THE ROOT!) and will return all associated pages.
Please note, that the path is case insensitive
```python
from pydapsys.toc import StreamType
my_texts = list(file.get_data("myrecording/my text stream", stype=StreamType.Text))
my_waveforms = list(file.get_data("myrecording/somewhere else/ my waveform stream", stype=StreamType.Waveform))
```
##### Text pages
A text page consists of three fields:
* `text`: The text stored in the page, string
* `timestamp_a`: The first timestamp of the page, float64 (seconds)
* `timestamp_b`: The second timestamp of the page (float64, seconds), which sometimes is not presented and is thus set to None
##### Waveform pages
Waveform pages consist of three fields:
* `values`: Values of the waveform, float32 (volt)
* `timestamps`: Timestamps corresponding to `values`, float64 (seconds)
* `interval`: Interval between values, float64 (seconds)
In **continuously sampled waveforms**, only the timestamp of the first value will be present, in addition to the sampling `interval`. The timestamps of the other values can be calculated by this two values.
**Irregularly sampled waveforms** will have one timestamp for each value, but no `interval`.
## Neo converters
The module `pydapsys.neo_convert` contains classes to convert a Dapsys recording to the Neo format. **IMPORTANT: importing the module without installing neo first will raise an exception**
As Dapsys files may have different structures, depending on how it was configured and what hardware is used, different converters are required for each file structure.
Currently there is only one converter available, for recordings made using a NI Pulse stimulator.
### NI Pulse stimulator
Converter class for Dapsys recording created using an NI Pulse stimulator. Puts everything into one neo sequence.
Waveform pages of the continuous recording are merged if the difference between a pair of consecutive pages is less than a specified threshold (`grouping_tolerance`).
```python
from pydapsys.neo_converters import NIPulseStimRecordingConverter
# convert a recording to a neo block
neo_block = NIPulseStimRecordingConverter(file, grouping_tolerance=1e-9).to_neo()
```
#### Expected file structure
{stim_folder} must be one of "NI Puls Stimulator", "pulse stimulator", "NI Pulse stimulator", but can be changed by adding entries to `NIPulseStimulatorToNeo.stim_foler_names`
* Root
* [Text] Comments -> Converted into a single event called "comments"
* {stim_folder}
* [Text] Pulses -> Converted into one neo event streams, one per unique text
* [Waveform] Continuous recording -> Converted into multiple AnalogSignals
* Responses
* Tracks for All Responses -> Optional. Will silently ignore spike trains if this folder does not exist
* ... [Text] tracks... -> Converted into spike trains
Raw data
{
"_id": null,
"home_page": "https://github.com/Digital-C-Fiber/PyDapsys",
"name": "pydapsys",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "microneurography,dapsys,neurophysiology,electrophysiology",
"author": "Peter Konradi",
"author_email": "codingchipmunk@posteo.net",
"download_url": "https://files.pythonhosted.org/packages/ff/9f/0bd9d32b5677f184215d152c9ba38b7dfc58b77fae483e7fd2da3985a647/pydapsys-0.2.1.tar.gz",
"platform": null,
"description": "# PyDapsys - Read DAPSYS recordings with Python\n\n[](https://pypi.org/project/pydapsys/)\n\nPyDapsys is a package to read neurography recordings made with [DAPSYS](http://dapsys.net/) (Data Acquisition Processor System). It is based on a reverse-engineered specification of the binary data format used by the latest DAPSYS version.\n\nOptionally, the library provides functionality to store loaded data into [Neo](https://github.com/NeuralEnsemble/python-neo) datastructures, from where they can be exported into various other formats.\n\n## Installation\n\nEither download the wheel file for offline installation or use pypi.\n\n### Basic functionalities\n\nWill only offer the data representation of PyDapsys, without ability to convert to Neo. Has only numpy as sole dependency. \n\n`pip install pydapsys`\n\n`pip install {name_of_downloaded_wheel}.whl`\n\n### With Neo converters\n\nInstall base library with additional dependencies required to load data into Neo datastructures. Writing Neo datastructures to some formats may require additional dependencies. Please see the Neo documentation for further information.\n\n`pip install pydapsys[neo]`\n\n`pip install {name_of_downloaded_wheel}.whl[neo]`\n\n## Usage\n\n### Quickstart\n\nA DAPSYS file is made up of two parts: A sequential list of blocks or **pages**, which store either a text with a timestamp or a waveform with associated timestamps, and a table of contents (toc). The toc consists of **folders** and **streams**. Each page has an id unique in the context of the file. Streams in the toc have an array of ids of the pages belonging to the stream. A stream is either a text stream (referring only to text pages) or a data stream (referring only to recording pages).\n\n#### Load a file\nUse `File.from_binary` to read from a BinaryIO object.\n```python\nfrom pydapsys import read_file\nfrom pathlib import Path\nMY_DAPSYS_FILE = Path(\".\")/\"to\"/\"my\"/\"dapsys_file.dps\"\nwith open(MY_DAPSYS_FILE, 'rb') as file:\n file = read_file(file)\n```\nThe `File` object has two fields, the root of the table of contents and a dictionary mapping the page ids to their respective pages.\n##### Inspect file structure\nTo inspect the ToC structure of a loaded file, use the `structure` property of the toc `Root`, preferable together with `pprint`:\n```python\nimport pprint\npprint.PrettyPrinter(indent=4).pprint(file.toc.structure)\n```\nThis will print the structure, names and types of all elements in the table of contents. For Streams, the number of associated pages it also printed after their type.\n#### Access data from a file\nTo access data, use the `File.get_data` method. The method takes a path from the toc structure (WITHOUT THE NAME OF THE ROOT!) and will return all associated pages.\nPlease note, that the path is case insensitive\n```python\nfrom pydapsys.toc import StreamType\nmy_texts = list(file.get_data(\"myrecording/my text stream\", stype=StreamType.Text))\nmy_waveforms = list(file.get_data(\"myrecording/somewhere else/ my waveform stream\", stype=StreamType.Waveform))\n```\n##### Text pages\n\nA text page consists of three fields:\n\n* `text`: The text stored in the page, string\n\n* `timestamp_a`: The first timestamp of the page, float64 (seconds)\n\n* `timestamp_b`: The second timestamp of the page (float64, seconds), which sometimes is not presented and is thus set to None\n\n##### Waveform pages\n\nWaveform pages consist of three fields:\n\n* `values`: Values of the waveform, float32 (volt)\n\n* `timestamps`: Timestamps corresponding to `values`, float64 (seconds)\n\n* `interval`: Interval between values, float64 (seconds)\n\nIn **continuously sampled waveforms**, only the timestamp of the first value will be present, in addition to the sampling `interval`. The timestamps of the other values can be calculated by this two values.\n\n**Irregularly sampled waveforms** will have one timestamp for each value, but no `interval`.\n\n## Neo converters\n\nThe module `pydapsys.neo_convert` contains classes to convert a Dapsys recording to the Neo format. **IMPORTANT: importing the module without installing neo first will raise an exception**\n\nAs Dapsys files may have different structures, depending on how it was configured and what hardware is used, different converters are required for each file structure.\n\nCurrently there is only one converter available, for recordings made using a NI Pulse stimulator.\n\n### NI Pulse stimulator\n\nConverter class for Dapsys recording created using an NI Pulse stimulator. Puts everything into one neo sequence. \nWaveform pages of the continuous recording are merged if the difference between a pair of consecutive pages is less than a specified threshold (`grouping_tolerance`).\n\n```python\nfrom pydapsys.neo_converters import NIPulseStimRecordingConverter\n\n# convert a recording to a neo block\nneo_block = NIPulseStimRecordingConverter(file, grouping_tolerance=1e-9).to_neo()\n```\n\n#### Expected file structure\n\n{stim_folder} must be one of \"NI Puls Stimulator\", \"pulse stimulator\", \"NI Pulse stimulator\", but can be changed by adding entries to `NIPulseStimulatorToNeo.stim_foler_names`\n\n* Root\n \n * [Text] Comments -> Converted into a single event called \"comments\"\n \n * {stim_folder}\n \n * [Text] Pulses -> Converted into one neo event streams, one per unique text\n \n * [Waveform] Continuous recording -> Converted into multiple AnalogSignals\n \n * Responses\n \n * Tracks for All Responses -> Optional. Will silently ignore spike trains if this folder does not exist\n \n * ... [Text] tracks... -> Converted into spike trains\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Read recordings made with DAPSYS",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/Digital-C-Fiber/PyDapsys",
"Repository": "https://github.com/Digital-C-Fiber/PyDapsys"
},
"split_keywords": [
"microneurography",
"dapsys",
"neurophysiology",
"electrophysiology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b124009cbbfc44c784790c26783980ff0029e0d47817089117c7e10df2632db",
"md5": "26e1d528c73a856e7235af68f27ea2b9",
"sha256": "95bafdab0505ae68028f3efc99dcd5bfe70e5fe6a93e4b8226d7cb986c01be4d"
},
"downloads": -1,
"filename": "pydapsys-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26e1d528c73a856e7235af68f27ea2b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 20918,
"upload_time": "2023-05-25T11:41:09",
"upload_time_iso_8601": "2023-05-25T11:41:09.657189Z",
"url": "https://files.pythonhosted.org/packages/9b/12/4009cbbfc44c784790c26783980ff0029e0d47817089117c7e10df2632db/pydapsys-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff9f0bd9d32b5677f184215d152c9ba38b7dfc58b77fae483e7fd2da3985a647",
"md5": "2dea25a5a332402da00f87250446b9d3",
"sha256": "f3d7488d990555aa818d2bb89a61dfd479f78d9cb487c6544a2982150328bd17"
},
"downloads": -1,
"filename": "pydapsys-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "2dea25a5a332402da00f87250446b9d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 18101,
"upload_time": "2023-05-25T11:41:11",
"upload_time_iso_8601": "2023-05-25T11:41:11.491050Z",
"url": "https://files.pythonhosted.org/packages/ff/9f/0bd9d32b5677f184215d152c9ba38b7dfc58b77fae483e7fd2da3985a647/pydapsys-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-25 11:41:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Digital-C-Fiber",
"github_project": "PyDapsys",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pydapsys"
}
JSON
