تنزيل BciPy - تنزيل رمز المصدر BciPy

BciPy

كود الذكاء الاصطناعي

2.0.0rc4

تنزيل

BCIPY: برنامج واجهة الحاسوب الدماغ في Python

BCIPY هي مكتبة لإجراء تجارب واجهة الحاسوب في الدماغ في بيثون. يعمل كتطبيق مستقل لجمع البيانات التجريبية أو يمكنك أخذ الأدوات التي تحتاجها والبدء في ترميز نظامك الخاص. راجع وثائق BCIPY الرسمية بما في ذلك الانتماءات والمزيد من معلومات السياق هنا.

سيتم تشغيله على أحدث Windows (7 ، 10 ، 11) ، Linux (Ubuntu 22.04) و MacOS (Big Sur). قد تعمل الإصدارات الأخرى أيضًا ، ولكنها ليست مضمونة. لمشاهدة الإصدارات المدعومة وأنظمة التشغيل اعتبارًا من هذا الإصدار ، انظر هنا: BCIPY Builds.

يرجى الاستشهاد بنا عند استخدام!

 Memmott, T., Koçanaoğulları, A., Lawhead, M., Klee, D., Dudy, S., Fried-Oken, M., & Oken, B. (2021). BciPy: brain–computer interface software in Python. Brain-Computer Interfaces, 1-18.

التبعيات

يتطلب هذا المشروع Python 3.8 أو 3.9. يرجى الاطلاع على الملاحظات أدناه للحصول على تبعيات إضافية لنظام التشغيل قبل التثبيت والرجوع إلى وثائقنا/الأسئلة الشائعة لمزيد من المعلومات: https://bcipy.github.io/hardware-os-config/

Linux

ستحتاج إلى تثبيت المتطلبات الأساسية المحددة في scriptsshelllinux_requirements.sh وكذلك pip install attrdict3 .

النوافذ

إذا كنت تستخدم جهاز Windows ، فستحتاج إلى تثبيت أدوات إنشاء Microsoft Visual C ++.

بيثون 3.9 فقط! ستحتاج إلى تثبيت Pywinhook يدويًا. انظر هنا للحصول على ملف العجلات المناسب ( pyWinhook‑1.6.2‑cp39‑cp39‑win_amd64.whl ). ثم قم بتشغيل pip install <path_to_wheel_file> . ندرج أيضًا ملف العجلات 64 بت في .bcipy/downloads/ directory.

ماك

إذا كنت تستخدم جهاز Mac ، فستحتاج إلى تثبيت أدوات سطر أوامر Xcode وتمكينها. xcode-select --install . إذا كنت تستخدم شريحة M1/2 ، فستحتاج إلى استخدام البرنامج النصي للتثبيت في scripts/shell/m2chip_install.sh لتثبيت المتطلبات الأساسية. قد تحتاج أيضًا إلى استخدام محطة Rosetta لتشغيل البرنامج النصي للتثبيت ، لكن هذا لم يكن ضروريًا في اختبارنا باستخدام رقائق M2.

إذا كنت تستخدم ZSH ، بدلاً من Bash ، قد تواجه خطأ في الفصل عند تشغيل BCIPY. ويرجع ذلك إلى مشكلة في تعتمد على النفس مع عدم وجود إصلاح معروف حتى الآن. يرجى استخدام bash بدلا من ZSH في الوقت الحالي.

تثبيت

إعداد bcipy

من أجل تشغيل BCIPY على جهاز الكمبيوتر الخاص بك ، بعد اتباع التبعيات أعلاه ، ستحتاج إلى تثبيت حزمة BCIPY.

للتثبيت للاستخدام محليًا واستخدام واجهة المستخدم الرسومية:

git clone https://github.com/bcipy/bcipy.git
تغيير الدليل في المحطة الخاصة بك إلى دليل repo.
تثبيت حزمة نموذج لغة Kenlm. pip install kenlm==0.1 --global-option="--max_order=12" .
تثبيت Psychopy مع عدم وجود تبعيات. pip install psychopy==2023.2.1 --no-deps .
تثبيت bcipy في وضع التطوير. pip install -e .

إذا كانت ترغب في أحدث إصدار من PYPI وبناء باستخدام الوحدات النمطية:

pip install bcipy

بالتناوب ، إذا تم تثبيت صنع ، فيمكنك تشغيل الأمر المتابعة لتثبيت:

 # install in development mode
make dev-install

استخدام العميل

قم بتشغيل بروتوكول التجربة أو المهمة

استدعاء بروتوكول التجربة أو المهمة مباشرة باستخدام أداة سطر الأوامر bcipy .

استخدم علامة المساعدة لرؤية خيارات الإدخال المتاحة الأخرى: bcipy --help
- يمكنك تمرير سماتها بالأعلام ، إذا رغبت في ذلك.
  - التشغيل مع معرف المستخدم والمهمة:
    - bcipy --user "bci_user" --task "RSVP Calibration"
  - تشغيل مع معرف المستخدم والمهام مع بروتوكول مسجل:
    - bcipy --user "bci_user" --experiment "default"
  - تشغيل بيانات مزيفة:
    - bcipy --fake
  - الجري بدون تصورات:
    - bcipy --noviz
  - تشغيل تنبيهات بعد كل تنفيذ مهمة:
    - bcipy --alert
  - تشغيل مع معلمات مخصصة:
    - bcipy --parameters "path/to/valid/parameters.json"

تدريب نموذج إشارة على نماذج bcipy مسجلة

لتدريب نموذج الإشارة (حاليًا PCARDAKDE ) ، قم بتشغيل الأمر التالي بعد تثبيت bcipy:

bcipy-train

استخدم علامة المساعدة لرؤية خيارات الإدخال المتاحة الأخرى: bcipy-train --help
- يمكنك تمرير سماتها بالأعلام ، إذا رغبت في ذلك.
  - التشغيل بدون نافذة تدعو إلى مجلد جلسة البيانات:
    - bcipy-train -d path/to/data
  - تشغيل مع تصورات البيانات (ERPs ، وما إلى ذلك):
    - bcipy-train -v
  - تشغيل مع تصورات البيانات التي لا تظهر ، ولكن حفظ للملف:
    - bcipy-train -s
  - الجري بدقة متوازنة:
    - bcipy-train --balanced-acc
  - تشغيل تنبيهات بعد كل تنفيذ مهمة:
    - bcipy-train --alert
  - تشغيل مع معلمات مخصصة:
    - bcipy-train -p "path/to/valid/parameters.json"

تصور بيانات ERP من جلسة مع علامات الهدف / غير المستهدفة

لإنشاء مخططات يمكن عرضها أو حفظها بعد جمع البيانات ، قم بتشغيل الأمر التالي بعد تثبيت BCIPY:

bcipy-erp-viz

استخدم علامة المساعدة لرؤية خيارات الإدخال المتاحة الأخرى: bcipy-erp-viz --help
- يمكنك تمرير سماتها بالأعلام ، إذا رغبت في ذلك.
  - التشغيل بدون نافذة تدعو إلى مجلد جلسة البيانات:
    - bcipy-erp-viz -s path/to/data
  - تشغيل مع تصورات البيانات (ERPs ، وما إلى ذلك):
    - bcipy-erp-viz --show
  - تشغيل مع تصورات البيانات التي لا تظهر ، ولكن حفظ للملف:
    - bcipy-erp-viz --save
  - تشغيل مع معلمات مخصصة (افتراضي في BCIPY/Parameters/Parameters.json):
    - bcipy-erp-viz -p "path/to/valid/parameters.json"

BCIPY محاكاة الاستخدام

يمكن تشغيل جهاز المحاكاة باستخدام أداة سطر الأوامر bcipy-sim .

السابق. bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5

قم بتشغيل bcipy-sim --help للتوثيق أو انظر README في وحدة Simulator.

استخدام الحزمة

 from bcipy . helpers import system_utils
system_utils . get_system_info ()

استخدام واجهة المستخدم الرسومية

قم بتشغيل الأمر التالي في المحطة الخاصة بك لبدء واجهة المستخدم الرسومية Bcipy:

python bcipy/gui/BCInterface.py

بالتناوب ، إذا تم تثبيت Make ، فيمكنك تشغيل الأمر المتابعة لبدء واجهة المستخدم الرسومية من دليل Bcipy Root:

make bci-gui

مسرد

المحفزات : رسالة واحدة أو نغمة أو صورة معروضة (بشكل عام في استفسار). المفرد = التحفيز ، الجمع = المحفزات.

التجربة : يتم عرض مجموعة من البيانات بعد المحفزات. أ ----

الاستفسار : مجموعة المحفزات بعد صليب التثبيت في مهمة إملائية لجمع نية المستخدم. أ ---- ب --- ج ----

السلسلة : تحتوي كل سلسلة على استفسار واحد على الأقل. يتم اتخاذ قرار رسالة/أيقونة بعد سلسلة في مهمة إملائية.

الجلسة : البيانات التي تم جمعها لمهمة. تتألف من البيانات الوصفية حول المهمة وقائمة السلسلة.

البروتوكول : مجموعة من المهام والإجراءات التي سيتم تنفيذها في جلسة. يتم تعريف هذا على أنه في التجارب ويمكن تسجيله باستخدام واجهة المستخدم الرسومية BCIPY.

المهمة : تصميم تجريبي مع المحفزات والتجارب والاستفسارات والسلسلة للاستخدام في BCI. على سبيل المثال ، "معايرة RSVP" هي مهمة.

الوضع : عناصر التصميم الشائعة بين أنواع المهام. على سبيل المثال ، المعايرة والتهجئة الحرة هي أوضاع.

النموذج : عرض نموذج مع خصائص وأوضاع فريدة. السابق. العرض المرئي السريع (RSVP) ، مصفوفة الإملاء ، إمكانات المرئية المستقرة للدولة المستقرة (SSVEP).

الوحدات الأساسية

هذه قائمة من الوحدات الرئيسية ووظائفها. ستحتوي كل وحدة نمطية على readme والتوضيح والاختبارات الخاصة بها. يرجى التحقق منها لمزيد من المعلومات!

acquisition : الحصول على البيانات ، يعيد السلسلة الزمنية المطلوبة ، ويحفظ للملف في نهاية الجلسة.
display : مقابض عرض المحفزات على الشاشة وتوقيت توقيت المحفزات.
signal : نماذج إشارة EEG ، نماذج إشارة النظرة ، المرشحات ، المعالجة ، المقيمين والمشاهدين.
واجهة المستخدم gui : واجهة المستخدم النهائي في مهام BCI مسجلة وتحرير المعلمة. انظر bcinterface.py.
helpers : وظائف مفيدة مطلوبة للتفاعلات بين الوحدات ، والإدخال/الإخراج الأساسية ، وتصور البيانات.
language : يعطي احتمالات الرموز التالية أثناء الكتابة.
parameters : موقع معلمات JSON. يتضمن ذلك المعلمات. json (تكوين التجربة / التطبيق الرئيسية) و device.json (سجل الجهاز والتكوين).
static : الصورة والصوت المحفزات ، أدلة MISC ، والنصوص القابلة للقراءة لـ GUI.
task : تم تنفيذ BCIPY مهام المستخدم. المجموعة الرئيسية من وحدات BCI للاستخدام أثناء التجارب المختلفة. السابق. معايرة RSVP.
feedback : آليات التغذية المرتدة للمنبهات الصوتية والبصرية.
main : منفذي التجارب. نقطة الدخول الرئيسية في التطبيق
config : معلمات التكوين للتطبيق ، بما في ذلك المسارات وأسماء ملفات البيانات.
simulator : يوفر الدعم لتشغيل عمليات المحاكاة القائمة على البيانات التي تم جمعها مسبقًا.

نماذج

انظر bcipy/task/README.md لمزيد من المعلومات حول جميع النماذج المدعومة والمهام والإجراءات والأوضاع. فيما يلي النماذج المدعومة والتحقق من صحتها:

RSVPKeyboard

 *RSVP KeyboardTM* is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called rapid serial visual presentation (RSVP). In RSVP, the options are presented rapidly at a single location with a temporal separation. Similarly in RSVP KeyboardTM, the symbols (the letters and additional symbols) are shown at the center of screen. When the subject wants to select a symbol, they await the intended symbol during the presentation and elicit a p300 response to a target symbol.

الاقتباس:

 Orhan, U., Hild, K. E., 2nd, Erdogmus, D., Roark, B., Oken, B., & Fried-Oken, M. (2012). RSVP Keyboard: An EEG Based Typing Interface. Proceedings of the ... IEEE International Conference on Acoustics, Speech, and Signal Processing. ICASSP (Conference), 10.1109/ICASSP.2012.6287966. https://doi.org/10.1109/ICASSP.2012.6287966

مصفوفة تهجئة

 Matrix Speller is an EEG (electroencephalography) based BCI (brain computer interface) typing system. It utilizes a visual presentation technique called Single Character Presentation (SCP). In matrix speller, the symbols are arranged in a matrix with fixed number of rows and columns. Using SCP, subsets of these symbols are intensified (i.e. highlighted) usually in pseudorandom order to produce an odd ball paradigm to induce p300 responses.

الاقتباس:

 Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: toward a mental prosthesis utilizing event-related brain potentials. Electroencephalography and clinical Neurophysiology, 70(6), 510-523.

Ahani A, Moghadamfalahi M, Erdogmus D. Language-Model Assisted And Icon-based Communication Through a Brain Computer Interface With Different Presentation Paradigms. IEEE Trans Neural Syst Rehabil Eng. 2018 Jul 25. doi: 10.1109/TNSRE.2018.2859432.

العرض التوضيحي

تحتوي جميع الوظائف والوحدات النمطية الرئيسية على ملفات تجريبية واختبار مرتبطة بها والتي قد يتم تشغيلها محليًا. هذا من شأنه أن يساعدك في توجيهك إلى الوظيفة وكذلك بمثابة وثائق. إذا أضفت إلى الريبو ، فيجب عليك إضافة اختبارات وإصلاح أي اختبار يفشل عند تغيير الرمز.

على سبيل المثال ، يمكنك تشغيل العرض التجريبي الرئيسي BCIPY بواسطة:

python demo/bci_main_demo.py

سيتم تحميل هذا العرض التوضيحي في المعلمات وتنفيذ مهمة تجريبية محددة في الملف. هناك ملفات تجريبية موجودة في معظم الوحدات ، باستثناء واجهة المستخدم الرسومية والإشارة والمعلمات. قم بتشغيلها كنص بيثون!

تحديد العوائد والتصحيح

يعد تحديد الإزاحة الثابتة والتصحيح خطوات حرجة قبل بدء التجربة. يستخدم BCIPY LSL لاكتساب بيانات EEG و Psychopy لتقديم المحفزات.

وثائق توقيت توقيت التزامن LSL

الإزاحة الثابتة هي الفرق في الوقت العادي بين إشاراتنا والمنبهات. يتم تحديد هذا الإزاحة من خلال الاختبار عبر ثنائيات ضوئية أو آلية تشغيل أخرى. يتم تصحيح الإزاحة عن طريق تحويل إشارة EEG بواسطة الإزاحة المحددة باستخدام معلمة static_offset .

بعد تشغيل مهمة التحقق من التوقيت (مثل ، rsvptimingverification) مع ثنائي ضوئي متصل بالشاشة وتوصيله بجهاز ، يمكن تحديد الإزاحة عن طريق تحليل البيانات. استخدم وحدة offset للتوصية بقيمة تصحيح الإزاحة وعرض النتائج.

لتشغيل تحديد الإزاحة وطباعة النتائج ، استخدم الأمر التالي:

python bcipy/helpers/offset.py -r

بعد تشغيل الأمر أعلاه ، سيتم عرض قيمة تصحيح الإزاحة الموصى بها في المحطة ويمكن تمريرها لتحديد استقرار النظام وعرض النتائج.

 # Let's say the recommneded offset value is 0.1
python bcipy/helpers/offset.py --offset " 0.1 " -p

بالتناوب ، إذا تم تثبيت Make ، فيمكنك تشغيل الأمر المتابعة لتشغيل تحديد الإزاحة وعرض النتائج:

make offset-recommend

الاختبار

عند كتابة الاختبارات ، ضعها في الوحدة النمطية الصحيحة ، في مجلد الاختبارات ، وادخل الملف واختبار نفسه باستخدام test_ حتى يكتشفه Pytest. انظر اختبارات الوحدة الأخرى للأمثلة!

يجب تثبيت متطلبات التطوير قبل التشغيل: pip install -r dev_requirements.txt

لتشغيل جميع الاختبارات ، في سطر الأوامر:

 py . test

لتشغيل اختبارات وحدات واحدة (على سبيل المثال ، الاستحواذ) ، في سطر الأوامر:

 py . test acquisition

لإنشاء مقاييس تغطية الاختبار ، في سطر الأوامر:

coverage run --branch --source=bcipy -m pytest --mpl -k " not slow "

# Generate a command line report
coverage report

# Generate html doc in the bci folder. Navigate to index.html and click.
coverage html

بالتناوب ، إذا تم تثبيت Make ، فيمكنك تشغيل الأمر المتابعة لتشغيل التغطية/pytest وإنشاء HTML:

make coverage-html

linting

يفرض هذا المشروع إرشادات نمط PEP باستخدام FLAKE8.

لتجنب قضاء الوقت غير الضروري في التنسيق ، نوصي باستخدام autopep8 . يمكنك تحديد ملف أو دليل إلى تنسيق تلقائي. عندما تكون جاهزًا لدفع الكود الخاص بك ، يمكنك تشغيل الأوامر التالية لتنسيق الكود الخاص بك:

 # autoformat all files in bcipy
autopep8 --in-place --aggressive -r bcipy

# autoformat only the processor file
autopep8 --in-place --aggressive bcipy/acquisition/processor.py

أخيرًا ، قم بتشغيل فحص الوبر: flake8 bcipy .

بالتناوب ، إذا تم تثبيت Make ، فيمكنك تشغيل الأمر المتابعة لتشغيل Autopep8 و Flake8:

make lint

اكتب فحص

يفرض هذا المشروع فحص نوع mypy . تم العثور على تكوين مشروع الكتابة في ملف mypy.ini. لتشغيل الفحص ، قم بتشغيل الأمر التالي:

mypy bcipy

لإنشاء تقرير ، قم بتشغيل الأمر التالي:

mypy --html-report bcipy

بالتناوب ، إذا تم تثبيت Make ، فيمكنك تشغيل الأمر المتابعة لتشغيل mypy:

make type

الترحيب بالمساهمات!

إذا كنت ترغب في إضافتك إلى فريق التطوير Slack أو لديك أسئلة إضافية ، فيرجى التواصل معنا على [email protected]!

إرشادات المساهمة

نحن نتبع وسننفذ عهد المساهم لتعزيز بيئة آمنة وشاملة لهذا البرنامج المفتوح المصدر ، يرجى الرجوع إلى هذا الرابط لمزيد من المعلومات: https://www.contributor-cavenant.org/

إرشادات أخرى:

جميع الوحدات تتطلب اختبارات وتوضيح.
يجب أن تمر جميع الاختبارات لدمج ، حتى لو كانت لا علاقة لها على ما يبدو بعملك.
استخدم المساحات ، وليس علامات التبويب.
استخدم أسماء مفيدة للوظائف والفئات.
قم بتوثيق إدخال وإخراج وظائفك / الفئات في الكود. على سبيل المثال التعليق والكتابة.
لا تدفع IDE أو ملفات التكوين المحلية الأخرى.
يجب توثيق جميع الوحدات الجديدة أو الوظائف الرئيسية خارج الكود باستخدام readMe.md. انظر readme.md في repo أو انتقل إلى هذا الموقع للحصول على الإلهام: https://github.com/matiassingers/awesome-readme. استخدم دائمًا مترجمًا مائلًا قبل الدفع.

انظر هذا المورد للحصول على أمثلة: http://docs.python-guide.org/en/latest/writing/style/