# Introduction
[
](https://github.com/BEL-Public/mffpy/actions)
`mffpy` is a lean reader for EGI's MFF file format. These files are
directories containing several files of mostly xml files, but also binary
files.
The main entry point into the library is class `Reader` that accesses a
selection of functions in the .mff directory to return signal data and its meta
information.
## Installation
```bash
$ conda create -n mffpy python=3.6 pip
$ conda activate mffpy
$ pip install -r requirements-dev.txt
$ pip install .
$ # and to run the test
$ make test
```
## Contribute
Definitely run:
```bash
$ pre-commit install
```
### Test Coverage
```
============================= test session starts ==============================
platform linux -- Python 3.6.7, pytest-7.0.1, pluggy-1.0.0
rootdir: /home/runner/work/mffpy/mffpy
plugins: cov-4.0.0
collected 122 items
mffpy/tests/test_cached_property.py .. [ 1%]
mffpy/tests/test_devices.py ............. [ 12%]
mffpy/tests/test_dict2xml.py . [ 13%]
mffpy/tests/test_header_block.py .. [ 14%]
mffpy/tests/test_mffdir.py .... [ 18%]
mffpy/tests/test_raw_bin_files.py .................. [ 32%]
mffpy/tests/test_reader.py ...................... [ 50%]
mffpy/tests/test_writer.py ........... [ 59%]
mffpy/tests/test_xml_files.py .......................................... [ 94%]
.. [ 95%]
mffpy/tests/test_zipfile.py ..... [100%]
----------- coverage: platform linux, python 3.6.7-final-0 -----------
Name Stmts Miss Cover
-----------------------------------------------------------------
mffpy/__init__.py 4 0 100%
mffpy/bin_files.py 40 2 95%
mffpy/bin_writer.py 71 0 100%
mffpy/cached_property.py 25 1 96%
mffpy/devices.py 10 0 100%
mffpy/dict2xml.py 31 3 90%
mffpy/epoch.py 24 3 88%
mffpy/header_block/__init__.py 1 0 100%
mffpy/header_block/header_block.py 48 2 96%
mffpy/header_block/helpers.py 15 0 100%
mffpy/header_block/optional_header_block.py 32 1 97%
mffpy/mffdir.py 92 7 92%
mffpy/raw_bin_files.py 113 0 100%
mffpy/reader.py 110 2 98%
mffpy/tests/__init__.py 0 0 100%
mffpy/tests/conftest.py 11 0 100%
mffpy/tests/test_cached_property.py 33 0 100%
mffpy/tests/test_devices.py 12 0 100%
mffpy/tests/test_dict2xml.py 16 0 100%
mffpy/tests/test_header_block.py 33 0 100%
mffpy/tests/test_mffdir.py 30 0 100%
mffpy/tests/test_raw_bin_files.py 63 0 100%
mffpy/tests/test_reader.py 96 0 100%
mffpy/tests/test_writer.py 204 0 100%
mffpy/tests/test_xml_files.py 202 1 99%
mffpy/tests/test_zipfile.py 34 0 100%
mffpy/version.py 1 0 100%
mffpy/writer.py 71 0 100%
mffpy/xml_files.py 554 18 97%
mffpy/zipfile.py 47 0 100%
-----------------------------------------------------------------
TOTAL 2023 40 98%
============================= 122 passed in 7.19s ==============================
```
## View the Docs
All documentation and API guidance are generated from the python doc-strings
and this README file using pydoc-markdown. To view the docs:
* install pydoc-markdown: `pip install pydoc-markdown`
* build and run: `pydocmd build; pydocmd serve`
* Navigate to the [docs](http://localhost:8000)
## Example Code
### Example 1: Basic Information
```python
import mffpy
fo = mffpy.Reader("./examples/example_1.mff")
print("time and date of the start of recording:", fo.startdatetime)
print("number of channels:", fo.num_channels)
print("sampling rates:", fo.sampling_rates, "(in Hz)")
print("durations:", fo.durations, "(in sec.)")
print("Here's the epoch information")
for i, e in enumerate(fo.epochs):
print("Epoch number", i)
print(e)
```
### Example 2: Reading Samples
```python
from mffpy import Reader
fo = Reader("./examples/example_1.mff")
fo.set_unit('EEG', 'uV')
eeg_in_mV, t0_EEG = fo.get_physical_samples_from_epoch(fo.epochs[0], dt=0.1)['EEG']
fo.set_unit('EEG', 'V')
eeg_in_V, t0_EEG = fo.get_physical_samples_from_epoch(fo.epochs[0], dt=0.1)['EEG']
print('data in mV:', eeg_in_mV[0])
print('data in V :', eeg_in_V[0])
```
### Example 3: Reading .mff xml files
```python
from mffpy import XML
categories = XML.from_file("./examples/example_1.mff/categories.xml")
print(categories['ULRN'])
```
### Example 4: Writing random numbers into an .mff file
```python
from os.path import join
from datetime import datetime
import numpy as np
from mffpy.writer import *
# write 256 channels of 10 data points at a sampling rate of 128 Hz
B = BinWriter(sampling_rate=128)
B.add_block(np.random.randn(256, 10).astype(np.float32))
W = Writer(join('.cache', 'example_4_output.mff'))
startdatetime = datetime.strptime('1984-02-18T14:00:10.000000+0100',
"%Y-%m-%dT%H:%M:%S.%f%z")
W.addxml('fileInfo', recordTime=startdatetime)
W.add_coordinates_and_sensor_layout(device='HydroCel GSN 256 1.0')
W.addbin(B)
W.write()
```
### Example 5: Exporting MFF content to a .json file
```python
from mffpy import Reader, Writer
# Read data from an MFF file
reader = Reader("./examples/example_2.mff")
data = reader.get_mff_content()
# Write data to a JSON file
writer = Writer(".cache/example_5_output.json")
writer.export_to_json(data)
```
**Note: for now, the JSON exporting feature only works for segmented mffs files.**
## Specification of the .mff File Format
### .XML Files
Xml-type files are specified in "/schemata/" using XML Schema Definition. Any
.xml file can be checked for compliance with the command-line tool xmllint.
One can validate your xml files by: `xmllint --schema schemata/categories.xsd
/path/to/my/file.xml --noout`. We are using the following version of xmllint:
```bash
$ xmllint --version
xmllint: using libxml version 20909
compiled with: Threads Tree Output Push Reader Patterns Writer SAXv1 FTP
HTTP DTDValid HTML Legacy C14N Catalog XPath XPointer XInclude Iconv ISO8859X
Unicode Regexps Automata Expr Schemas Schematron Modules Debug Zlib Lzma
```
Currently we describe the following .xml file types:
- [categories.xml](schemata/categories.xsd)
## License and Copyright
Copyright 2019 Brain Electrophysiology Laboratory Company LLC
Licensed under the ApacheLicense, Version 2.0(the "License");
you may not use this module except in compliance with the License.
You may obtain a copy of the License at:
http: // www.apache.org / licenses / LICENSE - 2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
ANY KIND, either express or implied.
Raw data
{
"_id": null,
"home_page": "https://github.com/BEL-Public/mffpy",
"name": "mffpy",
"maintainer": "Evan Hathaway",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "evan.hathaway@belco.tech",
"keywords": "",
"author": "Justus Schwabedal, Wayne Manselle",
"author_email": "jschwabedal@belco.tech, wayne.manselle@belco.tech",
"download_url": "https://files.pythonhosted.org/packages/4a/09/ee05fa3bb72f65fa1fb9a1d21599a8f32e47af7bdedf3bcb41f9d3da6c98/mffpy-0.8.0.tar.gz",
"platform": null,
"description": "# Introduction\n\n[\n](https://github.com/BEL-Public/mffpy/actions)\n\n`mffpy` is a lean reader for EGI's MFF file format. These files are\ndirectories containing several files of mostly xml files, but also binary\nfiles.\n\nThe main entry point into the library is class `Reader` that accesses a\nselection of functions in the .mff directory to return signal data and its meta\ninformation.\n\n## Installation\n\n```bash\n$ conda create -n mffpy python=3.6 pip\n$ conda activate mffpy\n$ pip install -r requirements-dev.txt\n$ pip install .\n$ # and to run the test\n$ make test\n```\n\n## Contribute\n\nDefinitely run:\n```bash\n$ pre-commit install\n```\n\n### Test Coverage\n\n```\n============================= test session starts ==============================\nplatform linux -- Python 3.6.7, pytest-7.0.1, pluggy-1.0.0\nrootdir: /home/runner/work/mffpy/mffpy\nplugins: cov-4.0.0\ncollected 122 items\n\nmffpy/tests/test_cached_property.py .. [ 1%]\nmffpy/tests/test_devices.py ............. [ 12%]\nmffpy/tests/test_dict2xml.py . [ 13%]\nmffpy/tests/test_header_block.py .. [ 14%]\nmffpy/tests/test_mffdir.py .... [ 18%]\nmffpy/tests/test_raw_bin_files.py .................. [ 32%]\nmffpy/tests/test_reader.py ...................... [ 50%]\nmffpy/tests/test_writer.py ........... [ 59%]\nmffpy/tests/test_xml_files.py .......................................... [ 94%]\n.. [ 95%]\nmffpy/tests/test_zipfile.py ..... [100%]\n\n----------- coverage: platform linux, python 3.6.7-final-0 -----------\nName Stmts Miss Cover\n-----------------------------------------------------------------\nmffpy/__init__.py 4 0 100%\nmffpy/bin_files.py 40 2 95%\nmffpy/bin_writer.py 71 0 100%\nmffpy/cached_property.py 25 1 96%\nmffpy/devices.py 10 0 100%\nmffpy/dict2xml.py 31 3 90%\nmffpy/epoch.py 24 3 88%\nmffpy/header_block/__init__.py 1 0 100%\nmffpy/header_block/header_block.py 48 2 96%\nmffpy/header_block/helpers.py 15 0 100%\nmffpy/header_block/optional_header_block.py 32 1 97%\nmffpy/mffdir.py 92 7 92%\nmffpy/raw_bin_files.py 113 0 100%\nmffpy/reader.py 110 2 98%\nmffpy/tests/__init__.py 0 0 100%\nmffpy/tests/conftest.py 11 0 100%\nmffpy/tests/test_cached_property.py 33 0 100%\nmffpy/tests/test_devices.py 12 0 100%\nmffpy/tests/test_dict2xml.py 16 0 100%\nmffpy/tests/test_header_block.py 33 0 100%\nmffpy/tests/test_mffdir.py 30 0 100%\nmffpy/tests/test_raw_bin_files.py 63 0 100%\nmffpy/tests/test_reader.py 96 0 100%\nmffpy/tests/test_writer.py 204 0 100%\nmffpy/tests/test_xml_files.py 202 1 99%\nmffpy/tests/test_zipfile.py 34 0 100%\nmffpy/version.py 1 0 100%\nmffpy/writer.py 71 0 100%\nmffpy/xml_files.py 554 18 97%\nmffpy/zipfile.py 47 0 100%\n-----------------------------------------------------------------\nTOTAL 2023 40 98%\n\n\n============================= 122 passed in 7.19s ==============================\n```\n\n## View the Docs\n\nAll documentation and API guidance are generated from the python doc-strings\nand this README file using pydoc-markdown. To view the docs:\n\n* install pydoc-markdown: `pip install pydoc-markdown`\n* build and run: `pydocmd build; pydocmd serve`\n* Navigate to the [docs](http://localhost:8000)\n\n## Example Code\n\n### Example 1: Basic Information\n\n```python\nimport mffpy\nfo = mffpy.Reader(\"./examples/example_1.mff\")\nprint(\"time and date of the start of recording:\", fo.startdatetime)\nprint(\"number of channels:\", fo.num_channels)\nprint(\"sampling rates:\", fo.sampling_rates, \"(in Hz)\")\nprint(\"durations:\", fo.durations, \"(in sec.)\")\nprint(\"Here's the epoch information\")\nfor i, e in enumerate(fo.epochs):\n print(\"Epoch number\", i)\n print(e)\n```\n\n### Example 2: Reading Samples\n\n```python\nfrom mffpy import Reader\nfo = Reader(\"./examples/example_1.mff\")\nfo.set_unit('EEG', 'uV')\neeg_in_mV, t0_EEG = fo.get_physical_samples_from_epoch(fo.epochs[0], dt=0.1)['EEG']\nfo.set_unit('EEG', 'V')\neeg_in_V, t0_EEG = fo.get_physical_samples_from_epoch(fo.epochs[0], dt=0.1)['EEG']\nprint('data in mV:', eeg_in_mV[0])\nprint('data in V :', eeg_in_V[0])\n```\n\n### Example 3: Reading .mff xml files\n\n```python\nfrom mffpy import XML\ncategories = XML.from_file(\"./examples/example_1.mff/categories.xml\")\nprint(categories['ULRN'])\n```\n\n### Example 4: Writing random numbers into an .mff file\n\n```python\nfrom os.path import join\nfrom datetime import datetime\nimport numpy as np\nfrom mffpy.writer import *\n\n# write 256 channels of 10 data points at a sampling rate of 128 Hz\nB = BinWriter(sampling_rate=128)\nB.add_block(np.random.randn(256, 10).astype(np.float32))\nW = Writer(join('.cache', 'example_4_output.mff'))\nstartdatetime = datetime.strptime('1984-02-18T14:00:10.000000+0100',\n \"%Y-%m-%dT%H:%M:%S.%f%z\")\nW.addxml('fileInfo', recordTime=startdatetime)\nW.add_coordinates_and_sensor_layout(device='HydroCel GSN 256 1.0')\nW.addbin(B)\nW.write()\n```\n\n\n### Example 5: Exporting MFF content to a .json file\n\n```python\nfrom mffpy import Reader, Writer\n\n# Read data from an MFF file\nreader = Reader(\"./examples/example_2.mff\")\ndata = reader.get_mff_content()\n\n# Write data to a JSON file\nwriter = Writer(\".cache/example_5_output.json\")\nwriter.export_to_json(data)\n```\n**Note: for now, the JSON exporting feature only works for segmented mffs files.**\n\n## Specification of the .mff File Format\n\n### .XML Files\n\nXml-type files are specified in \"/schemata/\" using XML Schema Definition. Any\n.xml file can be checked for compliance with the command-line tool xmllint.\nOne can validate your xml files by: `xmllint --schema schemata/categories.xsd\n/path/to/my/file.xml --noout`. We are using the following version of xmllint:\n\n```bash\n$ xmllint --version\nxmllint: using libxml version 20909\ncompiled with: Threads Tree Output Push Reader Patterns Writer SAXv1 FTP\nHTTP DTDValid HTML Legacy C14N Catalog XPath XPointer XInclude Iconv ISO8859X\nUnicode Regexps Automata Expr Schemas Schematron Modules Debug Zlib Lzma\n```\n\nCurrently we describe the following .xml file types:\n\n- [categories.xml](schemata/categories.xsd)\n\n\n## License and Copyright\n\nCopyright 2019 Brain Electrophysiology Laboratory Company LLC\n\nLicensed under the ApacheLicense, Version 2.0(the \"License\");\nyou may not use this module except in compliance with the License.\nYou may obtain a copy of the License at:\n\nhttp: // www.apache.org / licenses / LICENSE - 2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an\n\"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, either express or implied.\n",
"bugtrack_url": null,
"license": "",
"summary": "Reader and Writer for Philips' MFF file format.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/BEL-Public/mffpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97b607e63c68c8ad38a8e76a8c09ba95d7140e903af428e40f33ecacf9c671eb",
"md5": "ace03e00d78533efbc750f59139e6bce",
"sha256": "4c30cfcd2e20962a3c4c0a922590c35315092a6bb65a83951c4849ec251dc720"
},
"downloads": -1,
"filename": "mffpy-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ace03e00d78533efbc750f59139e6bce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 173824,
"upload_time": "2022-11-04T19:42:23",
"upload_time_iso_8601": "2022-11-04T19:42:23.934684Z",
"url": "https://files.pythonhosted.org/packages/97/b6/07e63c68c8ad38a8e76a8c09ba95d7140e903af428e40f33ecacf9c671eb/mffpy-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a09ee05fa3bb72f65fa1fb9a1d21599a8f32e47af7bdedf3bcb41f9d3da6c98",
"md5": "0e122cd142d0121245cefd7eb86c2832",
"sha256": "0658da3c58da3cbd22da9b7faf3aedf000f3140bcdff1e18567aba01be783c6c"
},
"downloads": -1,
"filename": "mffpy-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "0e122cd142d0121245cefd7eb86c2832",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 149277,
"upload_time": "2022-11-04T19:42:25",
"upload_time_iso_8601": "2022-11-04T19:42:25.207464Z",
"url": "https://files.pythonhosted.org/packages/4a/09/ee05fa3bb72f65fa1fb9a1d21599a8f32e47af7bdedf3bcb41f9d3da6c98/mffpy-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-04 19:42:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BEL-Public",
"github_project": "mffpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mffpy"
}
JSON
