BIDSHandler

BIDSHandler is the central object for creating datasets, collecting events, and writing BIDS outputs.

Typical Lifecycle

1. Initialize with dataset entities (dataset, subject, task, optional session, acq, data_type).
2. Call createDataset(...) once.
3. Add events via addEvent(...).
4. Write files via writeEvents(...).
5. Optionally export environment/code metadata.

Practical Example

from psychopy_bids import bids

handler = bids.BIDSHandler(dataset="example_dataset", subject="01", task="stroop", runs=True)
handler.createDataset(force=True)

handler.addEvent(bids.BIDSTaskEvent(onset=0.0, duration=0.8, trial_type="instruction"))
handler.writeEvents(participant_info={"participant_id": "01", "age": 22})

Important Behaviors

• Entity values are normalized to BIDS-style labels (sub-, ses-, task-).
• runs=True creates auto-incremented run labels, runs=False omits run label.
• Missing values are written as "n/a" where applicable.

API Reference

A class to handle the creation of a BIDS-compliant dataset.

This class provides methods for creating and managing BIDS datasets and their modality agnostic files plus modality specific files.

Examples:

>>> from psychopy_bids import bids
>>> handler = bids.BIDSHandler(dataset="example_dataset")

Source code in psychopy_bids/bids/bidshandler.py

class BIDSHandler:
    """A class to handle the creation of a BIDS-compliant dataset.

    This class provides methods for creating and managing BIDS datasets and their modality agnostic
    files plus modality specific files.

    Examples
    --------
    >>> from psychopy_bids import bids
    >>> handler = bids.BIDSHandler(dataset="example_dataset")
    """

    def __init__(
        self,
        dataset: str,
        subject: Union[str, None] = None,
        task: Union[str, None] = None,
        session: Union[str, None] = None,
        data_type: str = "beh",
        acq: Union[str, None] = None,
        runs: Union[bool, str] = True,
        log_level: Union[str, int] = "INFO",
    ) -> None:
        """Initialize a BIDSHandler object.

        Parameters
        ----------
        dataset : str
            A set of neuroimaging and behavioral data acquired for a purpose of a particular study.
        subject : str, optional
            A person or animal participating in the study.
        task : str, optional
            A set of structured activities performed by the participant.
        session : str, optional
            A logical grouping of neuroimaging and behavioral data consistent across subjects.
        data_type : str, optional
            A functional group of different types of data.
        acq : str, optional
            Custom label to distinguish different conditions present during multiple runs of the
            same task.
        runs : bool or str, optional
            If True, an auto-incrementing run number is added to the filename.
            If False, no run entity is added.
            If a string, it is used directly as the run label (e.g. ``"4a"``).
        """
        self.dataset = dataset
        self.subject = subject
        self.task = task
        self.session = session
        self.data_type = data_type
        self.acq = acq
        self.runs = runs
        self.log_level = self._resolveLogLevel(log_level)
        self._logger = logging.getLogger("psychopy-bids")
        self.__events = []
        self._t_start = None  # BIDS onset reference time (set by BidsOnsetRoutine)

    @staticmethod
    def _resolveLogLevel(level: Union[str, int]) -> int:
        """Resolve string/int log level to a numeric value."""
        if isinstance(level, int):
            return level
        level_map = {
            "DEBUG": logging.DEBUG,
            "INFO": logging.INFO,
            "WARNING": logging.WARNING,
            "WARN": logging.WARNING,
            "ERROR": logging.ERROR,
            "CRITICAL": logging.CRITICAL,
        }
        return level_map.get(str(level).upper(), logging.INFO)

    def setLogLevel(self, level: Union[str, int]) -> None:
        """Set runtime log verbosity for psychopy-bids handler messages."""
        self.log_level = self._resolveLogLevel(level)

    def setOnsetReference(self, t: float) -> None:
        """Set the time reference for BIDS onset calculation.

        Call this once (e.g. on receiving the MRI scanner trigger) to establish
        the time-zero point.  All event onsets will be expressed relative to
        this time when the TSV file is written.

        Parameters
        ----------
        t : float
            The reference time in seconds (typically from ``globalClock``).

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example", subject="01", task="mytask")
        >>> handler._t_start is None
        True
        >>> handler.setOnsetReference(10.5)
        >>> handler._t_start
        10.5
        """
        self._t_start = float(t)

    def _log(self, level: Union[str, int], message: str) -> None:
        """Log message with psychopy-bids prefix using stdlib logging."""
        resolved_level = self._resolveLogLevel(level)
        if resolved_level < self.log_level:
            return

        level_label = {
            logging.DEBUG: "DEBUG",
            logging.INFO: "INFO",
            logging.WARNING: "WARN",
            logging.ERROR: "ERROR",
            logging.CRITICAL: "ERROR",
        }.get(resolved_level, "INFO")
        formatted = f"{level_label} [psychopy-bids(handler)] {message}"
        self._logger.log(resolved_level, formatted)

    @staticmethod
    def _logStatic(level: Union[str, int], message: str) -> None:
        """Log from static contexts with the same formatting as instance logs."""
        resolved_level = BIDSHandler._resolveLogLevel(level)
        level_label = {
            logging.DEBUG: "DEBUG",
            logging.INFO: "INFO",
            logging.WARNING: "WARN",
            logging.ERROR: "ERROR",
            logging.CRITICAL: "ERROR",
        }.get(resolved_level, "INFO")
        logging.getLogger("psychopy-bids").log(
            resolved_level,
            "%s [psychopy-bids(handler)] %s",
            level_label,
            message,
        )

    @property
    def dataset(self) -> str:
        """A set of neuroimaging and behavioral data acquired for a purpose of a particular study."""
        return self.__dataset

    @dataset.setter
    def dataset(self, dataset: str) -> None:
        self.__dataset = str(dataset)

    @property
    def subject(self) -> Union[str, None]:
        """A participant identifier of the form sub-<label>, matching a participant entity in the dataset."""
        return self.__subject

    @subject.setter
    def subject(self, subject: Union[str, None]) -> None:
        match = re.match(r"^sub-[0-9a-zA-Z]+$", str(subject))
        if match:
            self.__subject = subject
        else:
            sanitized = re.sub(r"[^A-Za-z0-9]+", "", str(subject))
            self.__subject = f"sub-{sanitized}"

    @property
    def task(self) -> Union[str, None]:
        """A set of structured activities performed by the participant."""
        return self.__task

    @task.setter
    def task(self, task: Union[str, None]) -> None:
        pattern = re.compile(r"^task-[0-9a-zA-Z]+$", re.I)
        match = pattern.match(str(task))
        if match:
            self.__task = task
        else:
            sanitized = re.sub(r"[^A-Za-z0-9]+", "", str(task))
            self.__task = f"task-{sanitized}"

    @property
    def session(self) -> Union[str, None]:
        """A logical grouping of neuroimaging and behavioral data consistent across subjects."""
        return self.__session

    @session.setter
    def session(self, session: Union[str, None]) -> None:
        if session:
            pattern = re.compile(r"^ses-[0-9a-zA-Z]+$", re.I)
            match = pattern.match(str(session))
            if match:
                self.__session = session
            else:
                sanitized = re.sub(r"[^A-Za-z0-9]+", "", str(session))
                self.__session = f"ses-{sanitized}"
        else:
            self.__session = None

    @property
    def data_type(self) -> str:
        """A functional group of different types of data."""
        return self.__data_type

    @data_type.setter
    def data_type(self, data_type: str) -> None:
        types = [
            "beh",
            "eeg",
            "func",
            "ieeg",
            "nirs",
            "meg",
            "motion",
            "mrs",
            "pet",
        ]
        if str(data_type) in types:
            self.__data_type = str(data_type)
        else:
            msg = f"<data_type> MUST be one of the following: {types}"
            sys.exit(msg)

    @property
    def acq(self) -> Union[str, None]:
        """A label to distinguish a different set of parameters used for acquiring the same modality."""
        return self.__acq

    @acq.setter
    def acq(self, acq: Union[str, None]) -> None:
        if acq:
            pattern = re.compile(r"^acq-[0-9a-zA-Z]+$", re.I)
            match = pattern.match(str(acq))
            if match:
                self.__acq = acq
            else:
                sanitized = re.sub(r"[^A-Za-z0-9]+", "", str(acq))
                self.__acq = f"acq-{sanitized}"
        else:
            self.__acq = None

    @property
    def events(self) -> List[Union[BIDSBehEvent, BIDSTaskEvent]]:
        """Get the list of events."""
        return self.__events

    def addEvent(
        self,
        event: Union[
            BIDSBehEvent, BIDSTaskEvent, List[Union[BIDSBehEvent, BIDSTaskEvent]]
        ],
    ) -> None:
        """Add an event or list of events.

        Parameters
        ----------
        event : Any or list
            The event or list of events to be added to the list.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset")
        >>> handler.addEvent(bids.BIDSBehEvent(trial=1))
        >>> handler.addEvent([bids.BIDSBehEvent(trial=2), bids.BIDSBehEvent(trial=3)])
        """
        if isinstance(event, list):
            self.__events.extend(event)
        else:
            self.__events.append(event)

    def addChanges(
        self, changes: list, version: str = "PATCH", force: bool = False
    ) -> None:
        """Update the version history of the dataset.

        This method updates the CPAN changelog-like file `CHANGES` by adding a new version entry
        with the specified changes and incrementing the version number accordingly.

        Parameters
        ----------
        changes : list
            List of changes or bullet points for the new version.
        version : str, optional
            The version part to increment. Must be one of "MAJOR", "MINOR", or "PATCH".
        force : bool, optional
            Specifies whether existing file should be overwritten.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject=None, task=None)
        >>> handler.createDataset()
        >>> handler.addChanges(["Added new data files"], "MAJOR")

        Notes
        -----
        Version history of the dataset (describing changes, updates and corrections) MAY be provided
        in the form of a CHANGES text file. This file MUST follow the CPAN Changelog convention.
        The CHANGES file MUST be either in ASCII or UTF-8 encoding. For more details on the CHANGES
        file, see:
        https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#changes
        """
        changelog_dest = Path(self.dataset) / "CHANGES"
        if not force and changelog_dest.exists():
            self._log(
                "WARN",
                "File 'CHANGES' already exists, use force to overwrite it!",
            )
            return

        new_version = self._incrementVersion(changelog_dest, version)
        entry = self._createChangeLogEntry(new_version, changes, changelog_dest)

        with open(changelog_dest, mode="w", encoding="utf-8") as file:
            file.write(entry + "\n\n")

    def addDatasetDescription(
        self, file_path: Union[str, None] = None, force: bool = False
    ) -> None:
        """Add a description to the dataset by creating `dataset_description.json`.

        This method adds the required `dataset_description.json` file to the dataset.

        Parameters
        ----------
        file_path : str or None, optional
            Path to a custom `dataset_description.json` file. If None, the default template is used.
        force : bool, optional
            Specifies whether existing files should be overwritten.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addDatasetDescription()

        Notes
        -----
        The file `dataset_description.json` is a JSON file describing the dataset. Every dataset
        MUST include this file. For more details, see:
        https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#dataset-description
        """
        dataset_desc = Path(self.dataset) / "dataset_description.json"
        if not force and dataset_desc.exists():
            self._log(
                "WARN",
                "File 'dataset_description.json' already exists, use force to overwrite it!",
            )
            return

        ds_info = self._loadDatasetDescriptionTemplate(file_path)
        if not file_path:
            warnings.warn(
                "[psychopy-bids(handler)] Using the default dataset_description template. "
                "Please update placeholder metadata to match your study before sharing the dataset. "
            )
        ds_info.update(
            {
                "Name": self.dataset,
                "BIDSVersion": self._getLatestBidsVersion(),
                "HEDVersion": self._getLatestHedVersion(),
                "DatasetType": "raw",
                "GeneratedBy": [
                    {
                        "Name": "psychopy-bids",
                        "Version": self._getPackageVersion("psychopy-bids"),
                        "Description": "A PsychoPy plugin for working with the Brain Imaging Data Structure (BIDS).",
                        "CodeURL": "https://gitlab.com/psygraz/psychopy-bids",
                    }
                ],
            }
        )

        with open(dataset_desc, "w", encoding="utf-8") as write_file:
            json.dump(ds_info, write_file, indent=4)
            write_file.write("\n")

    def _updateDatasetDescription(self, updates: dict) -> None:
        """Update fields in dataset_description.json while preserving formatting."""
        dataset_desc = Path(self.dataset) / "dataset_description.json"
        if not dataset_desc.exists():
            self.addDatasetDescription()

        with dataset_desc.open("r", encoding="utf-8") as file:
            ds_info = json.load(file)

        ds_info.update(updates)

        with dataset_desc.open("w", encoding="utf-8") as write_file:
            json.dump(ds_info, write_file, indent=4)
            write_file.write("\n")

    def addLicense(self, identifier: str, force: bool = False) -> None:
        """Add a license file to the dataset.

        This method downloads a license with the given identifier from the SPDX license list and
        copies the content into the file `LICENSE`.

        Parameters
        ----------
        identifier : str
            Identifier of the license.
        force : bool, optional
            Specifies whether existing file should be overwritten.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addLicense("CC-BY-NC-4.0")

        Notes
        -----
        A LICENSE file MAY be provided in addition to the short specification of the used license
        in the dataset_description.json "License" field. The "License" field and LICENSE file MUST
        correspond. The LICENSE file MUST be either in ASCII or UTF-8 encoding. For more details, see:
        https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#license
        """
        dataset_desc = Path(self.dataset) / "dataset_description.json"
        if not dataset_desc.exists():
            self.addDatasetDescription()

        self._updateDatasetDescription({"License": identifier})

        license_dest = Path(self.dataset) / "LICENSE"
        if not force and license_dest.exists():
            self._log(
                "WARN",
                "File 'LICENSE' already exists, use force for overwriting it!",
            )
        else:
            self._downloadLicense(identifier, license_dest)

    def addReadme(self, force: bool = False) -> None:
        """Add a text file explaining the dataset in detail.

        This method adds a `README` template file to the dataset, which contains the main sections
        needed to describe the dataset in more detail.

        Parameters
        ----------
        force : bool, optional
            Specifies whether existing file should be overwritten.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addReadme()

        Notes
        -----
        A REQUIRED text file, README, SHOULD describe the dataset in more detail. A BIDS dataset
        MUST NOT contain more than one README file (with or without extension) at its root
        directory. For more details, see:
        https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#readme
        """
        readme_dest = Path(self.dataset) / "README"
        if not force and readme_dest.exists():
            self._log(
                "WARN",
                "File 'README' already exists, use force for overwriting it!",
            )
        else:
            bidsdir = Path(sys.modules["psychopy_bids.bids"].__path__[0])
            readme_src = bidsdir / "template" / "README"
            shutil.copyfile(readme_src, readme_dest)
            warnings.warn(
                "[psychopy-bids(handler)] Creating README from the default template. "
                "Please customize placeholder sections to match your study before sharing the dataset."
            )

    def addTaskCode(self, path: Union[str, None] = None, force: bool = False) -> None:
        """Add psychopy script or specified code directory to the BIDS /code directory.

        This method copies the psychopy script or a specified folder into the `/code` directory
        of the dataset. If a path is provided, the function handles files and folders
        appropriately. If the path starts with "code/", this prefix is stripped only for the
        destination placement.

        Parameters
        ----------
        path : str, optional
            Path to the file or folder to copy. If None, the main script is used.
        force : bool, optional
            If True, existing files are overwritten. Default is False.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.addTaskCode(path="../bids_validator/psychopy_run/validator_experiment.py", force=True)

        Notes
        -----
        The method ensures no files are overwritten unless the `force` parameter is set to True.
        If the path starts with "code/", the prefix is stripped only from the destination.
        If a file or directory already exists in `/code`, a warning is issued unless `force=True`.
        """
        code_path, psyexp_path, py_path = self._determineCodePath(path)
        code_dir = Path(self.dataset) / "code"
        code_dir.mkdir(parents=True, exist_ok=True)

        self._copyItem(code_path, code_dir, force)
        for extra in (psyexp_path, py_path):
            if extra and extra.exists():
                self._copyItem(extra, code_dir, force)

    def addConditionFiles(
        self, path: Union[str, None] = None, force: bool = False
    ) -> None:
        """Copy condition CSV files referenced in data.importConditions() to the BIDS /code directory.

        This method reads a PsychoPy script, detects all CSV files referenced via
        ``data.importConditions()``, and copies them into the ``/code`` directory of the BIDS
        dataset, preserving their relative path structure.

        Parameters
        ----------
        path : str, optional
            Path to the PsychoPy script to inspect. If None, the main script (``sys.argv[0]``)
            is used.
        force : bool, optional
            If True, existing files are overwritten. Default is False.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addConditionFiles(path="../tests/bids_validator/psychopy_run/validator_experiment.py", force=True)

        Notes
        -----
        Only condition files referenced with a literal string path (e.g.
        ``data.importConditions('materials/conditions.csv')``) are detected. Dynamic paths
        constructed at runtime cannot be resolved statically.
        """
        code_path, *_ = self._determineCodePath(path)
        if not code_path.exists():
            self._log("ERROR", f"Script '{code_path}' not found.")
            return

        condition_files = self._detectConditionFiles(code_path)
        if not condition_files:
            self._log("INFO", "No condition files detected in script.")
            return

        script_dir = code_path.parent
        code_dir = Path(self.dataset) / "code"
        code_dir.mkdir(parents=True, exist_ok=True)

        for csv_rel_path in condition_files:
            csv_src = script_dir / csv_rel_path
            if not csv_src.exists():
                self._log("WARN", f"Condition file '{csv_src}' not found, skipping.")
                continue
            csv_dst_dir = code_dir / Path(csv_rel_path).parent
            csv_dst_dir.mkdir(parents=True, exist_ok=True)
            self._copyItem(csv_src, csv_dst_dir, force)

    def addDirectoryStructure(self, force: bool = False) -> None:
        """Generate a directory structure file for the PsychoPy experiment folder.

        Uses the ``seedir`` package to create a human-readable text representation of the
        PsychoPy experiment folder (the parent of the BIDS dataset) and writes it to
        ``directory_structure.txt`` inside the dataset's ``code/`` directory. The BIDS
        dataset folder and PsychoPy's ``data`` output folder are excluded from the tree.

        Parameters
        ----------
        force : bool, optional
            If True, an existing file is overwritten. Default is False.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addDirectoryStructure(force=True)  # doctest: +SKIP

        """
        try:
            import seedir  # pylint: disable=import-outside-toplevel
        except ImportError:
            self._log(
                "WARN",
                "'seedir' is not installed. Install it with: pip install seedir",
            )
            return

        code_dir = Path(self.dataset) / "code"
        code_dir.mkdir(parents=True, exist_ok=True)
        output_path = code_dir / "directory_structure.txt"

        if not force and output_path.exists():
            self._log(
                "WARN",
                "File 'code/directory_structure.txt' already exists, use force=True to overwrite.",
            )
            return

        experiment_dir = Path(self.dataset).parent
        bids_folder_name = Path(self.dataset).name
        structure = seedir.seedir(
            str(experiment_dir),
            style="lines",
            indent=2,
            printout=False,
            exclude_folders=[bids_folder_name, "data"],
        )
        with open(output_path, "w", encoding="utf-8") as f:
            f.write(structure)

    @staticmethod
    def _collectEnvironmentInfo() -> dict:
        """Collect information about the current Python environment.

        Returns
        -------
        dict
            A dict with keys: python_version, platform, in_venv, in_conda,
            conda_prefix, packages (name -> {version, install_type, direct_url}),
            duplicates (list of (name, old_v, new_v, selected_v) tuples).
        """
        in_venv = sys.prefix != sys.base_prefix
        conda_prefix = os.environ.get("CONDA_PREFIX", "")
        in_conda = bool(conda_prefix) or "envs" in sys.prefix.replace("\\", "/")

        packages = {}
        duplicates = []
        for dist in importlib.metadata.distributions():
            name = dist.metadata["Name"].lower()
            version = dist.version
            old_version = packages.get(name, {}).get("version")

            # Detect install type via direct_url.json
            direct_url_text = dist.read_text("direct_url.json")
            if direct_url_text:
                direct_url = json.loads(direct_url_text)
                url = direct_url.get("url", "")
                dir_info = direct_url.get("dir_info", {})
                vcs_info = direct_url.get("vcs_info", {})
                if url.endswith(".whl") and url.startswith("file://"):
                    install_type = "wheel"
                elif dir_info.get("editable") is True:
                    install_type = "editable"
                elif url.startswith("file://"):
                    install_type = "local_dir"
                elif vcs_info or not url.startswith("file://"):
                    install_type = "url"
                else:
                    install_type = "pypi"
            else:
                direct_url = None
                install_type = "pypi"

            if old_version and old_version != version:
                selected_version = str(max(Version(old_version), Version(version)))
                packages[name]["version"] = selected_version
                duplicates.append((name, old_version, version, selected_version))
            else:
                packages[name] = {
                    "version": version,
                    "install_type": install_type,
                    "direct_url": direct_url,
                }

        return {
            "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
            "platform": sys.platform,
            "in_venv": in_venv,
            "in_conda": in_conda,
            "conda_prefix": conda_prefix,
            "packages": packages,
            "duplicates": duplicates,
        }

    @staticmethod
    def _writeRequirements(
        env_info: dict,
        req_path: Path,
        copy_wheels: bool = False,
        wheels_dir: Union[Path, None] = None,
    ) -> None:
        """Write a requirements.txt file from collected environment info.

        Parameters
        ----------
        env_info : dict
            Output of :meth:`_collectEnvironmentInfo`.
        req_path : pathlib.Path
            Destination path for requirements.txt.
        copy_wheels : bool
            If True, copy local wheel files into ``wheels_dir``.
        wheels_dir : pathlib.Path or None
            Directory to copy wheel files into when ``copy_wheels`` is True.
        """
        with open(req_path, "w", encoding="utf-8") as f:
            f.write(f"# Python version: {env_info['python_version']}\n")
            f.write(f"# Platform: {env_info['platform']}\n")
            if env_info["in_conda"]:
                f.write(
                    "# WARNING: Conda environment detected. Conda-managed packages are not listed here.\n"
                )
                if env_info["conda_prefix"]:
                    f.write(f"# CONDA_PREFIX: {env_info['conda_prefix']}\n")

            for pkg_name in sorted(env_info["packages"]):
                info = env_info["packages"][pkg_name]
                version = info["version"]
                install_type = info["install_type"]
                direct_url = info["direct_url"]

                if install_type == "pypi":
                    f.write(f"{pkg_name}=={version}\n")

                elif install_type == "editable":
                    url = direct_url.get("url", "")
                    f.write(f"# {pkg_name} is an editable install from {url}\n")
                    f.write(f"{pkg_name}=={version}  # editable install\n")

                elif install_type == "wheel":
                    url = direct_url.get("url", "")
                    # Convert file:// URL to filesystem path
                    wheel_path = Path(
                        urllib.request.url2pathname(url[len("file://") :])
                    )
                    if copy_wheels and wheels_dir is not None and wheel_path.exists():
                        wheels_dir.mkdir(exist_ok=True)
                        dest = wheels_dir / wheel_path.name
                        shutil.copy2(wheel_path, dest)
                        # Path is relative to requirements.txt location (code/)
                        f.write(f"{pkg_name} @ file:///./wheels/{wheel_path.name}\n")
                    else:
                        f.write(
                            f"# {pkg_name} was installed from wheel: {url}  # wheel not bundled\n"
                        )
                        f.write(f"{pkg_name}=={version}  # wheel install\n")

                elif install_type == "local_dir":
                    url = direct_url.get("url", "")
                    f.write(f"# {pkg_name} installed from local directory: {url}\n")
                    f.write(f"{pkg_name}=={version}  # local directory install\n")

                elif install_type == "url":
                    url = direct_url.get("url", "")
                    f.write(f"{pkg_name} @ {url}\n")

    def addEnvironment(self, copy_wheels: bool = True) -> None:
        """Generate a requirements.txt and optionally bundle wheel files.

        Scans the current Python environment for installed packages and writes
        ``{dataset}/code/requirements.txt``. Packages installed from local wheel
        files, editable installs, and local directories are annotated.

        Parameters
        ----------
        copy_wheels : bool
            If True, copy local wheel files into ``{dataset}/code/wheels/`` and
            reference them with a relative path in requirements.txt.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        >>> handler.addEnvironment()
        >>> handler.addEnvironment(copy_wheels=True)
        """
        code_dir = Path(self.dataset) / "code"
        code_dir.mkdir(exist_ok=True)
        req_path = code_dir / "requirements.txt"
        wheels_dir = code_dir / "wheels" if copy_wheels else None

        env_info = BIDSHandler._collectEnvironmentInfo()

        if env_info["duplicates"]:
            self._log(
                "INFO",
                f"Detected {len(env_info['duplicates'])} packages with multiple installed versions "
                "while generating requirements.txt. Using the highest version for each package.",
            )
            duplicate_detail = "; ".join(
                f"{name} ({old_v}, {new_v}) -> {selected_v}"
                for name, old_v, new_v, selected_v in env_info["duplicates"]
            )
            self._log(
                "DEBUG", f"Resolved package version conflicts: {duplicate_detail}"
            )

        if env_info["in_conda"]:
            self._log(
                "WARNING",
                "Conda environment detected. Only pip-installed packages are captured in requirements.txt.",
            )

        BIDSHandler._writeRequirements(
            env_info, req_path, copy_wheels=copy_wheels, wheels_dir=wheels_dir
        )

    def createDataset(
        self,
        readme: bool = True,
        chg: bool = True,
        lic: bool = True,
        force: bool = False,
    ) -> None:
        """Create the rudimentary body of a new dataset.

        Parameters
        ----------
        readme : bool, optional
            Specifies whether a README file should be created.
        chg : bool, optional
            Specifies whether a CHANGES file should be created.
        lic : bool, optional
            Specifies whether a LICENSE file should be created.
        force : bool, optional
            Specifies whether existing files should be overwritten.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> handler.createDataset()
        """
        dataset_path = Path(self.dataset)
        if not force and dataset_path.exists():
            self._log(
                "WARN",
                f"The folder {self.dataset} already exists! Use the parameter force if you want to recreate a dataset in an existing, non-empty directory",
            )
            return

        dataset_path.mkdir(exist_ok=True)
        (dataset_path / "participants.tsv").touch()

        self.addDatasetDescription()
        if readme:
            self.addReadme(force=force)
        if chg:
            self.addChanges(changes=["Initialize the dataset"], force=force)
        if lic:
            self.addLicense(identifier="CC-BY-NC-4.0", force=force)

    def writeEvents(
        self,
        participant_info: dict,
        execute_sidecar: Union[bool, str] = True,
        generate_hed_metadata: bool = False,
        add_stimuli: bool = True,
        event_type: str = "both",
    ):
        """Writes all existing events in `self.events` to the dataset.

        Parameters
        ----------
        participant_info : dict
            Key-value pairs describing participant info (e.g. age, sex, group) to be inserted
            into participants.tsv. A 'participant_id' key will automatically be added/updated
            with `self.subject`.
        execute_sidecar : Union[bool, str], optional
            If True, creates or updates a JSON sidecar file for the events file with metadata.
            If a string, uses the provided path to update the sidecar file.
        generate_hed_metadata : bool, optional
            If True, automatically generates HED metadata based on the event file.
            Only applies if execute_sidecar is not False.
        add_stimuli : bool, optional
            If True, copies any referenced stimuli in the event file to a `/stimuli` folder.
        event_type : str, optional
            One of {'both', 'beh', 'task'}:
            - 'both': Writes both behavioral and task events.
            - 'beh': Only writes behavioral events (`*_beh.tsv`).
            - 'task': Only writes task events (`*_events.tsv`).

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset")
        >>> handler.addEvent(bids.BIDSBehEvent(trial=1))
        >>> handler.addEvent(bids.BIDSTaskEvent(onset=1.0, duration=0.5))
        >>> handler.writeEvents(participant_info={'participant_id': handler.subject}, execute_sidecar=False)
        """
        self._updateParticipantsFile(participant_info)
        if self.session:
            self._updateSessionsFile()

        bids_beh_events = [e for e in self.events if type(e) is BIDSBehEvent]
        bids_task_events = [e for e in self.events if type(e) is BIDSTaskEvent]

        if event_type == "beh":
            bids_task_events = []
        elif event_type == "task":
            bids_beh_events = []

        written_events = []
        if bids_beh_events:
            written_events.extend(
                self._writeSingleEventFile(
                    bids_beh_events,
                    "beh",
                    execute_sidecar,
                    generate_hed_metadata,
                    add_stimuli,
                )
            )
        if bids_task_events:
            written_events.extend(
                self._writeSingleEventFile(
                    bids_task_events,
                    "events",
                    execute_sidecar,
                    generate_hed_metadata,
                    add_stimuli,
                )
            )

        self.__events = [e for e in self.events if e not in written_events]

    def _updateParticipantsFile(self, participant_info: dict) -> None:
        """
        Update or create the participants.tsv file with the given participant information.

        Parameters
        ----------
        participant_info : dict
            Dictionary containing participant metadata (e.g., {'age': 25, 'sex': 'M'}).
            The key 'participant_id' will be updated with `self.subject`.
        """
        participants_file = Path(self.dataset) / "participants.tsv"
        participant_info["participant_id"] = self.subject

        if participants_file.stat().st_size == 0:
            df_participants = pd.DataFrame([participant_info])
            participant_cols = ["participant_id"] + [
                col for col in df_participants.columns if col != "participant_id"
            ]
            df_participants = df_participants[participant_cols]
            df_participants = df_participants.fillna("n/a").replace("", "n/a")
            participants_metadata = {
                field: {
                    "Description": "RECOMMENDED. Free-form natural language description."
                }
                for field in participant_info
            }
            warnings.warn(
                "[psychopy-bids(handler)] Creating participants.json with default placeholder "
                "descriptions. Please replace these with study-specific metadata before "
                "sharing or validating the dataset."
            )
            with open(
                f"{self.dataset}/participants.json", mode="w", encoding="utf-8"
            ) as f:
                json.dump(participants_metadata, f, indent=4)

            df_participants.to_csv(
                participants_file, sep="\t", index=False, lineterminator="\n"
            )
        else:
            df_participants = pd.read_csv(participants_file, sep="\t")
            if self.subject not in df_participants["participant_id"].tolist():
                df_participants = pd.concat(
                    [df_participants, pd.DataFrame([participant_info])],
                    ignore_index=True,
                )
                participant_cols = ["participant_id"] + [
                    col for col in df_participants.columns if col != "participant_id"
                ]
                df_participants = df_participants[participant_cols]
                df_participants = df_participants.fillna("n/a").replace("", "n/a")
                df_participants.to_csv(
                    participants_file, sep="\t", index=False, lineterminator="\n"
                )

                json_path = Path(self.dataset) / "participants.json"
                try:
                    with open(json_path, mode="r", encoding="utf-8") as f:
                        existing_metadata = json.load(f)
                except (FileNotFoundError, json.JSONDecodeError):
                    existing_metadata = {}
                new_columns = {
                    field: {
                        "Description": "RECOMMENDED. Free-form natural language description."
                    }
                    for field in participant_info
                    if field not in existing_metadata
                }
                if new_columns:
                    existing_metadata.update(new_columns)
                    with open(json_path, mode="w", encoding="utf-8") as f:
                        json.dump(existing_metadata, f, indent=4)

    def _updateSessionsFile(self) -> None:
        """
        Create or update the sessions.tsv file for the current subject.

        The file is located at ``<dataset>/<subject>/sessions.tsv`` and lists
        every session recorded for that subject, with ``session_id`` as the
        first (and mandatory) column.
        """
        sessions_file = (
            Path(self.dataset) / self.subject / f"{self.subject}_sessions.tsv"
        )
        sessions_file.parent.mkdir(parents=True, exist_ok=True)

        if sessions_file.exists() and sessions_file.stat().st_size > 0:
            df_sessions = pd.read_csv(sessions_file, sep="\t")
            if self.session in df_sessions["session_id"].tolist():
                return
            df_sessions = pd.concat(
                [df_sessions, pd.DataFrame([{"session_id": self.session}])],
                ignore_index=True,
            )
        else:
            df_sessions = pd.DataFrame([{"session_id": self.session}])

        df_sessions = df_sessions.fillna("n/a").replace("", "n/a")
        df_sessions.to_csv(sessions_file, sep="\t", index=False, lineterminator="\n")

    def _writeSingleEventFile(
        self,
        events: list,
        event_type: str,
        execute_sidecar: Union[bool, str],
        generate_hed_metadata: bool,
        add_stimuli: bool,
    ) -> list:
        """
        Write a single type of events to the dataset (behavioral or task).

        Optionally creates a JSON sidecar file and copies stimuli if requested.

        Parameters
        ----------
        events : list
            List of event dictionaries (BIDSBehEvent or BIDSTaskEvent instances, as dicts).
        event_type : str
            The suffix in the event filename (e.g., 'beh' or 'events').
        execute_sidecar : Union[bool, str]
            If True, calls `_addJsonSidecar` to create/update sidecar metadata.
            If a string, uses the provided path to update the sidecar file.
        generate_hed_metadata : bool
            If True, automatically generates HED metadata based on the event file.
            Only applies if execute_sidecar is not False.
        add_stimuli : bool
            If True, calls `_addStimuliFolder` to copy referenced stimuli.

        Returns
        -------
        list
            The same list of events that were written, for reference (used to update `self.__events`).
        """
        df_events = pd.DataFrame(events)
        df_events.dropna(how="all", axis=1, inplace=True)
        df_events = df_events.fillna("n/a").infer_objects(copy=False)

        if "hed" in df_events.columns:
            df_events.rename(columns={"hed": "HED"}, inplace=True)

        if "stim_file" in df_events.columns:
            df_events["stim_file"] = df_events["stim_file"].apply(
                lambda stim: (
                    Path(*Path(stim).parts[1:]).as_posix()
                    if stim.startswith("stimuli/")
                    else stim.replace("\\", "/")
                )
            )

        if "onset" in df_events.columns and "duration" in df_events.columns:
            if self._t_start is not None:
                df_events["onset"] = (df_events["onset"] - self._t_start).round(4)
            _required = ["onset", "duration"]
            _reserved = ["trial_type", "response_time", "HED", "stim_file", "channel"]
            _known = set(_required + _reserved)
            col_order = (
                _required
                + [c for c in _reserved if c in df_events.columns]
                + [c for c in df_events.columns if c not in _known]
            )
            df_events = df_events[col_order]
            df_events = df_events.sort_values("onset", kind="stable").reset_index(
                drop=True
            )

        filepath = self._generateEventFilePath(event_type)
        df_events.to_csv(filepath, sep="\t", index=False)

        if execute_sidecar:
            self._addJsonSidecar(
                filepath, event_type, execute_sidecar, generate_hed_metadata
            )
        if add_stimuli:
            self._addStimuliFolder(filepath)

        return events

    def _generateEventFilePath(self, event_type: str) -> Path:
        """
        Generate the file path for the event file based on its type and the current
        dataset, subject, session, and data_type.

        Parameters
        ----------
        event_type : str
            The suffix to use in the filename (e.g., 'beh' or 'events').

        Returns
        -------
        pathlib.Path
            The full path (including filename) to the event file to be created.
        """
        event_dir_parts = [self.dataset, self.subject]
        if self.session:
            event_dir_parts.append(self.session)
        event_dir_parts.append(self.data_type)
        event_dir = Path(*event_dir_parts)
        event_dir.mkdir(parents=True, exist_ok=True)

        filename_parts = [self.subject, self.task]
        if self.session:
            filename_parts.insert(1, self.session)
        if self.acq:
            filename_parts.append(self.acq)
        base_filename = "_".join(filename_parts)

        if not isinstance(self.runs, bool):
            file_name = f"{base_filename}_run-{self.runs}_{event_type}.tsv"
        elif self.runs:
            existing_files = list(event_dir.glob(f"{base_filename}*_{event_type}.tsv"))
            run_numbers = [
                int(m.group(1))
                for f in existing_files
                if (m := re.search(r"_run-(\d+)_", f.name))
            ]
            next_run = (max(run_numbers) + 1) if run_numbers else 1
            file_name = f"{base_filename}_run-{next_run:03d}_{event_type}.tsv"
        else:
            file_name = f"{base_filename}_{event_type}.tsv"

        full_event_path = event_dir / file_name

        if event_type == "beh" and self.data_type != "beh":
            warnings.warn(
                f"[psychopy-bids(handler)] You are writing a 'beh' event file in a dataset with data_type='{self.data_type}', "
                "which is not BIDS valid. "
                "If you intend to store behavioral event data, please set 'data_type=beh'. "
                "Otherwise, use Task events instead. "
                f"\nThis invalid file has been saved to: {full_event_path}"
            )
        return full_event_path

    def _addJsonSidecar(
        self,
        event_filepath: Path,
        event_type: str,
        sidecar_path: Union[bool, str],
        generate_hed_metadata: bool,
    ) -> None:
        """
        Create or update the JSON sidecar file for the events file.

        Parameters
        ----------
        event_filepath : pathlib.Path
            The path to the written event TSV file.
        event_type : str
            Indicates whether this is a 'beh' or 'events' file for the sidecar naming.
        sidecar_path : Union[bool, str]
            If a string, uses the provided path to update the sidecar file.
        generate_hed_metadata : bool
            If True, automatically generates HED metadata based on the event file.
        """
        if isinstance(sidecar_path, str):
            template_path = Path(sidecar_path)
            if template_path.exists():
                sidecar = self._loadSidecarTemplate(template_path)
            else:
                warnings.warn(
                    f"[psychopy-bids(handler)] Provided sidecar template does not exist at: {template_path}. Falling back to an empty template."
                )
                sidecar = {}
        else:
            sidecar = {}

        json_path = (
            Path(self.dataset)
            / f"{self.task}_{self.acq + '_' if self.acq else ''}{event_type}.json"
        )

        existing_sidecar = {}
        if json_path.exists():
            try:
                with open(json_path, mode="r", encoding="utf-8") as json_reader:
                    existing_sidecar = json.load(json_reader)
                self._log(
                    "DEBUG",
                    f"Found an existing sidecar file at {json_path}. It will be updated with new metadata and any missing fields.",
                )
            except (TypeError, json.JSONDecodeError):
                warnings.warn(
                    f"[psychopy-bids(handler)] Failed to load the existing sidecar file at {json_path}. The file might be corrupted or "
                    "contain invalid JSON format. Proceeding with the creation of a new sidecar."
                )

        if not isinstance(sidecar_path, str) and not json_path.exists():
            warnings.warn(
                f"[psychopy-bids(handler)] Creating {json_path.name} from the default sidecar metadata template. "
                "Please update placeholder fields (for example TaskDescription, Instructions, "
                "CogAtlasID, InstitutionName) before sharing the dataset."
            )

        task_metadata = {
            "TaskName": self.task.replace("task-", ""),
            "TaskDescription": "RECOMMENDED. Detailed description of the task.",
            "Instructions": "RECOMMENDED. Text of the instructions given to participants.",
            "CogAtlasID": "RECOMMENDED. URL of the corresponding Cognitive Atlas term.",
            "CogPOID": "RECOMMENDED. URL of the corresponding CogPO term.",
            "InstitutionName": "RECOMMENDED. The institution responsible for the equipment.",
            "InstitutionAddress": "RECOMMENDED. The address of the institution.",
            "InstitutionalDepartmentName": "RECOMMENDED. The department within the institution.",
        }
        sidecar = {**task_metadata, **sidecar}

        event_data = pd.read_csv(event_filepath, sep="\t")

        if "HED" not in event_data.columns and generate_hed_metadata and TabularSummary:
            skip_columns = {"onset", "duration", "trial_type"}
            skip_columns.update(existing_sidecar.keys())
            skip_columns.update(sidecar.keys())
            value_columns = ["response_time"]
            value_columns = [col for col in value_columns if col not in skip_columns]
            value_summary = TabularSummary(
                value_cols=value_columns, skip_cols=skip_columns
            )
            value_summary.update([str(event_filepath)])
            hed_metadata = value_summary.extract_sidecar_template()
        else:
            self._log(
                "DEBUG",
                "HED metadata generation disabled, HED column found in the event file, or TabularSummary not available. Skipping HED metadata generation.",
            )
            hed_metadata = {}

        column_metadata_template = {
            "Description": "RECOMMENDED. Free-form natural language description.",
        }

        bids_numeric_columns = {"onset", "duration", "response_time"}

        for column_name in event_data.columns:
            if (
                column_name not in sidecar
                and column_name not in {"HED"} | bids_numeric_columns
            ):
                col_meta = column_metadata_template.copy()
                unique_values = [
                    v
                    for v in event_data[column_name].unique()
                    if pd.notna(v) and v != "n/a"
                ]
                if event_data[column_name].dtype == object and unique_values:
                    col_meta["Levels"] = {
                        str(v): "RECOMMENDED. Description of this level."
                        for v in sorted(unique_values)
                    }
                sidecar[column_name] = col_meta
                self._log(
                    "DEBUG",
                    f"Adding column '{column_name}' to the sidecar metadata. "
                    "This column was found in the event file but not in the provided/default template.",
                )

            if column_name in hed_metadata:
                for key, value in hed_metadata[column_name].items():
                    if key not in sidecar[column_name]:
                        sidecar[column_name][key] = value
                    elif isinstance(value, dict):
                        sidecar[column_name][key] = {
                            **sidecar[column_name].get(key, {}),
                            **value,
                        }

        for sidecar_column in sidecar.keys():
            if (
                sidecar_column not in event_data.columns
                and sidecar_column not in task_metadata
            ):
                warnings.warn(
                    f"[psychopy-bids(handler)] The column '{sidecar_column}' is present in the sidecar but does not appear in the event file '{event_filepath}'."
                )

        for key, value in existing_sidecar.items():
            if key not in sidecar:
                sidecar[key] = value

        sidecar["StimulusPresentation"] = {
            "OperatingSystem": self._getOsInfo(),
            "SoftwareName": "PsychoPy",
            "SoftwareRRID": "RRID:SCR_006571",
            "SoftwareVersion": self._getPackageVersion("psychopy"),
        }

        has_hed_metadata = "HED" in event_data.columns or any(
            isinstance(column_meta, dict) and "HED" in column_meta
            for column_meta in sidecar.values()
        )
        if has_hed_metadata:
            self._updateDatasetDescription({"HEDVersion": self._getLatestHedVersion()})

        with open(json_path, mode="w", encoding="utf-8") as json_file:
            json.dump(sidecar, json_file, indent=4)
            json_file.write("\n")

    def _addStimuliFolder(self, event_filepath) -> None:
        """
        Copies files referenced in the 'stim_file' column of the event TSV into a
        'stimuli' directory under the dataset root, preserving folder structure.

        Parameters
        ----------
        event_filepath : str or pathlib.Path
            Path to the TSV event file from which to extract 'stim_file' references.
        """
        dest_path = Path(self.dataset) / "stimuli"
        data_frame = pd.read_csv(event_filepath, sep="\t")

        if "stim_file" in data_frame.columns:
            for stim in data_frame["stim_file"].replace("n/a", pd.NA).dropna().unique():
                stim_path = Path(stim)
                src = stim_path if stim_path.is_file() else Path("stimuli") / stim_path
                dest_file = dest_path / stim_path

                if src.is_file():
                    dest_file.parent.mkdir(parents=True, exist_ok=True)
                    shutil.copyfile(src, dest_file)
                else:
                    self._log("WARN", f"File '{stim}' not found at '{src}'!")

    @staticmethod
    def parseLog(file, level="BIDS", regex=None) -> list:
        """Extract events from a log file.

        This method parses a given log file based on the specified log level and, optionally, a
        regex pattern. It then processes and structures these events into a list each adhering to
        the BIDSTaskEvent event format.

        Parameters
        ----------
        file : str
            The file path of the log file.
        level : str
            The level name of the bids task events.
        regex : str, optional
            A regular expression to parse the message string.

        Return
        ------
        events : list
            A list of events like presented stimuli or participant responses.

        Examples
        --------
        >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
        >>> log_events = handler.parseLog("simple1.log", "BIDS")
        """
        events = []
        try:
            with open(file, mode="r", encoding="utf-8") as log_file:
                for line in log_file:
                    event = re.split(r" \t|[ ]+", line, maxsplit=2)
                    if level in event:
                        entry = BIDSHandler._parseLogEntry(event, regex)
                        events.append(entry)
        except FileNotFoundError:
            warnings.warn(f"[psychopy-bids(handler)] File {file} not found!")
        return events

    @staticmethod
    def _parseLogEntry(event, regex):
        """Parse a single log entry."""
        if regex:
            match = re.search(regex, event[2])
            entry = match.groupdict() if match else {}
        else:
            entry = {k: v for k, v in literal_eval(event[2]).items() if v is not None}
        entry.setdefault("onset", float(event[0]))
        entry.setdefault("duration", "n/a")
        return entry

    @staticmethod
    def _incrementVersion(changelog_dest, version):
        """Increment the version number based on the specified version part.

        Parameters
        ----------
        changelog_dest : pathlib.Path
            Path to the changelog file
        version : str
            Version part to increment ("MAJOR", "MINOR", or "PATCH")

        Returns
        -------
        str
            The new version number
        """
        if changelog_dest.exists():
            with open(changelog_dest, "r", encoding="utf-8") as file:
                content = file.read()
            matches = re.findall(r"(\d+\.\d+\.\d+)\s+-", content, re.MULTILINE)
            if matches:
                curr_version = [
                    int(num) for num in sorted(matches, reverse=True)[0].split(".")
                ]
                new_version_list = curr_version[:]
                if version == "MAJOR":
                    new_version_list[0] += 1
                elif version == "MINOR":
                    new_version_list[1] += 1
                else:
                    new_version_list[2] += 1
                return ".".join(str(num) for num in new_version_list)
        return "1.0.0"

    @staticmethod
    def _createChangeLogEntry(new_version, changes, changelog_dest):
        """Create a new changelog entry with version, date and changes.

        Parameters
        ----------
        new_version : str
            Version number for the new entry
        changes : list
            List of changes to include
        changelog_dest : pathlib.Path
            Path to the changelog file

        Returns
        -------
        str
            Formatted changelog entry
        """
        entry = f"{new_version} - {datetime.now().strftime('%Y-%m-%d')}\n" + "\n".join(
            [f" - {change}" for change in changes]
        )
        if changelog_dest.exists():
            with open(changelog_dest, "r", encoding="utf-8") as file:
                content = file.read()
            entry += "\n\n" + content
        return entry

    @staticmethod
    def _loadDatasetDescriptionTemplate(file_path):
        """Load the dataset description JSON template.

        Parameters
        ----------
        file_path : Union[str, pathlib.Path, None]
            Path to custom template file, if None uses default

        Returns
        -------
        dict
            Template data as dictionary
        """
        if file_path and Path(file_path).exists():
            with open(file_path, mode="r", encoding="utf-8") as read_file:
                return json.load(read_file)
        bidsdir = Path(sys.modules["psychopy_bids.bids"].__path__[0])
        ds_desc = bidsdir / "template" / "dataset_description.json"
        with open(ds_desc, mode="r", encoding="utf-8") as read_file:
            return json.load(read_file)

    @staticmethod
    def _getPackageVersion(package_name):
        """Get the version of a Python package.

        Parameters
        ----------
        package_name : str
            Name of the package

        Returns
        -------
        str
            Version string or "unknown"
        """
        try:
            version = importlib.metadata.version(package_name)
            if not version:
                warnings.warn(
                    f"[psychopy-bids(handler)] The version of '{package_name}' could not be determined and will be set to 'unknown' in BIDS metadata files."
                )
                return "unknown"
            return version
        except importlib.metadata.PackageNotFoundError:
            warnings.warn(
                f"[psychopy-bids(handler)] The version of '{package_name}' could not be determined and will be set to 'unknown' in BIDS metadata files."
            )
            return "unknown"

    @staticmethod
    def _downloadLicense(identifier, license_dest):
        """Download a license file from SPDX.

        Parameters
        ----------
        identifier : str
            SPDX license identifier
        license_dest : pathlib.Path
            Destination path for license file
        """
        try:
            response = requests.get(
                f"https://spdx.org/licenses/{identifier}.txt", timeout=2
            )
            if response.status_code == 200:
                with open(license_dest, "w", encoding="utf-8") as file:
                    file.write(response.text)
            else:
                BIDSHandler._logStatic(
                    "WARN",
                    f"License '{identifier}' not found or could not be downloaded.",
                )
        except requests.exceptions.Timeout:
            BIDSHandler._logStatic(
                "ERROR",
                f"Request to download {identifier} timed out.",
            )
        except requests.exceptions.RequestException as exc:
            BIDSHandler._logStatic("ERROR", f"Request error: {exc}")

    @staticmethod
    def _determineCodePath(path):
        """Determine code and psyexp paths from input path.

        Parameters
        ----------
        path : Union[str, None]
            Input path to analyze

        Returns
        -------
        tuple
            Tuple of (code_path, psyexp_path)
        """
        if path:
            code_path = Path(path)
            psyexp_path = None
            py_path = None
        else:
            main_script = Path(os.path.basename(sys.argv[0]))
            code_path = main_script
            if "_lastrun" in main_script.stem:
                base_stem = main_script.stem.replace("_lastrun", "")
                psyexp_path = main_script.with_name(base_stem + ".psyexp")
                py_path = main_script.with_name(base_stem + ".py")
            else:
                psyexp_path = None
                py_path = None
        return code_path, psyexp_path, py_path

    @staticmethod
    def _detectConditionFiles(script_path: Path) -> List[str]:
        """Detect CSV condition files referenced in data.importConditions() calls.

        Reads the given PsychoPy script and extracts all literal string paths passed to
        ``data.importConditions()``.

        Parameters
        ----------
        script_path : pathlib.Path
            Path to the PsychoPy script to inspect.

        Returns
        -------
        list of str
            List of relative paths to condition files found in the script.
        """
        pattern = r"data\.importConditions\(['\"]([^'\"]+)['\"]\)"
        with open(script_path, "r", encoding="utf-8") as f:
            source = f.read()
        return re.findall(pattern, source)

    @staticmethod
    def _copyItem(src, dst_dir, force):
        """Copy file or directory to destination, with overwrite protection.

        Parameters
        ----------
        src : pathlib.Path
            Source file or directory to copy
        dst_dir : pathlib.Path
            Destination directory to copy into
        force : bool
            If True, overwrite existing files
        """
        dst = dst_dir / src.name
        if not src.is_dir():
            dst.parent.mkdir(parents=True, exist_ok=True)
        if dst.exists() and not force:
            warnings.warn(
                f"[psychopy-bids(handler)] '{dst}' already exists. Use force=True to overwrite.",
                UserWarning,
            )
        elif src.is_dir():
            shutil.copytree(src, dst, dirs_exist_ok=force)
        else:
            shutil.copy2(src, dst)

    @staticmethod
    def _updateBidsIgnore(bidsignore_path, entry):
        """Update the .bidsignore file by adding a new entry if it doesn't exist.

        Parameters
        ----------
        bidsignore_path : pathlib.Path
            Path to the .bidsignore file
        entry : str
            Entry to add to the ignore file
        """
        entries = []
        if bidsignore_path.exists():
            with open(bidsignore_path, "r", encoding="utf-8") as f:
                entries = f.read().splitlines()
        if entry not in entries:
            entries.append(entry)
            with open(bidsignore_path, "w", encoding="utf-8") as f:
                f.write("\n".join(entries) + "\n")

    @staticmethod
    def _loadSidecarTemplate(template_path: Path) -> dict:
        """
        Load the sidecar template from a specified file path.

        Parameters
        ----------
        template_path : pathlib.Path
            Path to the template file.

        Returns
        -------
        dict
            Loaded sidecar template as a dictionary.
        """
        try:
            if template_path.suffix == ".json":
                with open(template_path, mode="r", encoding="utf-8") as f:
                    return json.load(f)
            elif template_path.suffix in [".csv", ".tsv", ".xlsx"]:
                df = (
                    pd.read_excel(template_path)
                    if template_path.suffix == ".xlsx"
                    else pd.read_csv(
                        template_path,
                        sep="\t" if template_path.suffix == ".tsv" else ",",
                    )
                )

                sidecar = {}
                for _, row in df.iterrows():
                    try:
                        column_name = (
                            str(row["column_name"])
                            .replace("\u00a0", " ")
                            .replace("\n", " ")
                            .strip()
                        )
                        column_value = (
                            str(row["column_value"])
                            .replace("\u00a0", " ")
                            .replace("\n", " ")
                            .strip()
                        )
                        description = (
                            str(row["description"])
                            .replace("\u00a0", " ")
                            .replace("\n", " ")
                            .strip()
                        )
                        hed = (
                            str(row.get("HED", ""))
                            .replace("\u00a0", " ")
                            .replace("\n", " ")
                            .strip()
                        )

                        sidecar.setdefault(column_name, {})[column_value] = {
                            "Description": description,
                            "HED": hed,
                        }
                    except KeyError:
                        warnings.warn(
                            f"[psychopy-bids(handler)] Missing expected keys (e.g., 'column_name', 'column_value', 'description') in the sidecar template file {template_path.name}. "
                            "Skipping the row. Verify the template file structure for completeness."
                        )
                return sidecar
            else:
                raise ValueError(
                    f"[psychopy-bids(handler)] Unsupported file format: {template_path.suffix}"
                )
        except FileNotFoundError:
            warnings.warn(
                f"[psychopy-bids(handler)] File not found: {template_path}. Using an empty template. Ensure the file path is correct."
            )
        except json.JSONDecodeError as e:
            warnings.warn(
                f"[psychopy-bids(handler)] Invalid JSON format in the file {template_path}. The error details are: {e}. "
                "The file might be malformed or not intended to be a JSON sidecar. Using an empty template instead."
            )
        except pd.errors.ParserError as e:
            warnings.warn(
                f"[psychopy-bids(handler)] Failed to parse the file {template_path} as a CSV/TSV. Error details: {e}. Ensure the file conforms to the expected format. "
                "Using an empty template as a fallback."
            )
        except ValueError as e:
            warnings.warn(
                f"[psychopy-bids(handler)] Value error encountered while processing the sidecar template file at {template_path}: {e}. "
                "This may indicate an unsupported format or unexpected data. Proceeding with an empty template."
            )
        return {}

    @staticmethod
    def _getLatestBidsVersion() -> str:
        """Fetch the latest BIDS specification version from GitHub.

        Returns
        -------
        str
            Version string or fallback version
        """
        try:
            response = requests.get(
                "https://api.github.com/repos/bids-standard/bids-specification/releases/latest",
                timeout=2,
            )
            if response.status_code == 200:
                return response.json().get("tag_name", "").lstrip("v")
        except (requests.RequestException, KeyError):
            pass
        return "1.8.0"

    @staticmethod
    def _getLatestHedVersion() -> str:
        """Fetch the latest HED schema version from GitHub.

        Returns
        -------
        str
            Version string or fallback version
        """
        try:
            response = requests.get(
                "https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HEDLatest.xml",
                timeout=2,
            )
            if response.status_code == 200:
                content = response.text
                hed_tag_start = content.find("<HED ")
                if hed_tag_start != -1:
                    version_start = content.find('version="', hed_tag_start) + len(
                        'version="'
                    )
                    version_end = content.find('"', version_start)
                    if version_start != -1 and version_end != -1:
                        return content[version_start:version_end]
        except requests.RequestException:
            pass
        return "8.3.0"

    @staticmethod
    def _getOsInfo():
        try:
            system_name = platform.system()

            if system_name == "Windows" and hasattr(sys, "getwindowsversion"):
                win_build = sys.getwindowsversion().build  # pylint: disable=no-member
                return (
                    "Windows 11"
                    if win_build >= 22000
                    else f"Windows {platform.release()}"
                )

            if system_name == "Linux":
                with open("/etc/os-release", encoding="utf-8") as release_file:
                    os_info = {
                        k: v.strip().strip('"')
                        for k, v in (
                            line.split("=", 1) for line in release_file if "=" in line
                        )
                    }
                return os_info.get("PRETTY_NAME", f"Linux {platform.release()}")

            if system_name == "Darwin":
                return f"macOS {platform.mac_ver()[0]}"

            return f"{system_name} {platform.release()}"

        except (OSError, ValueError, SystemError):
            return "unknown"

acq property writable

A label to distinguish a different set of parameters used for acquiring the same modality.

data_type property writable

A functional group of different types of data.

dataset property writable

A set of neuroimaging and behavioral data acquired for a purpose of a particular study.

events property

Get the list of events.

session property writable

A logical grouping of neuroimaging and behavioral data consistent across subjects.

subject property writable

A participant identifier of the form sub-, matching a participant entity in the dataset.

task property writable

A set of structured activities performed by the participant.

__init__(dataset, subject=None, task=None, session=None, data_type='beh', acq=None, runs=True, log_level='INFO')

Initialize a BIDSHandler object.

Parameters:

Name	Type	Description	Default
dataset	str	A set of neuroimaging and behavioral data acquired for a purpose of a particular study.	required
subject	str	A person or animal participating in the study.	None
task	str	A set of structured activities performed by the participant.	None
session	str	A logical grouping of neuroimaging and behavioral data consistent across subjects.	None
data_type	str	A functional group of different types of data.	'beh'
acq	str	Custom label to distinguish different conditions present during multiple runs of the same task.	None
runs	bool or str	If True, an auto-incrementing run number is added to the filename. If False, no run entity is added. If a string, it is used directly as the run label (e.g. "4a").	True

Source code in psychopy_bids/bids/bidshandler.py

def __init__(
    self,
    dataset: str,
    subject: Union[str, None] = None,
    task: Union[str, None] = None,
    session: Union[str, None] = None,
    data_type: str = "beh",
    acq: Union[str, None] = None,
    runs: Union[bool, str] = True,
    log_level: Union[str, int] = "INFO",
) -> None:
    """Initialize a BIDSHandler object.

    Parameters
    ----------
    dataset : str
        A set of neuroimaging and behavioral data acquired for a purpose of a particular study.
    subject : str, optional
        A person or animal participating in the study.
    task : str, optional
        A set of structured activities performed by the participant.
    session : str, optional
        A logical grouping of neuroimaging and behavioral data consistent across subjects.
    data_type : str, optional
        A functional group of different types of data.
    acq : str, optional
        Custom label to distinguish different conditions present during multiple runs of the
        same task.
    runs : bool or str, optional
        If True, an auto-incrementing run number is added to the filename.
        If False, no run entity is added.
        If a string, it is used directly as the run label (e.g. ``"4a"``).
    """
    self.dataset = dataset
    self.subject = subject
    self.task = task
    self.session = session
    self.data_type = data_type
    self.acq = acq
    self.runs = runs
    self.log_level = self._resolveLogLevel(log_level)
    self._logger = logging.getLogger("psychopy-bids")
    self.__events = []
    self._t_start = None  # BIDS onset reference time (set by BidsOnsetRoutine)

addChanges(changes, version='PATCH', force=False)

Update the version history of the dataset.

This method updates the CPAN changelog-like file CHANGES by adding a new version entry with the specified changes and incrementing the version number accordingly.

Parameters:

Name	Type	Description	Default
changes	list	List of changes or bullet points for the new version.	required
version	str	The version part to increment. Must be one of "MAJOR", "MINOR", or "PATCH".	'PATCH'
force	bool	Specifies whether existing file should be overwritten.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject=None, task=None)
>>> handler.createDataset()
>>> handler.addChanges(["Added new data files"], "MAJOR")

Notes

Version history of the dataset (describing changes, updates and corrections) MAY be provided in the form of a CHANGES text file. This file MUST follow the CPAN Changelog convention. The CHANGES file MUST be either in ASCII or UTF-8 encoding. For more details on the CHANGES file, see: https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#changes

Source code in psychopy_bids/bids/bidshandler.py

def addChanges(
    self, changes: list, version: str = "PATCH", force: bool = False
) -> None:
    """Update the version history of the dataset.

    This method updates the CPAN changelog-like file `CHANGES` by adding a new version entry
    with the specified changes and incrementing the version number accordingly.

    Parameters
    ----------
    changes : list
        List of changes or bullet points for the new version.
    version : str, optional
        The version part to increment. Must be one of "MAJOR", "MINOR", or "PATCH".
    force : bool, optional
        Specifies whether existing file should be overwritten.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject=None, task=None)
    >>> handler.createDataset()
    >>> handler.addChanges(["Added new data files"], "MAJOR")

    Notes
    -----
    Version history of the dataset (describing changes, updates and corrections) MAY be provided
    in the form of a CHANGES text file. This file MUST follow the CPAN Changelog convention.
    The CHANGES file MUST be either in ASCII or UTF-8 encoding. For more details on the CHANGES
    file, see:
    https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#changes
    """
    changelog_dest = Path(self.dataset) / "CHANGES"
    if not force and changelog_dest.exists():
        self._log(
            "WARN",
            "File 'CHANGES' already exists, use force to overwrite it!",
        )
        return

    new_version = self._incrementVersion(changelog_dest, version)
    entry = self._createChangeLogEntry(new_version, changes, changelog_dest)

    with open(changelog_dest, mode="w", encoding="utf-8") as file:
        file.write(entry + "\n\n")

addConditionFiles(path=None, force=False)

Copy condition CSV files referenced in data.importConditions() to the BIDS /code directory.

This method reads a PsychoPy script, detects all CSV files referenced via data.importConditions(), and copies them into the /code directory of the BIDS dataset, preserving their relative path structure.

Parameters:

Name	Type	Description	Default
path	str	Path to the PsychoPy script to inspect. If None, the main script (sys.argv[0]) is used.	None
force	bool	If True, existing files are overwritten. Default is False.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addConditionFiles(path="../tests/bids_validator/psychopy_run/validator_experiment.py", force=True)

Notes

Only condition files referenced with a literal string path (e.g. data.importConditions('materials/conditions.csv')) are detected. Dynamic paths constructed at runtime cannot be resolved statically.

Source code in psychopy_bids/bids/bidshandler.py

def addConditionFiles(
    self, path: Union[str, None] = None, force: bool = False
) -> None:
    """Copy condition CSV files referenced in data.importConditions() to the BIDS /code directory.

    This method reads a PsychoPy script, detects all CSV files referenced via
    ``data.importConditions()``, and copies them into the ``/code`` directory of the BIDS
    dataset, preserving their relative path structure.

    Parameters
    ----------
    path : str, optional
        Path to the PsychoPy script to inspect. If None, the main script (``sys.argv[0]``)
        is used.
    force : bool, optional
        If True, existing files are overwritten. Default is False.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addConditionFiles(path="../tests/bids_validator/psychopy_run/validator_experiment.py", force=True)

    Notes
    -----
    Only condition files referenced with a literal string path (e.g.
    ``data.importConditions('materials/conditions.csv')``) are detected. Dynamic paths
    constructed at runtime cannot be resolved statically.
    """
    code_path, *_ = self._determineCodePath(path)
    if not code_path.exists():
        self._log("ERROR", f"Script '{code_path}' not found.")
        return

    condition_files = self._detectConditionFiles(code_path)
    if not condition_files:
        self._log("INFO", "No condition files detected in script.")
        return

    script_dir = code_path.parent
    code_dir = Path(self.dataset) / "code"
    code_dir.mkdir(parents=True, exist_ok=True)

    for csv_rel_path in condition_files:
        csv_src = script_dir / csv_rel_path
        if not csv_src.exists():
            self._log("WARN", f"Condition file '{csv_src}' not found, skipping.")
            continue
        csv_dst_dir = code_dir / Path(csv_rel_path).parent
        csv_dst_dir.mkdir(parents=True, exist_ok=True)
        self._copyItem(csv_src, csv_dst_dir, force)

addDatasetDescription(file_path=None, force=False)

Add a description to the dataset by creating dataset_description.json.

This method adds the required dataset_description.json file to the dataset.

Parameters:

Name	Type	Description	Default
file_path	str or None	Path to a custom dataset_description.json file. If None, the default template is used.	None
force	bool	Specifies whether existing files should be overwritten.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addDatasetDescription()

Notes

The file dataset_description.json is a JSON file describing the dataset. Every dataset MUST include this file. For more details, see: https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#dataset-description

Source code in psychopy_bids/bids/bidshandler.py

def addDatasetDescription(
    self, file_path: Union[str, None] = None, force: bool = False
) -> None:
    """Add a description to the dataset by creating `dataset_description.json`.

    This method adds the required `dataset_description.json` file to the dataset.

    Parameters
    ----------
    file_path : str or None, optional
        Path to a custom `dataset_description.json` file. If None, the default template is used.
    force : bool, optional
        Specifies whether existing files should be overwritten.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addDatasetDescription()

    Notes
    -----
    The file `dataset_description.json` is a JSON file describing the dataset. Every dataset
    MUST include this file. For more details, see:
    https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#dataset-description
    """
    dataset_desc = Path(self.dataset) / "dataset_description.json"
    if not force and dataset_desc.exists():
        self._log(
            "WARN",
            "File 'dataset_description.json' already exists, use force to overwrite it!",
        )
        return

    ds_info = self._loadDatasetDescriptionTemplate(file_path)
    if not file_path:
        warnings.warn(
            "[psychopy-bids(handler)] Using the default dataset_description template. "
            "Please update placeholder metadata to match your study before sharing the dataset. "
        )
    ds_info.update(
        {
            "Name": self.dataset,
            "BIDSVersion": self._getLatestBidsVersion(),
            "HEDVersion": self._getLatestHedVersion(),
            "DatasetType": "raw",
            "GeneratedBy": [
                {
                    "Name": "psychopy-bids",
                    "Version": self._getPackageVersion("psychopy-bids"),
                    "Description": "A PsychoPy plugin for working with the Brain Imaging Data Structure (BIDS).",
                    "CodeURL": "https://gitlab.com/psygraz/psychopy-bids",
                }
            ],
        }
    )

    with open(dataset_desc, "w", encoding="utf-8") as write_file:
        json.dump(ds_info, write_file, indent=4)
        write_file.write("\n")

addDirectoryStructure(force=False)

Generate a directory structure file for the PsychoPy experiment folder.

Uses the seedir package to create a human-readable text representation of the PsychoPy experiment folder (the parent of the BIDS dataset) and writes it to directory_structure.txt inside the dataset's code/ directory. The BIDS dataset folder and PsychoPy's data output folder are excluded from the tree.

Parameters:

Name	Type	Description	Default
force	bool	If True, an existing file is overwritten. Default is False.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addDirectoryStructure(force=True)

Source code in psychopy_bids/bids/bidshandler.py

def addDirectoryStructure(self, force: bool = False) -> None:
    """Generate a directory structure file for the PsychoPy experiment folder.

    Uses the ``seedir`` package to create a human-readable text representation of the
    PsychoPy experiment folder (the parent of the BIDS dataset) and writes it to
    ``directory_structure.txt`` inside the dataset's ``code/`` directory. The BIDS
    dataset folder and PsychoPy's ``data`` output folder are excluded from the tree.

    Parameters
    ----------
    force : bool, optional
        If True, an existing file is overwritten. Default is False.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addDirectoryStructure(force=True)  # doctest: +SKIP

    """
    try:
        import seedir  # pylint: disable=import-outside-toplevel
    except ImportError:
        self._log(
            "WARN",
            "'seedir' is not installed. Install it with: pip install seedir",
        )
        return

    code_dir = Path(self.dataset) / "code"
    code_dir.mkdir(parents=True, exist_ok=True)
    output_path = code_dir / "directory_structure.txt"

    if not force and output_path.exists():
        self._log(
            "WARN",
            "File 'code/directory_structure.txt' already exists, use force=True to overwrite.",
        )
        return

    experiment_dir = Path(self.dataset).parent
    bids_folder_name = Path(self.dataset).name
    structure = seedir.seedir(
        str(experiment_dir),
        style="lines",
        indent=2,
        printout=False,
        exclude_folders=[bids_folder_name, "data"],
    )
    with open(output_path, "w", encoding="utf-8") as f:
        f.write(structure)

addEnvironment(copy_wheels=True)

Generate a requirements.txt and optionally bundle wheel files.

Scans the current Python environment for installed packages and writes {dataset}/code/requirements.txt. Packages installed from local wheel files, editable installs, and local directories are annotated.

Parameters:

Name	Type	Description	Default
copy_wheels	bool	If True, copy local wheel files into {dataset}/code/wheels/ and reference them with a relative path in requirements.txt.	True

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addEnvironment()
>>> handler.addEnvironment(copy_wheels=True)

Source code in psychopy_bids/bids/bidshandler.py

def addEnvironment(self, copy_wheels: bool = True) -> None:
    """Generate a requirements.txt and optionally bundle wheel files.

    Scans the current Python environment for installed packages and writes
    ``{dataset}/code/requirements.txt``. Packages installed from local wheel
    files, editable installs, and local directories are annotated.

    Parameters
    ----------
    copy_wheels : bool
        If True, copy local wheel files into ``{dataset}/code/wheels/`` and
        reference them with a relative path in requirements.txt.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addEnvironment()
    >>> handler.addEnvironment(copy_wheels=True)
    """
    code_dir = Path(self.dataset) / "code"
    code_dir.mkdir(exist_ok=True)
    req_path = code_dir / "requirements.txt"
    wheels_dir = code_dir / "wheels" if copy_wheels else None

    env_info = BIDSHandler._collectEnvironmentInfo()

    if env_info["duplicates"]:
        self._log(
            "INFO",
            f"Detected {len(env_info['duplicates'])} packages with multiple installed versions "
            "while generating requirements.txt. Using the highest version for each package.",
        )
        duplicate_detail = "; ".join(
            f"{name} ({old_v}, {new_v}) -> {selected_v}"
            for name, old_v, new_v, selected_v in env_info["duplicates"]
        )
        self._log(
            "DEBUG", f"Resolved package version conflicts: {duplicate_detail}"
        )

    if env_info["in_conda"]:
        self._log(
            "WARNING",
            "Conda environment detected. Only pip-installed packages are captured in requirements.txt.",
        )

    BIDSHandler._writeRequirements(
        env_info, req_path, copy_wheels=copy_wheels, wheels_dir=wheels_dir
    )

addEvent(event)

Add an event or list of events.

Parameters:

Name	Type	Description	Default
event	Any or list	The event or list of events to be added to the list.	required

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset")
>>> handler.addEvent(bids.BIDSBehEvent(trial=1))
>>> handler.addEvent([bids.BIDSBehEvent(trial=2), bids.BIDSBehEvent(trial=3)])

Source code in psychopy_bids/bids/bidshandler.py

def addEvent(
    self,
    event: Union[
        BIDSBehEvent, BIDSTaskEvent, List[Union[BIDSBehEvent, BIDSTaskEvent]]
    ],
) -> None:
    """Add an event or list of events.

    Parameters
    ----------
    event : Any or list
        The event or list of events to be added to the list.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset")
    >>> handler.addEvent(bids.BIDSBehEvent(trial=1))
    >>> handler.addEvent([bids.BIDSBehEvent(trial=2), bids.BIDSBehEvent(trial=3)])
    """
    if isinstance(event, list):
        self.__events.extend(event)
    else:
        self.__events.append(event)

addLicense(identifier, force=False)

Add a license file to the dataset.

This method downloads a license with the given identifier from the SPDX license list and copies the content into the file LICENSE.

Parameters:

Name	Type	Description	Default
identifier	str	Identifier of the license.	required
force	bool	Specifies whether existing file should be overwritten.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addLicense("CC-BY-NC-4.0")

Notes

A LICENSE file MAY be provided in addition to the short specification of the used license in the dataset_description.json "License" field. The "License" field and LICENSE file MUST correspond. The LICENSE file MUST be either in ASCII or UTF-8 encoding. For more details, see: https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#license

Source code in psychopy_bids/bids/bidshandler.py

def addLicense(self, identifier: str, force: bool = False) -> None:
    """Add a license file to the dataset.

    This method downloads a license with the given identifier from the SPDX license list and
    copies the content into the file `LICENSE`.

    Parameters
    ----------
    identifier : str
        Identifier of the license.
    force : bool, optional
        Specifies whether existing file should be overwritten.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addLicense("CC-BY-NC-4.0")

    Notes
    -----
    A LICENSE file MAY be provided in addition to the short specification of the used license
    in the dataset_description.json "License" field. The "License" field and LICENSE file MUST
    correspond. The LICENSE file MUST be either in ASCII or UTF-8 encoding. For more details, see:
    https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#license
    """
    dataset_desc = Path(self.dataset) / "dataset_description.json"
    if not dataset_desc.exists():
        self.addDatasetDescription()

    self._updateDatasetDescription({"License": identifier})

    license_dest = Path(self.dataset) / "LICENSE"
    if not force and license_dest.exists():
        self._log(
            "WARN",
            "File 'LICENSE' already exists, use force for overwriting it!",
        )
    else:
        self._downloadLicense(identifier, license_dest)

addReadme(force=False)

Add a text file explaining the dataset in detail.

This method adds a README template file to the dataset, which contains the main sections needed to describe the dataset in more detail.

Parameters:

Name	Type	Description	Default
force	bool	Specifies whether existing file should be overwritten.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()
>>> handler.addReadme()

Notes

A REQUIRED text file, README, SHOULD describe the dataset in more detail. A BIDS dataset MUST NOT contain more than one README file (with or without extension) at its root directory. For more details, see: https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#readme

Source code in psychopy_bids/bids/bidshandler.py

def addReadme(self, force: bool = False) -> None:
    """Add a text file explaining the dataset in detail.

    This method adds a `README` template file to the dataset, which contains the main sections
    needed to describe the dataset in more detail.

    Parameters
    ----------
    force : bool, optional
        Specifies whether existing file should be overwritten.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    >>> handler.addReadme()

    Notes
    -----
    A REQUIRED text file, README, SHOULD describe the dataset in more detail. A BIDS dataset
    MUST NOT contain more than one README file (with or without extension) at its root
    directory. For more details, see:
    https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#readme
    """
    readme_dest = Path(self.dataset) / "README"
    if not force and readme_dest.exists():
        self._log(
            "WARN",
            "File 'README' already exists, use force for overwriting it!",
        )
    else:
        bidsdir = Path(sys.modules["psychopy_bids.bids"].__path__[0])
        readme_src = bidsdir / "template" / "README"
        shutil.copyfile(readme_src, readme_dest)
        warnings.warn(
            "[psychopy-bids(handler)] Creating README from the default template. "
            "Please customize placeholder sections to match your study before sharing the dataset."
        )

addTaskCode(path=None, force=False)

Add psychopy script or specified code directory to the BIDS /code directory.

This method copies the psychopy script or a specified folder into the /code directory of the dataset. If a path is provided, the function handles files and folders appropriately. If the path starts with "code/", this prefix is stripped only for the destination placement.

Parameters:

Name	Type	Description	Default
path	str	Path to the file or folder to copy. If None, the main script is used.	None
force	bool	If True, existing files are overwritten. Default is False.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.addTaskCode(path="../bids_validator/psychopy_run/validator_experiment.py", force=True)

Notes

The method ensures no files are overwritten unless the force parameter is set to True. If the path starts with "code/", the prefix is stripped only from the destination. If a file or directory already exists in /code, a warning is issued unless force=True.

Source code in psychopy_bids/bids/bidshandler.py

def addTaskCode(self, path: Union[str, None] = None, force: bool = False) -> None:
    """Add psychopy script or specified code directory to the BIDS /code directory.

    This method copies the psychopy script or a specified folder into the `/code` directory
    of the dataset. If a path is provided, the function handles files and folders
    appropriately. If the path starts with "code/", this prefix is stripped only for the
    destination placement.

    Parameters
    ----------
    path : str, optional
        Path to the file or folder to copy. If None, the main script is used.
    force : bool, optional
        If True, existing files are overwritten. Default is False.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.addTaskCode(path="../bids_validator/psychopy_run/validator_experiment.py", force=True)

    Notes
    -----
    The method ensures no files are overwritten unless the `force` parameter is set to True.
    If the path starts with "code/", the prefix is stripped only from the destination.
    If a file or directory already exists in `/code`, a warning is issued unless `force=True`.
    """
    code_path, psyexp_path, py_path = self._determineCodePath(path)
    code_dir = Path(self.dataset) / "code"
    code_dir.mkdir(parents=True, exist_ok=True)

    self._copyItem(code_path, code_dir, force)
    for extra in (psyexp_path, py_path):
        if extra and extra.exists():
            self._copyItem(extra, code_dir, force)

createDataset(readme=True, chg=True, lic=True, force=False)

Create the rudimentary body of a new dataset.

Parameters:

Name	Type	Description	Default
readme	bool	Specifies whether a README file should be created.	True
chg	bool	Specifies whether a CHANGES file should be created.	True
lic	bool	Specifies whether a LICENSE file should be created.	True
force	bool	Specifies whether existing files should be overwritten.	False

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> handler.createDataset()

Source code in psychopy_bids/bids/bidshandler.py

def createDataset(
    self,
    readme: bool = True,
    chg: bool = True,
    lic: bool = True,
    force: bool = False,
) -> None:
    """Create the rudimentary body of a new dataset.

    Parameters
    ----------
    readme : bool, optional
        Specifies whether a README file should be created.
    chg : bool, optional
        Specifies whether a CHANGES file should be created.
    lic : bool, optional
        Specifies whether a LICENSE file should be created.
    force : bool, optional
        Specifies whether existing files should be overwritten.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> handler.createDataset()
    """
    dataset_path = Path(self.dataset)
    if not force and dataset_path.exists():
        self._log(
            "WARN",
            f"The folder {self.dataset} already exists! Use the parameter force if you want to recreate a dataset in an existing, non-empty directory",
        )
        return

    dataset_path.mkdir(exist_ok=True)
    (dataset_path / "participants.tsv").touch()

    self.addDatasetDescription()
    if readme:
        self.addReadme(force=force)
    if chg:
        self.addChanges(changes=["Initialize the dataset"], force=force)
    if lic:
        self.addLicense(identifier="CC-BY-NC-4.0", force=force)

parseLog(file, level='BIDS', regex=None) staticmethod

Extract events from a log file.

This method parses a given log file based on the specified log level and, optionally, a regex pattern. It then processes and structures these events into a list each adhering to the BIDSTaskEvent event format.

Parameters:

Name	Type	Description	Default
file	str	The file path of the log file.	required
level	str	The level name of the bids task events.	'BIDS'
regex	str	A regular expression to parse the message string.	None

Return

events : list A list of events like presented stimuli or participant responses.

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
>>> log_events = handler.parseLog("simple1.log", "BIDS")

Source code in psychopy_bids/bids/bidshandler.py

@staticmethod
def parseLog(file, level="BIDS", regex=None) -> list:
    """Extract events from a log file.

    This method parses a given log file based on the specified log level and, optionally, a
    regex pattern. It then processes and structures these events into a list each adhering to
    the BIDSTaskEvent event format.

    Parameters
    ----------
    file : str
        The file path of the log file.
    level : str
        The level name of the bids task events.
    regex : str, optional
        A regular expression to parse the message string.

    Return
    ------
    events : list
        A list of events like presented stimuli or participant responses.

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset", subject="sub-01", task="simple")
    >>> log_events = handler.parseLog("simple1.log", "BIDS")
    """
    events = []
    try:
        with open(file, mode="r", encoding="utf-8") as log_file:
            for line in log_file:
                event = re.split(r" \t|[ ]+", line, maxsplit=2)
                if level in event:
                    entry = BIDSHandler._parseLogEntry(event, regex)
                    events.append(entry)
    except FileNotFoundError:
        warnings.warn(f"[psychopy-bids(handler)] File {file} not found!")
    return events

setLogLevel(level)

Set runtime log verbosity for psychopy-bids handler messages.

Source code in psychopy_bids/bids/bidshandler.py

def setLogLevel(self, level: Union[str, int]) -> None:
    """Set runtime log verbosity for psychopy-bids handler messages."""
    self.log_level = self._resolveLogLevel(level)

setOnsetReference(t)

Set the time reference for BIDS onset calculation.

Call this once (e.g. on receiving the MRI scanner trigger) to establish the time-zero point. All event onsets will be expressed relative to this time when the TSV file is written.

Parameters:

Name	Type	Description	Default
t	float	The reference time in seconds (typically from globalClock).	required

Examples:

>>> handler = bids.BIDSHandler(dataset="example", subject="01", task="mytask")
>>> handler._t_start is None
True
>>> handler.setOnsetReference(10.5)
>>> handler._t_start
10.5

Source code in psychopy_bids/bids/bidshandler.py

def setOnsetReference(self, t: float) -> None:
    """Set the time reference for BIDS onset calculation.

    Call this once (e.g. on receiving the MRI scanner trigger) to establish
    the time-zero point.  All event onsets will be expressed relative to
    this time when the TSV file is written.

    Parameters
    ----------
    t : float
        The reference time in seconds (typically from ``globalClock``).

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example", subject="01", task="mytask")
    >>> handler._t_start is None
    True
    >>> handler.setOnsetReference(10.5)
    >>> handler._t_start
    10.5
    """
    self._t_start = float(t)

writeEvents(participant_info, execute_sidecar=True, generate_hed_metadata=False, add_stimuli=True, event_type='both')

Writes all existing events in self.events to the dataset.

Parameters:

Name	Type	Description	Default
participant_info	dict	Key-value pairs describing participant info (e.g. age, sex, group) to be inserted into participants.tsv. A 'participant_id' key will automatically be added/updated with self.subject.	required
execute_sidecar	Union[bool, str]	If True, creates or updates a JSON sidecar file for the events file with metadata. If a string, uses the provided path to update the sidecar file.	True
generate_hed_metadata	bool	If True, automatically generates HED metadata based on the event file. Only applies if execute_sidecar is not False.	False
add_stimuli	bool	If True, copies any referenced stimuli in the event file to a /stimuli folder.	True
event_type	str	One of {'both', 'beh', 'task'}: - 'both': Writes both behavioral and task events. - 'beh': Only writes behavioral events (*_beh.tsv). - 'task': Only writes task events (*_events.tsv).	'both'

Examples:

>>> handler = bids.BIDSHandler(dataset="example_dataset")
>>> handler.addEvent(bids.BIDSBehEvent(trial=1))
>>> handler.addEvent(bids.BIDSTaskEvent(onset=1.0, duration=0.5))
>>> handler.writeEvents(participant_info={'participant_id': handler.subject}, execute_sidecar=False)

Source code in psychopy_bids/bids/bidshandler.py

def writeEvents(
    self,
    participant_info: dict,
    execute_sidecar: Union[bool, str] = True,
    generate_hed_metadata: bool = False,
    add_stimuli: bool = True,
    event_type: str = "both",
):
    """Writes all existing events in `self.events` to the dataset.

    Parameters
    ----------
    participant_info : dict
        Key-value pairs describing participant info (e.g. age, sex, group) to be inserted
        into participants.tsv. A 'participant_id' key will automatically be added/updated
        with `self.subject`.
    execute_sidecar : Union[bool, str], optional
        If True, creates or updates a JSON sidecar file for the events file with metadata.
        If a string, uses the provided path to update the sidecar file.
    generate_hed_metadata : bool, optional
        If True, automatically generates HED metadata based on the event file.
        Only applies if execute_sidecar is not False.
    add_stimuli : bool, optional
        If True, copies any referenced stimuli in the event file to a `/stimuli` folder.
    event_type : str, optional
        One of {'both', 'beh', 'task'}:
        - 'both': Writes both behavioral and task events.
        - 'beh': Only writes behavioral events (`*_beh.tsv`).
        - 'task': Only writes task events (`*_events.tsv`).

    Examples
    --------
    >>> handler = bids.BIDSHandler(dataset="example_dataset")
    >>> handler.addEvent(bids.BIDSBehEvent(trial=1))
    >>> handler.addEvent(bids.BIDSTaskEvent(onset=1.0, duration=0.5))
    >>> handler.writeEvents(participant_info={'participant_id': handler.subject}, execute_sidecar=False)
    """
    self._updateParticipantsFile(participant_info)
    if self.session:
        self._updateSessionsFile()

    bids_beh_events = [e for e in self.events if type(e) is BIDSBehEvent]
    bids_task_events = [e for e in self.events if type(e) is BIDSTaskEvent]

    if event_type == "beh":
        bids_task_events = []
    elif event_type == "task":
        bids_beh_events = []

    written_events = []
    if bids_beh_events:
        written_events.extend(
            self._writeSingleEventFile(
                bids_beh_events,
                "beh",
                execute_sidecar,
                generate_hed_metadata,
                add_stimuli,
            )
        )
    if bids_task_events:
        written_events.extend(
            self._writeSingleEventFile(
                bids_task_events,
                "events",
                execute_sidecar,
                generate_hed_metadata,
                add_stimuli,
            )
        )

    self.__events = [e for e in self.events if e not in written_events]