# ReproStim Introduction
ReproStim is a video capture and recording suite for neuroimaging and
psychology experiments. Its goal is to provide experimenters with a
complete record of audio and visual stimulation for every data collection
session by making it possible to easily collect high fidelity copies of the
actual stimuli shown to each subject in the form of video files that can be
stored alongside behavioral or neuroimaging data in public repositories.
ReproStim provides for enhanced experimental reproducibility and a safeguard
against data loss in cases of data-collection irregularites. Because
ReproStim provides an exact record of the actual stimuli delivered during
any given experimental session, it makes it possible to precisely reproduce
experimental sessions, even if the original trial sets were randomized and
precise trial details not recorded. In cases of experimental irregularities,
such as aborted fMRI runs, unexpected glitches in trial timing, or
programming errors that cause records of trial conditions to be lost,
valuable data (which can be especially costly in cases of fMRI of ECog, for
example) can be recoded and recovered using the audio-visual record provided
by ReproStim.
ReproStim requires minimal effort on behalf of investigators. Once it is
setup as the default mode within a behavioral lab or neuroimaging center,
investigators can reap the benefits of ReproStim without any additional
effort on the part of invidiual experimenters. When successfully set up,
ReproStim runs in the background, silently collecting, cataloging, and
storing all audio and visual stimulation delivered to experimental subjects.
# Development
## Hardware needed
Before using ReproStim you will need a minimum of the the following
components:
1. Magewell USB Capture Plus device (MWC)
2. Stimulus control computer (SC) with A/V out to presentation device
3. External presentation device (EPD)
4. Video capture computer (VC) with USB-C port
5. Supporting cables including A/V splitter cables
### Simple setup schematic
Given a stimulus presentation computer (SP) that controls the content and
flow of the experimental presentation and presents A/V to experimental
subject on external monitor or projector (EPD), the setup without ReproStim
would be something like:
1. Schematic A.
------ -------
| SC | -- A/V Out --> | EPD |
------ -------
With the addition of ReprosStim, the setup will look like this:
2. Schematic B.
------ -------
| SC | -- A/V Out --> A/V Splitter --> | EPD |
------ | -------
V
------- ------
| MWC | -- USB-C --> | VC |
------- ------
### Original set up without ReproStim
Most experimental setups include something like Schematic A, with a stimulus
control computer (SC) that sends A/V information to the experimental
subject. For example, in the Dartmouth Brain Imaging Center (DBIC),
experimenters can use their own laptop or a dedicated computer in the scan
control room for SC. The External Presentation Device for video (EPDv) in
the DBIC MRI suite is a projector that projects through the wall of the
shielded scan room to a rear-projection screen located at the back of the
MRI scanner bore; and the EPDa (audio) comprises MRI-safe headphones worn on
the subject's head.
The A/V out connections from SC can be any standard as long as you have the
appropriate adapters, dongles, etc. However, if your Video out does not
support embedded audio (e.g. VGA), then you will need a separate audio out
set of splitters and cables. The Magewell device has standard audio ports to
accommodate this eventuality.
Note: Missing from Schematics A and B, is any connection back to SC that
records subject response information. That's because ReproStim is not
interested in how the subject responds. If you like, imagine arrows pointing
from EPD to a "subject" node, and then more arrows pointing from the subject
node to some response input device (RID?) and back to SC for recording...
ReproStim will not interfere.
#### Magewell USB Capture Plus Family device
The current version of ReproStim has only been developed and tested for the
Magewell USB Capture DVI Plus device (MWC) . However, we anticipate that it
will be relatively painless to support at least all devices in the USB
Capture Plus Family. Information about these devices and supporting software
can all be found at www.magewell.com
#### Video Capture computer (VC), AKA ReproStim Server
The video capture computer (VC) does most of the work for ReproStim. The
software running on this computer runs as a service that is always on as
long as the computer is running, which is all the time. Therefore I will
refer to VC also as the ReproStim server. In a nutshell, the server software
monitors the video signal coming from SC into MWC. If there is any video
coming over the connection, it gets recorded for posterity.
Current development of ReproStim, including our working setup at the DBIC,
uses a Linux box running Debian Linux. We anticipate that any Nix/Mac setup
running on a modern desktop will be amply sufficient as a ReproStim Server,
and should be relatively painless to configure.
The current DBIC computer is a small-profile desktop that resides in the
control of the scan suite, quietly recording all video presented to all
subjects.
# reprostim-capture
This subproject is set of native C/C++ tools and utilities to capture
video/audio signals with Magewell USB Capture devices and save it to a file.
More detailed information about dependencies and installation provided in
[reprostim-capture README.md](./src/reprostim-capture/README.md).
# reprostim CLI
Represented as a set of Python tools and utilities under the umbrella of
the `reprostim` library, where each tool is a separate subcommand of
the `reprostim` CLI.
## Dependencies
`qr-parse` subcommand requires `zbar` to be installed:
- On Debian
```shell
apt-get install -y libzbar0
````
- On MacOS
```shell
brew install zbar
```
NOTE: Consider this conversation in case of problems to install it @MacOS:
https://github.com/ReproNim/reprostim/pull/124#issuecomment-2599291577
`timesync-stimuli` subcommand requires in `psychopy` and `portaudio` to
be installed:
- On Debian
```shell
apt-get install portaudio19-dev
```
- On MacOS
```shell
brew install portaudio
```
## Installation
Make sure you have strict Python version/venv especially for subcommands working
with psychopy like `timesync-stimuli`. Recommended Python version is 3.10 ATM:
```shell
python3.10 -m venv venv
source venv/bin/activate
pip install --upgrade pip
python3 --version
```
Then it can be installed from PyPI:
```shell
pip install reprostim
```
## Build
To build the project, use `hatch` and `venv` with preferable Python version:
```shell
# first setup python and hatch
python3.10 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install hatch
# build reprostim package
hatch build reprostim
# optionally re-create env
hatch env remove
hatch env create
# install all extra dependencies
hatch run pip install .[all]
# run some reprostim commands, e.g.:
hatch run reprostim --help
hatch run reprostim --version
hatch run reprostim echo 'Hello ReproStim CLI!'
```
## Subdirectories Structure
### src/reprostim
Contains all code for `reprostim` library.
### src/reprostim-capture
Contains all code needed for setting up video capture. This includes C++
code for interfacing with the video capture device, and scheme for setting
up a video-capture "server", along with helper utilities.
### tests
Directory with reprostim pytests and test data.
### **_Obsolete:_** QRCoding
Contains utilities for embedding QR codes in experimental stimulus-delivery
programs, such as PsychoPy, or PsychToolbox scripts.
### **_Obsolete:_** Parsing
Contains code needed for segmenting videos to include just the parts of the
videos that are demarcated by embedded QR codes marking the beginning and
end of experimental runs. There are also helper tools for identifying
experimental runs and matching them to the parent experimental paradigm and
neuroimaging data acquisitions.
# Hardware Installation and Configuration
## Setup USB device with "udev" access
The `reprostim-videocapture` utility internally uses Magewell Capture SDK and to
make it working properly should be executed under "root" account or in case of
other account - special "udev" rules should be applied there. Program will
produce following error when executed in environment without proper ownership
and permissions for informational purposes:
ERROR[003]: Access or permissions issue. Please check /etc/udev/rules.d/ configuration and docs.
For more information refer to item #14 from Magewell FAQ on https://www.magewell.com/kb/detail/010020005/All :
14. Can the example codes associated with USB Capture (Plus) devices in SDKv3 work
without root authority (sudo) on Linux?
Yes. Click here to download the file "189-usbdev.rules" (http://www.magewell.com/files/sdk/189-usbdev.zip) ,
move it to the directory "/etc/udev/rules.d", and then restart your computer.
NOTE: Also make sure that no other processes like ffmpeg, vlc, etc are using this video device, as
it can accidentally produce the same error message ERROR[003].
### 1) Identify the USB Device:
This is optional step, only for information purposes:
```shell
lsusb
```
And locate line with device, e.g.:
Bus 004 Device 012: ID 2935:0008 Magewell USB Capture DVI+
In this sample, 2935 is the "Vendor ID", and 0008 is the "Product ID".
Optionally Magewell device name and serial number can be quickly checked with this command:
```shell
lsusb -d 2935: -v | grep -E 'iSerial|iProduct'
```
### 2) Create "udev" rules
Create text file under "/etc/udev/rules.d/189-reprostim.rules" location with
appropriate content depending on system type.
For an active/desktop user logged in via session manager it should be like:
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="2935", TAG+="uaccess"
For a daemon configuration we should provide explicit permissions like:
SUBSYSTEM=="usb", ATTR{idVendor}=="2935", MODE="0660", OWNER="reprostim", GROUP="plugdev"
Note: we can see that "ATTR{idVendor}" value 2935 is equal to one we got in
step 1) from lsusb utility.
Also sample udev rules configuration added to project under
"src/reprostim-capture/etc/udev/189-reprostim.rules" location.
Note: make sure the file has owner "root", group "root" and 644 permissions:
```shell
ls -l /etc/udev/rules.d/189*
````
```
-rw-r--r-- 1 root root 72 ... /etc/udev/rules.d/189-reprostim.rules
```
### 3) Add user to "plugdev" group
Make sure the user running `reprostim-videocapture` utility is a member of the
"plugdev" group, e.g.:
```shell
sudo usermod -aG plugdev TODO_user
```
### 4) Restart computer
Restart computer to make changes effect.
Note: we tested "sudo udevadm control --reload-rules" command without OS
restart, but somehow it didn't help, and complete restart was necessary
anyway.
## TODO:
- Build (per above) and install in the PATH
- TODO: cron job
- TODO: add user/group
- ...
- [Parsing/repro-vidsort](./Parsing/repro-vidsort) script (has hardcoded paths) sorts from `incoming/` to
folders per DICOM accession
-
Raw data
{
"_id": null,
"home_page": null,
"name": "reprostim",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ReproStim, reprostim-screncapture, reprostim-videocapture",
"author": null,
"author_email": "ReproNim Team <info@repronim.org>, Yaroslav Halchenko <yoh@dartmouth.edu>, Andy Connolly <andrew.c.connolly@dartmouth.edu>, Horea Christian <chr@chymera.eu>, Vadim Melnik <vmelnik@docsultant.com>",
"download_url": "https://files.pythonhosted.org/packages/1b/fc/88b8ecea91d5a96c505363cb9006e8ae7b6efaad09f7a0d058cead542ff0/reprostim-0.7.8.tar.gz",
"platform": null,
"description": "# ReproStim Introduction\n\nReproStim is a video capture and recording suite for neuroimaging and\npsychology experiments. Its goal is to provide experimenters with a\ncomplete record of audio and visual stimulation for every data collection\nsession by making it possible to easily collect high fidelity copies of the\nactual stimuli shown to each subject in the form of video files that can be\nstored alongside behavioral or neuroimaging data in public repositories.\n\nReproStim provides for enhanced experimental reproducibility and a safeguard\nagainst data loss in cases of data-collection irregularites. Because\nReproStim provides an exact record of the actual stimuli delivered during\nany given experimental session, it makes it possible to precisely reproduce\nexperimental sessions, even if the original trial sets were randomized and\nprecise trial details not recorded. In cases of experimental irregularities,\nsuch as aborted fMRI runs, unexpected glitches in trial timing, or\nprogramming errors that cause records of trial conditions to be lost,\nvaluable data (which can be especially costly in cases of fMRI of ECog, for\nexample) can be recoded and recovered using the audio-visual record provided\nby ReproStim.\n\nReproStim requires minimal effort on behalf of investigators. Once it is\nsetup as the default mode within a behavioral lab or neuroimaging center,\ninvestigators can reap the benefits of ReproStim without any additional\neffort on the part of invidiual experimenters. When successfully set up,\nReproStim runs in the background, silently collecting, cataloging, and\nstoring all audio and visual stimulation delivered to experimental subjects.\n\n# Development\n\n## Hardware needed\n\nBefore using ReproStim you will need a minimum of the the following\ncomponents:\n\n1. Magewell USB Capture Plus device (MWC)\n\n2. Stimulus control computer (SC) with A/V out to presentation device\n\n3. External presentation device (EPD)\n\n4. Video capture computer (VC) with USB-C port\n\n5. Supporting cables including A/V splitter cables\n\n### Simple setup schematic\n\nGiven a stimulus presentation computer (SP) that controls the content and\nflow of the experimental presentation and presents A/V to experimental\nsubject on external monitor or projector (EPD), the setup without ReproStim\nwould be something like:\n\n1. Schematic A.\n\n ------ -------\n | SC | -- A/V Out --> | EPD |\n ------ -------\n\n With the addition of ReprosStim, the setup will look like this:\n\n2. Schematic B.\n\n ------ -------\n | SC | -- A/V Out --> A/V Splitter --> | EPD |\n ------ | -------\n V\n ------- ------\n | MWC | -- USB-C --> | VC |\n ------- ------\n\n### Original set up without ReproStim\n\nMost experimental setups include something like Schematic A, with a stimulus\ncontrol computer (SC) that sends A/V information to the experimental\nsubject. For example, in the Dartmouth Brain Imaging Center (DBIC),\nexperimenters can use their own laptop or a dedicated computer in the scan\ncontrol room for SC. The External Presentation Device for video (EPDv) in\nthe DBIC MRI suite is a projector that projects through the wall of the\nshielded scan room to a rear-projection screen located at the back of the\nMRI scanner bore; and the EPDa (audio) comprises MRI-safe headphones worn on\nthe subject's head.\n\nThe A/V out connections from SC can be any standard as long as you have the\nappropriate adapters, dongles, etc. However, if your Video out does not\nsupport embedded audio (e.g. VGA), then you will need a separate audio out\nset of splitters and cables. The Magewell device has standard audio ports to\naccommodate this eventuality.\n\nNote: Missing from Schematics A and B, is any connection back to SC that\nrecords subject response information. That's because ReproStim is not\ninterested in how the subject responds. If you like, imagine arrows pointing\nfrom EPD to a \"subject\" node, and then more arrows pointing from the subject\nnode to some response input device (RID?) and back to SC for recording...\nReproStim will not interfere.\n\n#### Magewell USB Capture Plus Family device\n\nThe current version of ReproStim has only been developed and tested for the\nMagewell USB Capture DVI Plus device (MWC) . However, we anticipate that it\nwill be relatively painless to support at least all devices in the USB\nCapture Plus Family. Information about these devices and supporting software\ncan all be found at www.magewell.com\n\n#### Video Capture computer (VC), AKA ReproStim Server\n\nThe video capture computer (VC) does most of the work for ReproStim. The\nsoftware running on this computer runs as a service that is always on as\nlong as the computer is running, which is all the time. Therefore I will\nrefer to VC also as the ReproStim server. In a nutshell, the server software\nmonitors the video signal coming from SC into MWC. If there is any video\ncoming over the connection, it gets recorded for posterity.\n\nCurrent development of ReproStim, including our working setup at the DBIC,\nuses a Linux box running Debian Linux. We anticipate that any Nix/Mac setup\nrunning on a modern desktop will be amply sufficient as a ReproStim Server,\nand should be relatively painless to configure.\n\nThe current DBIC computer is a small-profile desktop that resides in the\ncontrol of the scan suite, quietly recording all video presented to all\nsubjects.\n\n# reprostim-capture\n\nThis subproject is set of native C/C++ tools and utilities to capture\nvideo/audio signals with Magewell USB Capture devices and save it to a file.\nMore detailed information about dependencies and installation provided in\n[reprostim-capture README.md](./src/reprostim-capture/README.md).\n\n\n# reprostim CLI\n\nRepresented as a set of Python tools and utilities under the umbrella of\nthe `reprostim` library, where each tool is a separate subcommand of\nthe `reprostim` CLI.\n\n## Dependencies\n\n`qr-parse` subcommand requires `zbar` to be installed:\n - On Debian\n ```shell\n apt-get install -y libzbar0\n ````\n - On MacOS\n ```shell\n brew install zbar\n ```\n NOTE: Consider this conversation in case of problems to install it @MacOS:\n https://github.com/ReproNim/reprostim/pull/124#issuecomment-2599291577\n\n`timesync-stimuli` subcommand requires in `psychopy` and `portaudio` to\nbe installed:\n - On Debian\n ```shell\n apt-get install portaudio19-dev\n ```\n - On MacOS\n ```shell\n brew install portaudio\n ```\n\n\n## Installation\n\nMake sure you have strict Python version/venv especially for subcommands working\nwith psychopy like `timesync-stimuli`. Recommended Python version is 3.10 ATM:\n\n```shell\n python3.10 -m venv venv\n source venv/bin/activate\n pip install --upgrade pip\n python3 --version\n```\n\nThen it can be installed from PyPI:\n\n```shell\n pip install reprostim\n```\n\n## Build\n\nTo build the project, use `hatch` and `venv` with preferable Python version:\n\n```shell\n # first setup python and hatch\n python3.10 -m venv venv\n source venv/bin/activate\n pip install --upgrade pip\n pip install hatch\n\n # build reprostim package\n hatch build reprostim\n\n # optionally re-create env\n hatch env remove\n hatch env create\n\n # install all extra dependencies\n hatch run pip install .[all]\n\n # run some reprostim commands, e.g.:\n hatch run reprostim --help\n hatch run reprostim --version\n hatch run reprostim echo 'Hello ReproStim CLI!'\n```\n\n## Subdirectories Structure\n\n### src/reprostim\n\nContains all code for `reprostim` library.\n\n### src/reprostim-capture\n\nContains all code needed for setting up video capture. This includes C++\ncode for interfacing with the video capture device, and scheme for setting\nup a video-capture \"server\", along with helper utilities.\n\n### tests\n\nDirectory with reprostim pytests and test data.\n\n\n### **_Obsolete:_** QRCoding\n\nContains utilities for embedding QR codes in experimental stimulus-delivery\nprograms, such as PsychoPy, or PsychToolbox scripts.\n\n### **_Obsolete:_** Parsing\n\nContains code needed for segmenting videos to include just the parts of the\nvideos that are demarcated by embedded QR codes marking the beginning and\nend of experimental runs. There are also helper tools for identifying\nexperimental runs and matching them to the parent experimental paradigm and\nneuroimaging data acquisitions.\n\n# Hardware Installation and Configuration\n\n## Setup USB device with \"udev\" access\n\nThe `reprostim-videocapture` utility internally uses Magewell Capture SDK and to\nmake it working properly should be executed under \"root\" account or in case of\nother account - special \"udev\" rules should be applied there. Program will\nproduce following error when executed in environment without proper ownership\nand permissions for informational purposes:\n\n ERROR[003]: Access or permissions issue. Please check /etc/udev/rules.d/ configuration and docs.\n\nFor more information refer to item #14 from Magewell FAQ on https://www.magewell.com/kb/detail/010020005/All :\n\n 14. Can the example codes associated with USB Capture (Plus) devices in SDKv3 work\n without root authority (sudo) on Linux?\n\n Yes. Click here to download the file \"189-usbdev.rules\" (http://www.magewell.com/files/sdk/189-usbdev.zip) ,\n move it to the directory \"/etc/udev/rules.d\", and then restart your computer.\n\nNOTE: Also make sure that no other processes like ffmpeg, vlc, etc are using this video device, as\nit can accidentally produce the same error message ERROR[003].\n\n### 1) Identify the USB Device:\n\nThis is optional step, only for information purposes:\n\n```shell\n lsusb\n```\n\nAnd locate line with device, e.g.:\n\n Bus 004 Device 012: ID 2935:0008 Magewell USB Capture DVI+\n\nIn this sample, 2935 is the \"Vendor ID\", and 0008 is the \"Product ID\".\n\nOptionally Magewell device name and serial number can be quickly checked with this command:\n\n```shell\n lsusb -d 2935: -v | grep -E 'iSerial|iProduct'\n```\n\n### 2) Create \"udev\" rules\nCreate text file under \"/etc/udev/rules.d/189-reprostim.rules\" location with\nappropriate content depending on system type.\n\nFor an active/desktop user logged in via session manager it should be like:\n\n ACTION==\"add\", SUBSYSTEM==\"usb\", ATTR{idVendor}==\"2935\", TAG+=\"uaccess\"\n\nFor a daemon configuration we should provide explicit permissions like:\n\n SUBSYSTEM==\"usb\", ATTR{idVendor}==\"2935\", MODE=\"0660\", OWNER=\"reprostim\", GROUP=\"plugdev\"\n\nNote: we can see that \"ATTR{idVendor}\" value 2935 is equal to one we got in\nstep 1) from lsusb utility.\n\nAlso sample udev rules configuration added to project under\n\"src/reprostim-capture/etc/udev/189-reprostim.rules\" location.\n\nNote: make sure the file has owner \"root\", group \"root\" and 644 permissions:\n\n```shell\n ls -l /etc/udev/rules.d/189*\n````\n```\n -rw-r--r-- 1 root root 72 ... /etc/udev/rules.d/189-reprostim.rules\n```\n\n### 3) Add user to \"plugdev\" group\nMake sure the user running `reprostim-videocapture` utility is a member of the\n\"plugdev\" group, e.g.:\n\n```shell\n sudo usermod -aG plugdev TODO_user\n```\n\n### 4) Restart computer\nRestart computer to make changes effect.\n\nNote: we tested \"sudo udevadm control --reload-rules\" command without OS\nrestart, but somehow it didn't help, and complete restart was necessary\nanyway.\n\n\n## TODO:\n\n- Build (per above) and install in the PATH\n- TODO: cron job\n- TODO: add user/group\n- ...\n- [Parsing/repro-vidsort](./Parsing/repro-vidsort) script (has hardcoded paths) sorts from `incoming/` to\n folders per DICOM accession\n-\n",
"bugtrack_url": null,
"license": null,
"summary": "ReproStim is a video capture and recording suite for neuroimaging and psychology experiments.",
"version": "0.7.8",
"project_urls": {
"Documentation": "https://github.com/ReproNim/reprostim",
"Issues": "https://github.com/ReproNim/reprostim/issues",
"Source": "https://github.com/ReproNim/reprostim"
},
"split_keywords": [
"reprostim",
" reprostim-screncapture",
" reprostim-videocapture"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7f23036a79b42c4ea780625e290178af26b310f935f9f37d849b1b7e9f4b21fb",
"md5": "e8e2aba710c5008ed3b3643a86c1d3c8",
"sha256": "41f0777b8e7ef6dd1d8661cecd1984f9f623db8f6cf3c016cf89d32e72cf8f39"
},
"downloads": -1,
"filename": "reprostim-0.7.8-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8e2aba710c5008ed3b3643a86c1d3c8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 68682,
"upload_time": "2025-02-07T13:13:46",
"upload_time_iso_8601": "2025-02-07T13:13:46.914695Z",
"url": "https://files.pythonhosted.org/packages/7f/23/036a79b42c4ea780625e290178af26b310f935f9f37d849b1b7e9f4b21fb/reprostim-0.7.8-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1bfc88b8ecea91d5a96c505363cb9006e8ae7b6efaad09f7a0d058cead542ff0",
"md5": "37f687478b7da3583d25db68d9158b43",
"sha256": "f735714a725998816617df9ab84c9e0f79e6749544b0ab1d27d0fd0c5672d6c2"
},
"downloads": -1,
"filename": "reprostim-0.7.8.tar.gz",
"has_sig": false,
"md5_digest": "37f687478b7da3583d25db68d9158b43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 428121,
"upload_time": "2025-02-07T13:13:48",
"upload_time_iso_8601": "2025-02-07T13:13:48.888903Z",
"url": "https://files.pythonhosted.org/packages/1b/fc/88b8ecea91d5a96c505363cb9006e8ae7b6efaad09f7a0d058cead542ff0/reprostim-0.7.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-07 13:13:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ReproNim",
"github_project": "reprostim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "reprostim"
}
JSON
