Unduh BciPy - Unduh Kode Sumber BciPy

BciPy

Kode Sumber AI

2.0.0rc4

Unduh

BCIPY: Perangkat Lunak Antarmuka Komputer Otak di Python

BCIPY adalah perpustakaan untuk melakukan eksperimen antarmuka komputer otak di Python. Ini berfungsi sebagai aplikasi mandiri untuk pengumpulan data eksperimental atau Anda dapat mengambil alat yang Anda butuhkan dan mulai mengkode sistem Anda sendiri. Lihat dokumentasi BCIPY resmi kami termasuk afiliasi dan lebih banyak informasi konteks di sini.

Ini akan berjalan pada Windows terbaru (7, 10, 11), Linux (Ubuntu 22.04) dan MacOS (Big Sur). Versi lain mungkin berfungsi juga, tetapi tidak dijamin. Untuk melihat versi yang didukung dan sistem operasi pada rilis ini lihat di sini: BCIPY Builds.

Tolong kutip kami saat menggunakan!

 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.

Dependensi

Proyek ini membutuhkan Python 3.8 atau 3.9. Silakan lihat catatan di bawah ini untuk dependensi spesifik OS tambahan sebelum instalasi dapat diselesaikan dan referensi dokumentasi/FAQ kami untuk informasi lebih lanjut: https://bcipy.github.io/hardware-os-config/

Linux

Anda perlu menginstal prasyarat yang ditentukan dalam scriptsshelllinux_requirements.sh serta pip install attrdict3 .

Windows

Jika Anda menggunakan mesin Windows, Anda harus menginstal alat build Microsoft Visual C ++.

Python 3.9 saja! Anda perlu menginstal pywinhook secara manual. Lihat di sini untuk file roda yang sesuai ( pyWinhook‑1.6.2‑cp39‑cp39‑win_amd64.whl ). Kemudian jalankan pip install <path_to_wheel_file> . Kami juga menyertakan file roda 64-bit di .bcipy/downloads/ direktori.

Mac

Jika Anda menggunakan Mac, Anda harus menginstal XCODE dan mengaktifkan alat baris perintah. xcode-select --install . Jika menggunakan chip M1/2, Anda harus menggunakan skrip instal dalam scripts/shell/m2chip_install.sh untuk menginstal prasyarat. Anda mungkin juga perlu menggunakan terminal Rosetta untuk menjalankan skrip instalasi, tetapi ini belum diperlukan dalam pengujian kami menggunakan chip M2.

Jika menggunakan ZSH, alih -alih bash, Anda dapat menemukan kesalahan segementasi saat menjalankan BCIPY. Ini karena masalah dalam ketergantungan psikopy tanpa perbaikan yang diketahui. Harap gunakan bash, bukan zsh untuk saat ini.

Instalasi

Pengaturan BCIPY

Untuk menjalankan BCIPY di komputer Anda, setelah mengikuti dependensi di atas, Anda harus menginstal paket BCIPY.

Untuk menginstal untuk digunakan secara lokal dan penggunaan GUI:

Git Clone https://github.com/bcipy/bcipy.git
Ubah direktori di terminal Anda ke direktori repo.
Instal Paket Model Bahasa Kenlm. pip install kenlm==0.1 --global-option="--max_order=12" .
Pasang psikopy tanpa dependensi. pip install psychopy==2023.2.1 --no-deps .
Instal BCIPY dalam mode pengembangan. pip install -e .

Jika menginginkan versi terbaru dari PYPI dan membangun menggunakan modul:

pip install bcipy

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk menginstal:

 # install in development mode
make dev-install

Penggunaan klien

Jalankan protokol atau tugas percobaan

Ajukan protokol percobaan atau tugas secara langsung menggunakan utilitas baris perintah bcipy .

Gunakan bendera bantuan untuk melihat opsi input lain yang tersedia: bcipy --help
- Anda dapat meneruskan atributnya dengan bendera, jika diinginkan.
  - Berjalan dengan ID pengguna dan tugas:
    - bcipy --user "bci_user" --task "RSVP Calibration"
  - Berlari dengan ID pengguna dan tugas dengan protokol terdaftar:
    - bcipy --user "bci_user" --experiment "default"
  - Berjalan dengan data palsu:
    - bcipy --fake
  - Berlari tanpa visualisasi:
    - bcipy --noviz
  - Berlari dengan peringatan setelah setiap eksekusi tugas:
    - bcipy --alert
  - Berlari dengan parameter khusus:
    - bcipy --parameters "path/to/valid/parameters.json"

Latih model sinyal dengan model BCIPY terdaftar

Untuk melatih model sinyal (saat ini PCARDAKDE ), jalankan perintah berikut setelah menginstal BCIPY:

bcipy-train

Gunakan bendera bantuan untuk melihat opsi input lain yang tersedia: bcipy-train --help
- Anda dapat meneruskan atributnya dengan bendera, jika diinginkan.
  - Berjalan tanpa jendela meminta folder sesi data:
    - bcipy-train -d path/to/data
  - Berjalan dengan visualisasi data (ERP, dll.):
    - bcipy-train -v
  - Berjalan dengan visualisasi data yang tidak ditampilkan, tetapi simpan ke file:
    - bcipy-train -s
  - Berlari dengan akurasi seimbang:
    - bcipy-train --balanced-acc
  - Berlari dengan peringatan setelah setiap eksekusi tugas:
    - bcipy-train --alert
  - Berlari dengan parameter khusus:
    - bcipy-train -p "path/to/valid/parameters.json"

Visualisasikan data ERP dari sesi dengan label target / non-target

Untuk menghasilkan plot yang dapat ditampilkan atau disimpan setelah pengumpulan data, jalankan perintah berikut setelah menginstal BCIPY:

bcipy-erp-viz

Gunakan bendera bantuan untuk melihat opsi input lain yang tersedia: bcipy-erp-viz --help
- Anda dapat meneruskan atributnya dengan bendera, jika diinginkan.
  - Berjalan tanpa jendela meminta folder sesi data:
    - bcipy-erp-viz -s path/to/data
  - Berjalan dengan visualisasi data (ERP, dll.):
    - bcipy-erp-viz --show
  - Berjalan dengan visualisasi data yang tidak ditampilkan, tetapi simpan ke file:
    - bcipy-erp-viz --save
  - Berjalan dengan parameter khusus (default ada di bcipy/parameter/parameter.json):
    - bcipy-erp-viz -p "path/to/valid/parameters.json"

Penggunaan simulator BCIPY

Simulator dapat dijalankan menggunakan utilitas baris perintah bcipy-sim .

Mantan. bcipy-sim -d my_data_folder/ -p my_parameters.json -m my_models/ -n 5

Jalankan bcipy-sim --help untuk dokumentasi atau lihat readme di modul simulator.

Penggunaan paket

 from bcipy . helpers import system_utils
system_utils . get_system_info ()

Penggunaan GUI

Jalankan perintah berikut di terminal Anda untuk memulai BCIPY GUI:

python bcipy/gui/BCInterface.py

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk memulai GUI dari direktori root BCIPY:

make bci-gui

Glosarium

Stimuli : Satu huruf, nada atau gambar yang ditampilkan (umumnya dalam penyelidikan). Singular = stimulus, jamak = rangsangan.

Percobaan : Kumpulan data setelah rangsangan ditampilkan. A----

PERTANYAAN : Himpunan rangsangan setelah salib fiksasi dalam tugas ejaan untuk mengumpulkan niat pengguna. A ---- B --- C ----

Seri : Setiap seri berisi setidaknya satu pertanyaan. Keputusan huruf/ikon dibuat setelah serangkaian tugas ejaan.

Sesi : Data dikumpulkan untuk suatu tugas. Terdiri dari metadata tentang tugas dan daftar seri.

Protokol : Kumpulan tugas dan tindakan yang akan dieksekusi dalam suatu sesi. Ini didefinisikan sebagai dalam percobaan dan dapat didaftarkan menggunakan BCIPY GUI.

Tugas : Desain eksperimental dengan rangsangan, uji coba, pertanyaan, dan seri untuk digunakan di BCI. Misalnya, "kalibrasi RSVP" adalah tugas.

Mode : Elemen desain umum antara jenis tugas. Misalnya, kalibrasi dan ejaan gratis adalah mode.

Paradigma : Paradigma tampilan dengan sifat dan mode unik. Mantan. Presentasi Visual Serial Rapid (RSVP), Matrix Speller, Steady-State Visual Evoked Potential (SSVEP).

Modul inti

Ini daftar modul utama dan fungsinya. Setiap modul akan berisi readme, demo, dan tesnya sendiri. Silakan periksa untuk informasi lebih lanjut!

acquisition : Mengakuisisi data, memberikan kembali deret waktu yang diinginkan, menyimpan untuk mengajukan di akhir sesi.
display : Menangani tampilan rangsangan di layar dan melewati waktu rangsangan kembali.
signal : Model sinyal EEG, model sinyal pandangan, filter, pemrosesan, evaluator dan pemirsa.
gui : Antarmuka pengguna akhir ke tugas BCI terdaftar dan pengeditan parameter. Lihat bcinterface.py.
helpers : Fungsi bermanfaat yang diperlukan untuk interaksi antara modul, I/O dasar, dan visualisasi data.
language : Memberikan probabilitas simbol berikutnya selama pengetikan.
parameters : Lokasi parameter JSON. Ini termasuk parameter.json (Konfigurasi Eksperimen / Aplikasi Utama) dan Device.json (Registry dan Konfigurasi Perangkat).
static : rangsangan gambar dan suara, manual misc, dan teks yang dapat dibaca untuk GUI.
task : BCIPY mengimplementasikan tugas pengguna. Koleksi utama modul BCI untuk digunakan selama berbagai eksperimen. Mantan. Kalibrasi RSVP.
feedback : Mekanisme umpan balik untuk rangsangan suara dan visual.
main : Pelaksana Eksperimen. Titik masuk utama ke dalam aplikasi
config : Parameter konfigurasi untuk aplikasi, termasuk jalur dan nama file data.
simulator : Memberikan dukungan untuk menjalankan simulasi berdasarkan data yang dikumpulkan sebelumnya.

Paradigma

Lihat bcipy/task/README.md untuk informasi lebih lanjut tentang semua paradigma, tugas, tindakan, dan mode yang didukung. Berikut ini adalah paradigma yang didukung dan divalidasi:

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.

Kutipan:

 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

 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.

Kutipan:

 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.

Demo

Semua fungsi dan modul utama memiliki demo dan menguji file yang terkait dengannya yang dapat dijalankan secara lokal. Ini akan membantu mengarahkan Anda ke fungsionalitas serta berfungsi sebagai dokumentasi. Jika Anda menambahkan ke repo, Anda harus menambahkan tes dan memperbaiki tes apa pun yang gagal saat Anda mengubah kode.

Misalnya, Anda dapat menjalankan demo BCIPY utama dengan:

python demo/bci_main_demo.py

Demo ini akan memuat dalam parameter dan menjalankan tugas demo yang ditentukan dalam file. Ada file demo yang terkandung di sebagian besar modul, kecuali GUI, sinyal dan parameter. Jalankan mereka sebagai skrip Python!

Penentuan dan koreksi offset

Penentuan dan koreksi offset statis adalah langkah penting sebelum memulai percobaan. BCIPY menggunakan LSL untuk memperoleh data EEG dan psikopy untuk menyajikan rangsangan.

Dokumentasi Sinkronisasi LSL Dokumentasi Waktu Psikopy

Offset statis adalah perbedaan waktu reguler antara sinyal dan rangsangan kami. Offset ini ditentukan melalui pengujian melalui fotodioda atau mekanisme pemicu lainnya. Koreksi offset dilakukan dengan menggeser sinyal EEG dengan offset yang ditentukan menggunakan parameter static_offset .

Setelah menjalankan tugas verifikasi waktu (seperti, RSVPTIMINGVERIFIKASI) dengan fotodiode yang terpasang pada tampilan dan terhubung ke perangkat, offset dapat ditentukan dengan menganalisis data. Gunakan modul offset untuk merekomendasikan nilai koreksi offset dan menampilkan hasilnya.

Untuk menjalankan penentuan offset dan mencetak hasilnya, gunakan perintah berikut:

python bcipy/helpers/offset.py -r

Setelah menjalankan perintah di atas, nilai koreksi offset yang disarankan akan ditampilkan di terminal dan dapat diteruskan untuk menentukan stabilitas sistem dan menampilkan hasilnya.

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

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk menjalankan penentuan offset dan menampilkan hasilnya:

make offset-recommend

Pengujian

Saat menulis tes, masukkan ke dalam modul yang benar, di folder tes, dan awalkan file dan uji dirinya dengan test_ agar pytest menemukannya. Lihat tes modul lainnya untuk contoh!

Persyaratan pengembangan harus diinstal sebelum menjalankan: pip install -r dev_requirements.txt

Untuk menjalankan semua tes, di baris perintah:

 py . test

Untuk menjalankan satu tes modul (mis. Akuisisi), di baris perintah:

 py . test acquisition

Untuk menghasilkan metrik cakupan uji, di baris perintah:

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

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk menjalankan cakupan/pytest dan menghasilkan html:

make coverage-html

Berbaris

Proyek ini menegakkan pedoman gaya PEP menggunakan Flake8.

Untuk menghindari menghabiskan waktu yang tidak perlu untuk pemformatan, kami sarankan menggunakan autopep8 . Anda dapat menentukan file atau direktori ke format otomatis. Saat siap untuk mendorong kode Anda, Anda dapat menjalankan perintah berikut untuk memformat kode Anda:

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

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

Akhirnya, jalankan Lint Check: flake8 bcipy .

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk menjalankan autopep8 dan flake8:

make lint

Ketik Pemeriksaan

Proyek ini menegakkan mypy type checking. Konfigurasi proyek pengetikan ditemukan di file mypy.ini. Untuk menjalankan pemeriksaan tipe, jalankan perintah berikut:

mypy bcipy

Untuk menghasilkan laporan, jalankan perintah berikut:

mypy --html-report bcipy

Bergantian, jika Make diinstal, Anda dapat menjalankan perintah ikuti untuk menjalankan mypy:

make type

Kontribusi Selamat Datang!

Jika Anda ingin ditambahkan ke tim pengembangan Slack atau memiliki pertanyaan tambahan, hubungi kami di [email protected]!

Pedoman Kontribusi

Kami mengikuti dan akan menegakkan perjanjian kontributor untuk menumbuhkan lingkungan yang aman dan inklusif untuk perangkat lunak open source ini, silakan merujuk tautan ini untuk informasi lebih lanjut: https://www.contributor-covenant.org/

Pedoman Lainnya:

Semua modul membutuhkan tes dan demo.
Semua tes harus lulus untuk bergabung, bahkan jika mereka tampaknya tidak terkait dengan pekerjaan Anda.
Gunakan spasi, bukan tab.
Gunakan nama informatif untuk fungsi dan kelas.
Dokumentasikan input dan output fungsi / kelas Anda dalam kode. misalnya berkomentar dan mengetik in-line.
Jangan mendorong IDE atau file konfigurasi lokal lainnya.
Semua modul baru atau fungsi utama harus didokumentasikan di luar kode dengan readme.md. Lihat readme.md di repo atau kunjungi situs ini untuk inspirasi: https://github.com/matiassingers/awesome-readme. Selalu gunakan penerjemah penurunan harga sebelum mendorong.

Lihat sumber ini untuk contoh: http://docs.python-guide.org/en/latest/writing/style/