py-neuromodulation 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

py_neuromodulation/__init__.py

@@ -1,13 +1,74 @@
-from . import (
-    nm_analysis,
-    nm_stream_abc,
-    nm_cohortwrapper,
-    nm_across_patient_decoding,
-    nm_stream_offline,
-    nm_settings,
-    nm_define_nmchannels,
-)
-from .nm_stream_offline import Stream
-from .nm_run_analysis import DataProcessor
-
-__version__ = "0.1.0.dev1"
+import os
+import platform
+from pathlib import PurePath
+from importlib.metadata import version
+from .nm_logger import NMLogger
+
+#####################################
+# Globals and environment variables #
+#####################################
+
+__version__ = version(__package__)  # get version from pyproject.toml
+
+# Check if the module is running headless (no display) for tests and doc builds
+PYNM_HEADLESS: bool = not os.environ.get("DISPLAY")
+PYNM_DIR = PurePath(__file__).parent  # Define constant for py_nm directory
+
+os.environ["MPLBACKEND"] = "agg" if PYNM_HEADLESS else "qtagg"  # Set matplotlib backend
+
+# Set  environment variable MNE_LSL_LIB (required to import Stream below)
+LSL_DICT = {
+    "windows_32bit": "windows/x86/liblsl.1.16.2.dll",
+    "windows_64bit": "windows/amd64/liblsl.1.16.2.dll",
+    "darwin_i386": "macos/amd64/liblsl.1.16.2.dylib",
+    "darwin_arm": "macos/arm64/liblsl.1.16.0.dylib",
+    "linux_jammy_32bit": "linux/jammy_x86/liblsl.1.16.2.so",
+    "linux_jammy_64bit": "linux/jammy_amd64/liblsl.1.16.2.so",
+    "linux_focal_64bit": "linux/focal_amd64/liblsl.1.16.2.so",
+    "linux_bionic_64bit": "linux/bionic_amd64/liblsl.1.16.2.so",
+    "linux_bookworm_64bit": "linux/bookworm_amd64/liblsl.1.16.2.so",
+    "linux_noble_64bit": "linux/noble_amd64/liblsl.1.16.2.so",
+    "linux_32bit": "linux/jammy_x86/liblsl.1.16.2.so",
+    "linux_64bit": "linux/jammy_amd64/liblsl.1.16.2.so",
+}
+
+PLATFORM = platform.system().lower().strip()
+ARCH = platform.architecture()[0]
+match PLATFORM:
+    case "windows":
+        KEY = PLATFORM + "_" + ARCH
+    case "darwin":
+        KEY = PLATFORM + "_" + platform.processor()
+    case "linux":
+        DIST = platform.freedesktop_os_release()["VERSION_CODENAME"]
+        KEY = PLATFORM + "_" + DIST + "_" + ARCH
+        if KEY not in LSL_DICT:
+            KEY = PLATFORM + "_" + ARCH
+    case _:
+        KEY = ""
+
+if KEY in LSL_DICT:
+    os.environ["MNE_LSL_LIB"] = str(PYNM_DIR / "liblsl" / LSL_DICT[KEY])
+
+
+# Create global dictionary to store user-defined features
+user_features = {}
+
+
+######################################
+# Logger initialization and settings #
+######################################
+
+logger = NMLogger(__name__)  # logger initialization first to prevent circular import
+
+####################################
+# API: Exposed classes and methods #
+####################################
+from .nm_stream import Stream as Stream
+from .nm_run_analysis import DataProcessor as DataProcessor
+from .nm_settings import NMSettings as NMSettings
+from .nm_features import (
+    add_custom_feature as add_custom_feature,
+    remove_custom_feature as remove_custom_feature,
+    NMFeature as NMFeature,
+)

py_neuromodulation/_write_example_dataset_helper.py

@@ -1,65 +1,83 @@
-import mne
-import mne_bids
-import pybv  # pip install pybv
-import os
-
-
-def set_chtypes(vhdr_raw):
-    """
-    define MNE RawArray channel types
-    """
-    print('Setting new channel types...')
-    remapping_dict = {}
-    for ch_name in vhdr_raw.info['ch_names']:
-        if ch_name.startswith('ECOG'):
-            remapping_dict[ch_name] = 'ecog'
-        elif ch_name.startswith(('LFP', 'STN')):
-            remapping_dict[ch_name] = 'dbs'
-        elif ch_name.startswith('EMG'):
-            remapping_dict[ch_name] = 'emg'
-        elif ch_name.startswith('EEG'):
-            remapping_dict[ch_name] = 'misc'
-        elif ch_name.startswith(('MOV', 'ANALOG', 'ROT', 'ACC', 'AUX', 'X', 'Y', 'Z')):
-            remapping_dict[ch_name] = 'misc'
-        else:
-            remapping_dict[ch_name] = 'misc'
-    vhdr_raw.set_channel_types(remapping_dict, verbose=False)
-    return vhdr_raw
-
-
-def write_bids_example():
-    # define run file to read and write from
-    PATH_RUN = r"C:\code\py_neuromodulation\examples\data\sub-000\ses-right\ieeg\sub-000_ses-right_task-force_run-3_ieeg.vhdr"
-    PATH_BIDS = r"C:\code\py_neuromodulation\examples\data"
-    PATH_OUT = r"C:\Users\ICN_admin\Downloads\BIDS_EXAMPLE"
-    PATH_OUT_TEMP = r"C:\Users\ICN_admin\Downloads\BIDS_EXAMPLE_TEMP"
-
-    entities = mne_bids.get_entities_from_fname(PATH_RUN)
-
-    bids_path = mne_bids.BIDSPath(subject=entities["subject"], session=entities["session"], task=entities["task"],
-                                  run=entities["run"], acquisition=entities["acquisition"], datatype="ieeg",
-                                  root=PATH_BIDS)
-
-    raw_arr = mne_bids.read_raw_bids(bids_path)
-
-    # crop data
-    raw_arr.crop(0, 19)  # pick three movements
-
-    data = raw_arr.get_data()[:10, :]
-    ch_names = raw_arr.ch_names[:10]
-
-
-    pybv.write_brainvision(data=data, sfreq=raw_arr.info["sfreq"], ch_names=ch_names,
-                           fname_base="example", folder_out=PATH_OUT_TEMP)
-
-    data_to_write = mne.io.read_raw_brainvision(os.path.join(PATH_OUT_TEMP, "example.vhdr"))
-
-    # example.eeg / .vhdr need to be deleted afterwards
-
-    data_to_write = set_chtypes(data_to_write)
-    data_to_write.info["line_freq"] = 60
-
-    mne_bids.write_raw_bids(data_to_write, mne_bids.BIDSPath(subject="testsub", session="EphysMedOff",
-                            task="gripforce", datatype="ieeg", run="0",
-                            root=PATH_OUT),
-                            overwrite=True)
+import mne
+import mne_bids
+import pybv  # pip install pybv
+from pathlib import PurePath
+
+
+def set_chtypes(vhdr_raw):
+    """
+    define MNE RawArray channel types
+    """
+    print("Setting new channel types...")
+    remapping_dict = {}
+    for ch_name in vhdr_raw.info["ch_names"]:
+        if ch_name.startswith("ECOG"):
+            remapping_dict[ch_name] = "ecog"
+        elif ch_name.startswith(("LFP", "STN")):
+            remapping_dict[ch_name] = "dbs"
+        elif ch_name.startswith("EMG"):
+            remapping_dict[ch_name] = "emg"
+        elif ch_name.startswith("EEG"):
+            remapping_dict[ch_name] = "misc"
+        elif ch_name.startswith(("MOV", "ANALOG", "ROT", "ACC", "AUX", "X", "Y", "Z")):
+            remapping_dict[ch_name] = "misc"
+        else:
+            remapping_dict[ch_name] = "misc"
+    vhdr_raw.set_channel_types(remapping_dict, verbose=False)
+    return vhdr_raw
+
+
+def write_bids_example():
+    # define run file to read and write from
+    PATH_RUN = r"C:\code\py_neuromodulation\examples\data\sub-000\ses-right\ieeg\sub-000_ses-right_task-force_run-3_ieeg.vhdr"
+    PATH_BIDS = r"C:\code\py_neuromodulation\examples\data"
+    PATH_OUT = r"C:\Users\ICN_admin\Downloads\BIDS_EXAMPLE"
+    PATH_OUT_TEMP = r"C:\Users\ICN_admin\Downloads\BIDS_EXAMPLE_TEMP"
+
+    entities = mne_bids.get_entities_from_fname(PATH_RUN)
+
+    bids_path = mne_bids.BIDSPath(
+        subject=entities["subject"],
+        session=entities["session"],
+        task=entities["task"],
+        run=entities["run"],
+        acquisition=entities["acquisition"],
+        datatype="ieeg",
+        root=PATH_BIDS,
+    )
+
+    raw_arr = mne_bids.read_raw_bids(bids_path)
+
+    # crop data
+    raw_arr.crop(0, 19)  # pick three movements
+
+    data = raw_arr.get_data()[:10, :]
+    ch_names = raw_arr.ch_names[:10]
+
+    pybv.write_brainvision(
+        data=data,
+        sfreq=raw_arr.info["sfreq"],
+        ch_names=ch_names,
+        fname_base="example",
+        folder_out=PATH_OUT_TEMP,
+    )
+
+    data_to_write = mne.io.read_raw_brainvision(PurePath(PATH_OUT_TEMP, "example.vhdr"))
+
+    # example.eeg / .vhdr need to be deleted afterwards
+
+    data_to_write = set_chtypes(data_to_write)
+    data_to_write.info["line_freq"] = 60
+
+    mne_bids.write_raw_bids(
+        data_to_write,
+        mne_bids.BIDSPath(
+            subject="testsub",
+            session="EphysMedOff",
+            task="gripforce",
+            datatype="ieeg",
+            run="0",
+            root=PATH_OUT,
+        ),
+        overwrite=True,
+    )

py_neuromodulation/data/README

@@ -0,0 +1,6 @@
+References
+----------
+Appelhoff, S., Sanderson, M., Brooks, T., Vliet, M., Quentin, R., Holdgraf, C., Chaumon, M., Mikulan, E., Tavabi, K., Höchenberger, R., Welke, D., Brunner, C., Rockhill, A., Larson, E., Gramfort, A. and Jas, M. (2019). MNE-BIDS: Organizing electrophysiological data into the BIDS format and facilitating their analysis. Journal of Open Source Software 4: (1896). https://doi.org/10.21105/joss.01896
+
+Holdgraf, C., Appelhoff, S., Bickel, S., Bouchard, K., D'Ambrosio, S., David, O., … Hermes, D. (2019). iEEG-BIDS, extending the Brain Imaging Data Structure specification to human intracranial electrophysiology. Scientific Data, 6, 102. https://doi.org/10.1038/s41597-019-0105-7
+

py_neuromodulation/data/dataset_description.json

@@ -0,0 +1,8 @@
+{
+    "Name": " ",
+    "BIDSVersion": "1.7.0",
+    "DatasetType": "raw",
+    "Authors": [
+        "[Unspecified]"
+    ]
+}

py_neuromodulation/data/participants.json

@@ -0,0 +1,32 @@
+{
+    "participant_id": {
+        "Description": "Unique participant identifier"
+    },
+    "age": {
+        "Description": "Age of the participant at time of testing",
+        "Units": "years"
+    },
+    "sex": {
+        "Description": "Biological sex of the participant",
+        "Levels": {
+            "F": "female",
+            "M": "male"
+        }
+    },
+    "hand": {
+        "Description": "Handedness of the participant",
+        "Levels": {
+            "R": "right",
+            "L": "left",
+            "A": "ambidextrous"
+        }
+    },
+    "weight": {
+        "Description": "Body weight of the participant",
+        "Units": "kg"
+    },
+    "height": {
+        "Description": "Body height of the participant",
+        "Units": "m"
+    }
+}

py_neuromodulation/data/participants.tsv

@@ -0,0 +1,2 @@
+participant_id	age	sex	hand	weight	height
+sub-testsub	n/a	n/a	n/a	n/a	n/a

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_space-mni_coordsystem.json

@@ -0,0 +1,5 @@
+{
+    "iEEGCoordinateSystem": "Other",
+    "iEEGCoordinateSystemDescription": "n/a",
+    "iEEGCoordinateUnits": "m"
+}

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_space-mni_electrodes.tsv

@@ -0,0 +1,11 @@
+name	x	y	z	size	impedance
+LFP_RIGHT_0	0.0118280802308701	-0.0151597482742092	-0.00776909845640809	n/a	n/a
+LFP_RIGHT_1	0.0123908351968705	-0.0142925082817827	-0.0059367986990887	n/a	n/a
+LFP_RIGHT_2	0.012930849148285701	-0.0134128499400548	-0.00409165661961333	n/a	n/a
+ECOG_RIGHT_0	0.037318173999999996	-0.048610126639999994	0.06179765474	n/a	n/a
+ECOG_RIGHT_1	0.0401598943	-0.037315929830000004	0.06431171618	n/a	n/a
+ECOG_RIGHT_2	0.040943035780000005	-0.02721778456	0.06409518407999999	n/a	n/a
+ECOG_RIGHT_3	0.03978395522	-0.01700523081	0.06386618136	n/a	n/a
+ECOG_RIGHT_4	0.03968813641	-0.005528024572	0.06168254254	n/a	n/a
+ECOG_RIGHT_5	0.03751915924	0.004304913414	0.060541263549999995	n/a	n/a
+MOV_RIGHT	n/a	n/a	n/a	n/a	n/a

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_task-gripforce_run-0_channels.tsv

@@ -0,0 +1,11 @@
+name	type	units	low_cutoff	high_cutoff	description	sampling_frequency	status	status_description
+LFP_RIGHT_0	DBS	µV	0.0	500.0	Deep Brain Stimulation	1000.0	good	n/a
+LFP_RIGHT_1	DBS	µV	0.0	500.0	Deep Brain Stimulation	1000.0	good	n/a
+LFP_RIGHT_2	DBS	µV	0.0	500.0	Deep Brain Stimulation	1000.0	good	n/a
+ECOG_RIGHT_0	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+ECOG_RIGHT_1	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+ECOG_RIGHT_2	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+ECOG_RIGHT_3	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+ECOG_RIGHT_4	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+ECOG_RIGHT_5	ECOG	µV	0.0	500.0	Electrocorticography	1000.0	good	n/a
+MOV_RIGHT	MISC	µV	0.0	500.0	Miscellaneous	1000.0	good	n/a

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.json

@@ -0,0 +1,18 @@
+{
+    "TaskName": "gripforce",
+    "Manufacturer": "Brain Products",
+    "PowerLineFrequency": 60.0,
+    "SamplingFrequency": 1000.0,
+    "SoftwareFilters": "n/a",
+    "RecordingDuration": 19.0,
+    "RecordingType": "continuous",
+    "iEEGReference": "n/a",
+    "ECOGChannelCount": 6,
+    "SEEGChannelCount": 3,
+    "EEGChannelCount": 0,
+    "EOGChannelCount": 0,
+    "ECGChannelCount": 0,
+    "EMGChannelCount": 0,
+    "MiscChannelCount": 1,
+    "TriggerChannelCount": 0
+}

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.vhdr

@@ -0,0 +1,35 @@
+Brain Vision Data Exchange Header File Version 1.0
+; Written using pybv 0.7.5
+
+[Common Infos]
+Codepage=UTF-8
+DataFile=sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.eeg
+MarkerFile=sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.vmrk
+DataFormat=BINARY
+; Data orientation: MULTIPLEXED=ch1,pt1, ch2,pt1 ...
+DataOrientation=MULTIPLEXED
+NumberOfChannels=10
+; Sampling interval in microseconds
+SamplingInterval=1000.0
+
+[Binary Infos]
+BinaryFormat=IEEE_FLOAT_32
+
+[Channel Infos]
+; Each entry: Ch<Channel number>=<Name>,<Reference channel name>,
+; <Resolution in "Unit">,<Unit>, Future extensions..
+; Fields are delimited by commas, some fields might be omitted (empty).
+; Commas in channel names are coded as "\1".
+Ch1=LFP_RIGHT_0,,0.1,µV
+Ch2=LFP_RIGHT_1,,0.1,µV
+Ch3=LFP_RIGHT_2,,0.1,µV
+Ch4=ECOG_RIGHT_0,,0.1,µV
+Ch5=ECOG_RIGHT_1,,0.1,µV
+Ch6=ECOG_RIGHT_2,,0.1,µV
+Ch7=ECOG_RIGHT_3,,0.1,µV
+Ch8=ECOG_RIGHT_4,,0.1,µV
+Ch9=ECOG_RIGHT_5,,0.1,µV
+Ch10=MOV_RIGHT,,0.1,µV
+
+[Comment]
+

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/ieeg/sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.vmrk

@@ -0,0 +1,13 @@
+Brain Vision Data Exchange Marker File, Version 1.0
+; Exported using pybv 0.7.5
+
+[Common Infos]
+Codepage=UTF-8
+DataFile=sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.eeg
+
+[Marker Infos]
+; Each entry: Mk<Marker number>=<Type>,<Description>,<Position in data points>,
+;             <Size in data points>, <Channel number (0 = marker is related to all channels)>
+;             <Date (YYYYMMDDhhmmssuuuuuu)>
+; Fields are delimited by commas, some fields might be omitted (empty).
+; Commas in type or description text are coded as "\1".

py_neuromodulation/data/sub-testsub/ses-EphysMedOff/sub-testsub_ses-EphysMedOff_scans.tsv

@@ -0,0 +1,2 @@
+filename	acq_time
+ieeg/sub-testsub_ses-EphysMedOff_task-gripforce_run-0_ieeg.vhdr	n/a

py_neuromodulation/grid_cortex.tsv

@@ -0,0 +1,40 @@
+x	y	z
+-13.1	-67.7	69.1
+-35.5	-60.0	66.0
+-48.3	-55.1	58.2
+-60.0	-51.8	48.0
+-16.9	-51.6	78.0
+-34.8	-49.3	71.7
+-67.5	-47.1	31.0
+-46.1	-43.7	61.1
+-59.8	-39.6	53.3
+-14.2	-39.1	81.1
+-28.3	-31.2	76.0
+-42.3	-30.7	70.2
+-67.6	-30.1	41.2
+-50.5	-24.4	64.4
+-14.6	-22.7	80.2
+-60.9	-18.7	50.9
+-31.6	-16.9	75.2
+-5.1	-12.6	77.3
+-65.6	-10.8	37.8
+-41.8	-10.2	67.0
+-55.1	-4.01	53.2
+-22.7	1.2	72.0
+-5.8	2.8	74.8
+-49.2	3.7	54.7
+-34.5	3.9	66.5
+-61.55	6.2	35.9
+-63.6	8.3	25.7
+-40.4	11.8	60.7
+-48.7	14.5	50.5
+-21.8	16.0	68.9
+-58.2	18.2	27.3
+-7.0	18.4	70.3
+-36.3	19.9	59.6
+-48.1	24.6	44.0
+-56.8	28.52	20.8
+-7.3	33.8	61.7
+-22.2	35.0	57.2
+-36.8	35.4	47.0
+-46.8	35.6	36.0