MultiTaskBattery 1.3.0__py3-none-any.whl

MultiTaskBattery/task_table.tsv

@@ -0,0 +1,23 @@
+name	task_class	descriptive_name	code
+rest	Rest	rest	rest
+motor_localizer	MotorLocalizer	motor localizer	motloc
+toe_movement	FlexionExtension	toe	flexexten
+finger_sequence	FingerSequence	finger_sequence	fingseq
+serial_reaction_time	SerialReactionTime	serial_reaction_time	srt
+tongue_movement	TongueMovement	tongue	tongue
+finger_rhythmic	FingerRhythmic	finger_rhythmic	fingrhytm
+time_perception	TimePerception	time_perception	timeperc
+visual_search	VisualSearch	search	visrchsml
+action_observation	ActionObservation	knot	actobserv
+n_back	NBack	memory	nbko
+demand_grid	DemandGrid	grid	dmgrd
+oddball	OddBall	oddball	odbal
+passage_listening	PassageListening	listen	pssglisten
+reading	Reading	read	read
+semantic_prediction	SemanticPrediction	complete	sempred
+verb_generation	VerbGeneration	verb	vrbgen
+movie	Movie	movie	mov
+auditory_narrative	AuditoryNarrative	radio	audnarr
+spatial_navigation	SpatialNavigation	imagine	spatialnav
+affective	Affective	affective	affect
+theory_of_mind	TheoryOfMind	story	tom

MultiTaskBattery/ttl_clock.py

@@ -0,0 +1,73 @@
+# Created 2023: Bassel Arafat, Jorn Diedrichsen, Ince Husain
+from psychopy import core, event
+
+class TTLClock:
+
+    def __init__(self):
+        """
+        TTLClock class is used for counting the number of TTL pulses and the time of the last TTL pulse
+        """
+        self.clock      = core.Clock() #
+        self.ttl_count      = 0    # the number of ttl pulses
+        self.ttl_time       = 0    # time stamp of the last incoming ttl pulse
+        self.ttl_button = 't'  # the button used for simulating a ttl pulse
+
+    def reset(self, start_time=0):
+        """ resets the clock and ttl-counter
+        Args:
+            start_time (float):
+                the time in seconds to start the clock from
+        """
+        self.clock.reset(start_time)
+        self.ttl_count = 0
+        self.ttl_time = 0
+
+    def wait_for_first_ttl(self, wait = True):
+        """ This function waits for the first TTL and then resets the clock appropriately
+        Args:
+            wait (bool):
+                if True, the function will wait for the first TTL
+        """
+        if wait:
+            print('Waiting for first TTL...')
+            while self.ttl_count == 0:
+                self.update()
+        self.clock.reset()
+        self.ttl_time = 0
+
+    def wait_until(self,time):
+        """waits until the given time since the beginning of the run
+        Args:
+            time (float):
+                time in seconds
+        Returns:
+            real_time (float):
+                time that the real start occurs
+            start_ttl (int):
+                Number of TRs recorded since the beginning of the run
+            start_ttl_time (float):
+                Time since the last TR  """
+        while self.clock.getTime() < time:
+            self.update()
+        return self.clock.getTime(), self.ttl_count, self.clock.getTime()-self.ttl_time
+
+    def get_time(self):
+        """returns the current time of the clock
+        Returns:
+            time (float):
+                the current time of the clock
+        """
+        return self.clock.getTime()
+
+    def update(self):
+        """ updates the ttl count and time of the last ttl pulse
+        """
+        # get all the ttl pulses in the buffer (ttl_button is one key or a list of keys)
+        ttl_keys = [self.ttl_button] if isinstance(self.ttl_button, str) else list(self.ttl_button)
+        keys = event.getKeys(ttl_keys, timeStamped=self.clock)
+
+        # checks if the pressed key is the key used as the ttl pulse
+        for k in keys:
+            self.ttl_count += 1 # each time a ttl button is pressed, ttl count increases
+            self.ttl_time = k[1] # the time when the ttl button has been pressed
+            print(f"TR count: {self.ttl_count} -    TR time: {self.ttl_time} (key '{k[0]}')", end = "\r")

MultiTaskBattery/utils.py

@@ -0,0 +1,201 @@
+# Created 2023: Bassel Arafat, Jorn Diedrichsen, Ince Hussain
+import os
+from pathlib import Path
+import pandas as pd
+import MultiTaskBattery.task_blocks as tasks
+import MultiTaskBattery.task_file as task_files
+from MultiTaskBattery.fetch import CACHE_DIR
+
+# DEPRECATED: kept for backwards compatibility with external user scripts.
+# make_files.py no longer consults this list — instead it inspects each task's
+# make_task_file signature for a run_number parameter. To opt your task out of
+# receiving a run_number, simply omit it from the signature.
+tasks_without_run_number = ['n_back', 'verb_generation', 'rest', 'tongue_movement',
+                            'oddball', 'demand_grid', 'demand_grid_easy_diff','finger_sequence', 'finger_sequence_surprise', 'flexion_extension',
+                            'visual_search', 'serial_reaction_time', 'rest_surprise', 'rest_surprise_images', 'rest_surprise_sound_images','temp_deviant']
+
+def dircheck(path2dir):
+    """
+    Checks if a directory exists! if it does not exist, it creates it
+    Args:
+        dir_path (str, path)
+            path to the directory you want to be created
+    """
+    if not os.path.exists(path2dir):
+        print(f"creating {path2dir}")
+        os.makedirs(path2dir)
+
+def append_data_to_file(filename,data):
+    """ Appends a data frame to an (possibly) existing tsv file
+    Args:
+        filename (str):
+            path to the file
+        data (dataframe):
+            data to be appended to the file
+    """
+    if os.path.isfile(filename):
+        old_data = pd.read_csv(filename, sep = '\t')
+        data = pd.concat([old_data,data],axis = 0)
+    data.to_csv(filename, sep = '\t', index = False)
+
+def module_dirs(task_modules):
+    """Folders holding the task modules: a task library keeps its
+    task_table.tsv and stimuli/ next to its code."""
+    return [Path(m.__file__).resolve().parent for m in (task_modules or [])]
+
+def get_task_table(exp_dir=None, task_modules=None):
+    """ Reads the task_table.tsv files and concatenates them, avoiding duplicates.
+    Tables are read in order: next to each task module, then the experiment's,
+    then the package's; for a name in more than one table, the first one wins.
+    Args:
+        exp_dir (str, path, optional):
+            path to the experiment directory. If None, its table is not read.
+        task_modules (list, optional):
+            task modules (const.task_modules); a task_table.tsv next to a
+            module is read, e.g. from a task library outside the experiment.
+    Returns:
+        task_table (dataframe):
+            dataframe containing the task table
+    """
+    tables = [d / 'task_table.tsv' for d in module_dirs(task_modules)]
+    if exp_dir is not None:
+        tables.append(Path(exp_dir) / 'task_table.tsv')
+    tables.append(Path(__file__).parent / 'task_table.tsv')  # package table last, as fallback
+    task_table = pd.concat([pd.read_csv(t, sep='\t') for t in tables if os.path.isfile(t)], axis=0)
+    return task_table.drop_duplicates(subset='name').reset_index(drop=True)
+
+def get_task_class(const, class_name):
+    """ Searches for the task class in the list of task modules and returns it
+    Args:
+        const (constant object):
+            constant.py object containing the list of task modules to search for the task class
+        class_name (str):
+            name of the task class to be searched for   
+    Returns:        
+        TaskClass (class):
+            the task class that was searched for
+    """
+    # First tries to find the class in the custom list of task modules
+    if hasattr(const, 'task_modules'):
+        for module in const.task_modules:
+            if hasattr(module, class_name):
+                return getattr(module, class_name)
+    if hasattr(tasks, class_name):
+        return getattr(tasks, class_name)
+    else:
+        raise NameError(f"Task class {class_name} not found in any of the task modules, make sure to add the module to the list of task_modules in constants.py")
+
+def get_task_file_class(const, class_name):
+    """ Searches for the TaskFile class in the list of task modules and returns it.
+    Mirrors get_task_class but for the file-generation side. Custom TaskFile
+    classes follow a '<class>File' naming convention so they can coexist with
+    their matching Task class in the same module (e.g. SilentWord and
+    SilentWordFile in my_tasks.py).
+
+    Args:
+        const (constant object):
+            constants.py object containing the task_modules list
+        class_name (str):
+            base class name from task_table.tsv (e.g. 'SilentWord')
+    Returns:
+        TaskFileClass (class):
+            the TaskFile class that was searched for
+    """
+    # First tries '<class>File' in the custom list of task modules
+    if hasattr(const, 'task_modules'):
+        suffixed = class_name + 'File'
+        for module in const.task_modules:
+            if hasattr(module, suffixed):
+                return getattr(module, suffixed)
+    # Otherwise fall back to the framework's task_file module (bare class name)
+    if hasattr(task_files, class_name):
+        return getattr(task_files, class_name)
+    else:
+        raise NameError(f"TaskFile class {class_name} (or {class_name}File) not found in any task module, make sure to add the module to task_modules in constants.py")
+
+
+# --- Stimulus resolution -------------------------------------------------
+# Stimuli are resolved with the same local-first, package-fallback logic that
+# task *classes* use (see get_task_class / get_task_file_class): each root is
+# searched in order, and the package's own bundled stimuli are always appended
+# as a final fallback. This lets a custom task keep its stimuli in the
+# experiment folder while built-in tasks still resolve from the package.
+# The package's stimuli live at <repo_root>/stimuli, i.e. one level up from this
+# module's package directory. After those comes the stimulus cache that
+# `mtb fetch` downloads into (see fetch.py).
+_PACKAGE_STIM_DIR = Path(__file__).resolve().parents[1] / 'stimuli'
+
+
+def stim_roots(const):
+    """Return the ordered list of stimulus root directories to search.
+
+    Searches the ``stimuli`` folder next to each module in ``const.task_modules``
+    first, then ``const.stim_dirs`` (a list of roots) if it is defined, otherwise
+    the single ``const.stim_dir``. The package's bundled ``stimuli`` folder is
+    appended next, then the stimulus cache filled by ``mtb fetch``
+    (deduplicated), so built-in tasks still resolve.
+
+    Args:
+        const: the experiment constants module/object.
+    Returns:
+        list[Path]: roots to search, in priority order (local first, package last).
+    """
+    roots = [d / 'stimuli' for d in module_dirs(getattr(const, 'task_modules', None))]
+    roots += getattr(const, 'stim_dirs', None) or [getattr(const, 'stim_dir', _PACKAGE_STIM_DIR)]
+    roots.append(_PACKAGE_STIM_DIR)
+    roots.append(CACHE_DIR)
+    return list(dict.fromkeys(Path(r).resolve() for r in roots))
+
+
+def find_stim(const, task_name, *parts, must_exist=True):
+    """Resolve a single stimulus file for a task across the stimulus roots.
+
+    Searches ``<root>/<task_name>/<parts...>`` in each root (local first, package
+    last) and returns the first path that exists. Because the local roots are
+    searched first, appending the package fallback can never change a lookup that
+    already succeeds - it can only rescue one that would otherwise fail.
+
+    Args:
+        const: the experiment constants module/object.
+        task_name (str): task subfolder name (usually ``self.name``).
+        *parts (str): path components under the task folder - a filename, or e.g.
+            ``'clips', 'foo.mov'`` for a nested subfolder.
+        must_exist (bool): if True (default) raise ``FileNotFoundError`` when the
+            file is in none of the roots; if False, return the path under the
+            first root (useful when writing a file rather than reading one).
+    Returns:
+        Path: the resolved stimulus path.
+    """
+    roots = stim_roots(const)
+    for r in roots:
+        p = r.joinpath(task_name, *parts)
+        if p.exists():
+            return p
+    if must_exist:
+        sub = str(Path(*parts)) if parts else ''
+        raise FileNotFoundError(
+            f"Stimulus '{task_name}/{sub}' not found in any stimulus root: "
+            f"{[str(r) for r in roots]}. If it is a built-in task, run `mtb fetch {task_name}`.")
+    return roots[0].joinpath(task_name, *parts)
+
+
+def find_stim_dir(const, task_name):
+    """Resolve a task's stimulus *directory* across the stimulus roots.
+
+    Returns the first ``<root>/<task_name>`` that is an existing directory. Use
+    this for the cases that operate on the folder itself (e.g. globbing for a set
+    of files) rather than resolving one named file. If no root has the folder,
+    the path under the first root is returned so callers get a sensible location
+    for error messages.
+
+    Args:
+        const: the experiment constants module/object.
+        task_name (str): task subfolder name (usually ``self.name``).
+    Returns:
+        Path: the resolved task stimulus directory.
+    """
+    for r in stim_roots(const):
+        d = r / task_name
+        if d.is_dir():
+            return d
+    return stim_roots(const)[0] / task_name

multitaskbattery-1.3.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: MultiTaskBattery
+Version: 1.3.0
+Summary: A flexible Python toolbox for running multi-domain cognitive and motor tasks during fMRI sessions, built on PsychoPy.
+Author: Diedrichsenlab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/diedrichsenlab/MultiTaskBattery
+Project-URL: Documentation, https://multitaskbattery.readthedocs.io/
+Project-URL: Issues, https://github.com/diedrichsenlab/MultiTaskBattery/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psychopy==2026.2.5
+Requires-Dist: pandas
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy
+Requires-Dist: moviepy
+Requires-Dist: imageio
+Requires-Dist: ffmpeg-python
+Requires-Dist: sounddevice
+Requires-Dist: soundfile
+Requires-Dist: pyyaml
+Requires-Dist: questplus
+Requires-Dist: pooch
+Requires-Dist: numba
+Requires-Dist: nibabel
+Requires-Dist: psychopy-sounddevice
+Provides-Extra: docs
+Requires-Dist: numpy; extra == "docs"
+Requires-Dist: sphinx>=1.4; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: pandas; extra == "docs"
+Requires-Dist: matplotlib; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: scipy; extra == "docs"
+Requires-Dist: seaborn; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DiedrichsenLab/MultiTaskBattery/main/docs/assets/icon_MTB.png" alt="MTB Logo" width="200">
+</p>
+
+# Multi Task Battery (MTB)
+
+A flexible Python toolbox for running multi-domain cognitive and motor tasks during fMRI sessions — all within a single scanning run. Built on [PsychoPy](https://www.psychopy.org/)
+
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://multitaskbattery.readthedocs.io/)
+[![Interactive task map](https://img.shields.io/badge/explore-interactive%20task%20map-orange)](https://diedrichsenlab.github.io/MultiTaskBattery/mds/)
+
+
+This project runs multi-task batteries developed by the diedrichsenlab.
+#### Authors: Diedrichsenlab (Bassel Arafat, Caroline Nettekoven, Ince Husain, Ladan Shahshahani, Suzanne Witt, Maedbh King, Jorn Diedrichsen)
+
+
+## Documentation
+
+Full documentation is hosted at:  
+https://multitaskbattery.readthedocs.io/
+
+Covers:
+- Installation and setup
+- Task and run configuration
+- Optimal battery selection
+- Data output
+
+---
+
+## License
+
+MIT License © 2024 Joern Diedrichsen
+
+---
+
+## Contributing
+
+Open to issues and pull requests. If you use MTB in your research.
+
+---
+
+## Citation
+
+If you use the toolbox please cite the following reference:
+
+Arafat, B., Nettekoven, C., Xiang, J. D., & Diedrichsen, J. (2026). Multi-Task Batteries for Precision Functional Mapping. *eLife*, 15, RP111868. https://doi.org/10.7554/eLife.111868.1

multitaskbattery-1.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+MultiTaskBattery/__init__.py,sha256=7jB7NL8qDIauzVTg1zOzIiQSsE5TqfZ-zqqMZTrbpg0,149
+MultiTaskBattery/battery.py,sha256=4s4Q1DVA7UbRmezgZgOGRh735KgRTodNWUjmRXQbUJQ,8070
+MultiTaskBattery/experiment_block.py,sha256=4m8NolckTj0wpa1jIVcq57StjSLyLMu-EGPGaeTKv_M,15945
+MultiTaskBattery/fetch.py,sha256=Q-4TS9XOHOu-RHrhichkTC1ED90ZK8-aBmMhBbwrRfM,3021
+MultiTaskBattery/screen.py,sha256=Inf5XR_yJAw1NXBclZ_bwi7SESB04_JFMRlfslgvpDc,5760
+MultiTaskBattery/task_blocks.py,sha256=mQibCR2WqEWs8dVIZivcGyc3-oBm0RwKmnhXJ3t10lk,74441
+MultiTaskBattery/task_details.json,sha256=UxX2ZwrH8O6FmbDR-j5oD1pft16fWN0W_2rcAbfyVEE,59150
+MultiTaskBattery/task_file.py,sha256=gSRzX0VDjPlpB8JEWDsjXCIKieKDr-6EoZ5O7CkkAuc,77438
+MultiTaskBattery/task_table.tsv,sha256=HWyMpUkQinfYSXeBj2XWY-qcm1WQ5Y182FxhjdpN9dI,1024
+MultiTaskBattery/ttl_clock.py,sha256=j-gS9RTec8RvsszP1eqFp-7P20hSsKdx_tpZCdNqXWg,2787
+MultiTaskBattery/utils.py,sha256=SGmYP6OtRNYSm3SyspiGAT4hggKdYGN83cvD2v8amS8,9285
+multitaskbattery-1.3.0.dist-info/licenses/LICENSE,sha256=jJJvF_95za41k5Fhb5e1O4E8cRdmFcL4FT0G6-Ll8NY,1074
+multitaskbattery-1.3.0.dist-info/METADATA,sha256=TK6n7aykg3r6zohq1nDShqU9kQ_loHETJW0pXJW_rHA,3149
+multitaskbattery-1.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+multitaskbattery-1.3.0.dist-info/entry_points.txt,sha256=jNF1OcHTqnbjILkUMoP9kenlcThpsf71IfNAErfJU4M,52
+multitaskbattery-1.3.0.dist-info/top_level.txt,sha256=X9uviKkeqfHhUbRcbTsvr2bPR2HLhdLVX2HHFfoo8X4,17
+multitaskbattery-1.3.0.dist-info/RECORD,,

multitaskbattery-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

multitaskbattery-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mtb = MultiTaskBattery.fetch:main

multitaskbattery-1.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joern Diedrichsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

multitaskbattery-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+MultiTaskBattery