Skip to main content
https://zenodo.org/badge/287045175.svg https://joss.theoj.org/papers/10.21105/joss.02674/status.svg

icon pd-parser

The stable version of the documentation can be found here.

A tool to parse photodiode events from a possibly corrupted channel, compatible with BIDS formatting.

Corrupted data may look like so:

https://alexrockhill.github.io/pd-parser/_images/excluded_events.png

Which may lead to some excluded events and differences between the events and the expected timing based on the behavior that look like so:

https://alexrockhill.github.io/pd-parser/_images/event_diffs.png

pd-parser matches deflection events on a potentially corrupted photodiode channel with time-stamped events generated by the computer that changes the luminance sensed by the photodiode. This tool is for research that needs high-performance timing synchronization, especially in clinical settings where having a channel record a photodiode is the best or only method of task-integration available and where the photodiode is especially likely to be corrupted by unavoidable environmental noise. First, photodiode time series data is extracted from an electrophysiology data file. The photodiode data can be on a single channel or two channels that are then bipolar re-referenced. Candidate photodiode events from this photodiode time series are identified based on matching a square-wave template. Time-stamped events from the computer triggering changes to the luminance of the photodiode are read from a tab-separated value (tsv) file, and the best alignment of these events relative to photodiode deflection events is then found while accounting for any drift between computer clocks of separate recording devices. Events are excluded where when the difference between the photodiode event and the time-stamped event are greater then a specified threshold. This discrepancy in timing can occur when a monitor doesn’t update the display for one or more frames most often because the computer paused execution of the program controlling luminance to do background tasks. Additional events can then be added using the time of each event relative to the corresponding photodiode-synchronized event. Adding relative events may be needed for any number of reasons. For instance, events may occur too rapidly in series relative to the monitor refresh rate to have a photodiode deflection for each event, or the photodiode deflection may effect neighboring channels on the amplifier with its large deflection and so be placed synchronous with an event, such the onset of fixation, where it will not effect other, more important events. Finally, the raw data and events data can be saved in brain imaging data structure (BIDS) format, which allows the behavioral events to be stored in a standardized format without modifying the underlying raw electrophysiology file.

Installation Instructions

  1. Install the latest version python using of anaconda

    and make sure that you add the installed packages to the path.

  2. Optional Create virtual environment to keep the particular versions of software relevant to this project from getting changed. In a terminal, run
    • conda create --name myenv and then conda activate myenv or

    • python -m venv /path/to/env/myenv and then source /path/to/env/myenv/bin/activate

  3. Run conda install pip in a terminal, and then ensure that when you run which pip in a terminal it points to the where the anaconda or python you just installed is.

  4. Run pip install pd-parser in a terminal.

Getting Started

  1. Plot the examples in a Jupyter notebook
    • In the Examples page, click on ‘Download all examples in Jupyter notebooks’

    • Unzip the downloaded file

    • Run pip install jupyter

    • Point the terminal to the folder where the files you downloaded are by running cd /path/to/downloads/

    • Run jupyter notebook in the terminal, this will pop up a webpage in your default browser.

    • Change %matplotlib inline to just %matplotlib to pop the plots out interactively instead of below the cell in the notebook.

    • Run each cell, change the parameters and explore the example.

  2. Try pd-parser on your photodiode data. You will need:
    • Time series data in .fif, .edf, .bdf, .vhdr, or .set format like the data from the first cell of this example. If you do not know the name of the photodiode channel, the data will be plotted and you will be asked to find it so it is not necessary to pass the name.

    • A behavior file in tab-separated value (tsv) format like the one created in the second cell of this example. The file needs to have:
      • One column corresponding to the expected event in seconds, called by default fix_onset_time

      • Optionally Other columns with relative event times in seconds.

    • How to run:
      • See the example notebooks for information on how to extract parameters for pd_parser, use the parameters to detect events, and saving the events and data in a BIDS-compatible format.

Bug reports

Use the GitHub issue tracker to report bugs.

Contributing

Please see our contributing guide. `

Alex Rockhill Eugene, OR 2020

Metadata

Release files for pd-parser 0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for pd-parser 0.8
File Interpreter ABI Platform Actions
pd_parser-0.8-py3-none-any.whl Python 3 none any Details for pd_parser-0.8-py3-none-any.whl

Release files / pd_parser-0.8-py3-none-any.whl

Download URL pd_parser-0.8-py3-none-any.whl
Size 23.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3b64780d77eef45f44a6786c39c8b549f61edf2e76f21e218add5085c9849de6
BLAKE2b-256 checksum
How to use checksums
affa838fe6017e9eaab88c53a93c33298b15b5947fae6ab320fed838cd884a39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.10.5

Security for pd-parser 0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page