Metadata-Version: 2.1
Name: pd-parser
Version: 0.3.dev0
Summary: pd-parser: Take a potentially corrupted photodiode channel and find the event time samples at which it turned on.
Home-page: https://github.com/alexrockhill/pd-parser/
Maintainer: Alex Rockhill
Maintainer-email: aprockhill@mailbox.org
License: BSD (3-clause)
Download-URL: https://github.com/alexrockhill/pd-parser.git
Project-URL: Bug Reports, https://github.com/alexrockhill/pd-parser/issues
Project-URL: Source, https://github.com/alexrockhill/pd-parser
Description: .. pd-parser's documentation
        
        |icon| pd-parser
        ================
        
        The stable version of the documentation can be found `here <https://alexrockhill.github.io/pd-parser/>`_.
        
        .. |icon| image:: https://alexrockhill.github.io/pd-parser/_images/favicon.png
          :width: 25
        
        A tool to parse photodiode events from a possibly corrupted channel, compatible with BIDS formatting.
        
        Corrupted data may look like so:
        
        .. image:: https://alexrockhill.github.io/pd-parser/_images/excluded_events.png
           :width: 800
        
        Which may lead to some excluded events and differences between the events and the expected timing based on the behavior that look like so:
        
        .. image:: https://alexrockhill.github.io/pd-parser/_images/event_diffs.png
           :width: 400
        
        ``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 
        	- anaconda (https://www.anaconda.com/products/individual) *or* 
        	- python (https://www.python.org/downloads/)
        
        	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.
        
        5) Install mne-bids bleeding edge: run ``pip install git+https://github.com/mne-tools/mne-bids.git``
        
        
        Getting Started
        ---------------
        
        1) Plot the examples in a Jupyter notebook
            - In the `Examples page <https://alexrockhill.github.io/pd-parser/auto_examples/dev/index.html>`_, 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 likely need to modify your behavior tsv files so that they 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.
        
        Bug reports
        -----------
        
        Use the `GitHub issue tracker <https://github.com/alexrockhill/pd-parser/issues>`_
        to report bugs.
        
        Contributing
        ------------
        
        Please see our `contributing guide <https://github.com/alexrockhill/pd-parser/blob/master/CONTRIBUTING.md>`_.
        `
        
        Alex Rockhill
        Eugene, OR 2020
Platform: any
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: ~=3.5
Description-Content-Type: text/x-rst
