# midi-psychopy - A Python interface for asynchronous MIDI data collection
The MIDI Interface is a Python package designed to interact with MIDI devices through the
[Mido](https://github.com/mido/mido) library. It provides functionality to receive and
transmit MIDI data asynchronously, which is useful for real-time data collection in
PsychoPy experiments.
## Installation
You can install the MIDI Interface package using pip:
```bash
pip install midi-psychopy
```
## Usage
### Basic Usage - Collecting MIDI Data
```python
import time
import pandas as pd
from midi_controller import MidiController
# Create an instance of MidiController
controller = MidiController(device_name='UM-ONE')
# Start data collection
controller.start_data_collection()
# Let the program run for some time (e.g., 10 seconds)
time.sleep(10)
# Stop data collection
controller.stop_data_collection()
# Access the collected MIDI data
print(controller.sequence_out_full)
```
### In PsychoPy
The setup for using the MidiController in a PsychoPy experiment is similar to the basic usage. Users can follow the
steps below to integrate the MidiController into their experiment:
1. Create a code component in the PsychoPy Builder interface inside the routine where you want to collect MIDI data.
2. Import and instantiate the MidiController object in the "Begin Experiment" tab.
```python
import os
import pandas as pd
from midi_controller import MidiController
# Create an instance of MidiController
# Note that globalClock is a standard PsychoPy variable that can be used to synchronize the MIDI data with the
# PsychoPy global timer.
midi_controller = MidiController(device_name='UM-ONE', psychopy_global_timer=globalClock)
# Initialize a DataFrame to store the collected MIDI data
keypress_data = pd.DataFrame()
# Also initialize a variable to keep track of the trial number
trial_count = 0
# Define the path to save the data
# expInfo is standard PsychoPy variable. make sure to check the name of the identifying variable in your experiment
# (i.e., participant is the default name for the participant ID defined in the "Experiment Info" section of the "Basic"
# tab in the PsychoPy GUI's "Properties" window).
par_id = expInfo['participant']
save_dir = os.path.abspath(f'./')
file_name = f'par_{par_id}.csv'
save_path = f'{save_dir}/{file_name}'
```
3. Start data collection in the "Begin Routine" tab.
```python
# Start data collection
midi_controller.start_data_collection()
```
4. Stop data collection in the "End Routine" tab.
```python
# Stop data collection
midi_controller.stop_data_collection()
```
Alternatively, a conditional statement can also be used in the "Each Frame" tab to terminate data collection based
on certain conditions.
```python
if some_condition:
midi_controller.stop_data_collection()
```
5. Store the collected MIDI data in the "End Experiment" tab.
Because the start_data_collection() method would reset the collected data (sequence_out_full) each time it is called,
the data should be stored locally as a csv file or in a Pandas DataFrame.
```python
temp_out = midi_controller.sequence_out_full
# Add a column to store the trial number. If there are other variables to store, add them here.
temp_out['trial'] = trial_count
trial_count += 1
# Append the collected data to the keypress_data DataFrame
keypress_data = pd.concat([keypress_data, temp_out], ignore_index=True)
# Save the data to a csv file in case the experiment crashes
keypress_data.to_csv(save_path)
```
## Requirements
- Python 3.x
- Mido
- Pandas
## Contributing
Contributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a
pull request on GitHub.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## MIDI Interface
For more details about the underlying MIDI interface used by the MidiController, refer to midi_interface.py.
Raw data
{
"_id": null,
"home_page": "https://github.com/xywang01/midi-psychopy",
"name": "midi-psychopy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "X. Michael Wang, Centre for Motor Control, University of Toronto, Faculty of Kinesiology and Physical Education",
"author_email": "michaelwxy.wang@utoronto.ca",
"download_url": "https://files.pythonhosted.org/packages/90/4b/8833352f44b24be88c8af2eb41da6602cffe79058edd2ff70be7aea3bb07/midi-psychopy-0.0.1.tar.gz",
"platform": null,
"description": "# midi-psychopy - A Python interface for asynchronous MIDI data collection\n\nThe MIDI Interface is a Python package designed to interact with MIDI devices through the \n[Mido](https://github.com/mido/mido) library. It provides functionality to receive and \ntransmit MIDI data asynchronously, which is useful for real-time data collection in\nPsychoPy experiments.\n\n## Installation\n\nYou can install the MIDI Interface package using pip:\n\n```bash\npip install midi-psychopy\n```\n\n## Usage\n\n### Basic Usage - Collecting MIDI Data\n\n```python\nimport time\nimport pandas as pd\nfrom midi_controller import MidiController\n\n# Create an instance of MidiController\ncontroller = MidiController(device_name='UM-ONE')\n\n# Start data collection\ncontroller.start_data_collection()\n\n# Let the program run for some time (e.g., 10 seconds)\ntime.sleep(10)\n\n# Stop data collection\ncontroller.stop_data_collection()\n\n# Access the collected MIDI data\nprint(controller.sequence_out_full)\n```\n\n### In PsychoPy\n\nThe setup for using the MidiController in a PsychoPy experiment is similar to the basic usage. Users can follow the \nsteps below to integrate the MidiController into their experiment:\n\n1. Create a code component in the PsychoPy Builder interface inside the routine where you want to collect MIDI data.\n2. Import and instantiate the MidiController object in the \"Begin Experiment\" tab.\n\n```python\nimport os\nimport pandas as pd\nfrom midi_controller import MidiController\n\n# Create an instance of MidiController\n# Note that globalClock is a standard PsychoPy variable that can be used to synchronize the MIDI data with the\n# PsychoPy global timer.\nmidi_controller = MidiController(device_name='UM-ONE', psychopy_global_timer=globalClock)\n\n# Initialize a DataFrame to store the collected MIDI data\nkeypress_data = pd.DataFrame()\n\n# Also initialize a variable to keep track of the trial number\ntrial_count = 0\n\n# Define the path to save the data\n# expInfo is standard PsychoPy variable. make sure to check the name of the identifying variable in your experiment \n# (i.e., participant is the default name for the participant ID defined in the \"Experiment Info\" section of the \"Basic\" \n# tab in the PsychoPy GUI's \"Properties\" window).\npar_id = expInfo['participant'] \nsave_dir = os.path.abspath(f'./')\nfile_name = f'par_{par_id}.csv'\nsave_path = f'{save_dir}/{file_name}'\n```\n\n3. Start data collection in the \"Begin Routine\" tab.\n\n```python\n# Start data collection\nmidi_controller.start_data_collection()\n```\n\n4. Stop data collection in the \"End Routine\" tab.\n\n```python\n# Stop data collection\nmidi_controller.stop_data_collection()\n```\n\nAlternatively, a conditional statement can also be used in the \"Each Frame\" tab to terminate data collection based \non certain conditions.\n\n```python\nif some_condition:\n midi_controller.stop_data_collection()\n```\n\n5. Store the collected MIDI data in the \"End Experiment\" tab.\n\nBecause the start_data_collection() method would reset the collected data (sequence_out_full) each time it is called,\nthe data should be stored locally as a csv file or in a Pandas DataFrame.\n\n```python\ntemp_out = midi_controller.sequence_out_full\n# Add a column to store the trial number. If there are other variables to store, add them here.\ntemp_out['trial'] = trial_count\n\ntrial_count += 1\n\n# Append the collected data to the keypress_data DataFrame\nkeypress_data = pd.concat([keypress_data, temp_out], ignore_index=True)\n\n# Save the data to a csv file in case the experiment crashes\nkeypress_data.to_csv(save_path)\n```\n## Requirements\n\n- Python 3.x\n- Mido\n- Pandas\n\n## Contributing\nContributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a \npull request on GitHub.\n\n## License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## MIDI Interface\nFor more details about the underlying MIDI interface used by the MidiController, refer to midi_interface.py.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python interface for asynchronous MIDI data collection using PsychoPy",
"version": "0.0.1",
"project_urls": {
"Download": "https://github.com/xywang01/midi-psychopy/archive/refs/tags/0.0.1.tar.gz",
"Homepage": "https://github.com/xywang01/midi-psychopy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "489ade8371ee495c528e3fa8db23d0f28072035f1d9b21132d25d05bfeac4adf",
"md5": "17676b646a3ff66a4a895102e5b21760",
"sha256": "5564a02480b3f8de837118cb0ec36bd0debfa5e7d46163d94eda760d7e1c8a15"
},
"downloads": -1,
"filename": "midi_psychopy-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17676b646a3ff66a4a895102e5b21760",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6694,
"upload_time": "2024-03-25T19:44:33",
"upload_time_iso_8601": "2024-03-25T19:44:33.089275Z",
"url": "https://files.pythonhosted.org/packages/48/9a/de8371ee495c528e3fa8db23d0f28072035f1d9b21132d25d05bfeac4adf/midi_psychopy-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "904b8833352f44b24be88c8af2eb41da6602cffe79058edd2ff70be7aea3bb07",
"md5": "71901f3c43ceef73511ddecd7c4b52f8",
"sha256": "6e5196024ff6251858b85aa8b07a5e776e4c60e70fb28b3b5cddca5967c77afd"
},
"downloads": -1,
"filename": "midi-psychopy-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "71901f3c43ceef73511ddecd7c4b52f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5711,
"upload_time": "2024-03-25T19:44:34",
"upload_time_iso_8601": "2024-03-25T19:44:34.219302Z",
"url": "https://files.pythonhosted.org/packages/90/4b/8833352f44b24be88c8af2eb41da6602cffe79058edd2ff70be7aea3bb07/midi-psychopy-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 19:44:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xywang01",
"github_project": "midi-psychopy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "midi-psychopy"
}
JSON
