hypline 0.1.0__tar.gz

hypline-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Create cache key
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Cache build files
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Publish docs to gh-pages
+        run: |
+          cd docs
+          mkdocs gh-deploy --force

hypline-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

hypline-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

hypline-0.1.0/LICENSE

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

hypline-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: hypline
+Version: 0.1.0
+Summary: Data Cleaning and Analysis Pipeline for Hyperscanning Research
+Project-URL: Repository, https://github.com/princeton-ddss/hypline
+Project-URL: Documentation, https://princeton-ddss.github.io/hypline/
+Author-email: Sangyoon Park <datumvitae@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: dill>=0.3.9
+Requires-Dist: natsort>=8.4.0
+Requires-Dist: nibabel>=5.3.2
+Requires-Dist: nilearn>=0.11.1
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: polars>=1.26.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.15.2
+Description-Content-Type: text/markdown
+
+# Hypline
+
+Hypline is a Python package that provides a CLI tool for cleaning and analyzing data from hyperscanning studies involving dyadic conversations.
+
+## Installation
+
+Hypline can be installed using `pip`:
+
+```bash
+pip install hypline
+```
+
+It can also be installed using other package managers such as [`uv`](https://docs.astral.sh/uv/) and [`poetry`](https://python-poetry.org/docs/).
+
+## Quick Start
+
+Once the package is installed, `hypline` command will be available, like so:
+
+```bash
+hypline --help
+```
+
+Running the above will display an overview of the tool, including supported subcommands.
+
+For instance, `clean` is a subcommand for performing confound regression to clean BOLD outputs from [fMRIPrep](https://fmriprep.org/en/stable/index.html), and its details can be viewed by running:
+
+```bash
+hypline clean --help
+```
+
+## What Next
+
+If you want to learn more about Hypline, please check out the official project [documentation](https://princeton-ddss.github.io/hypline/).

hypline-0.1.0/README.md

@@ -0,0 +1,33 @@
+# Hypline
+
+Hypline is a Python package that provides a CLI tool for cleaning and analyzing data from hyperscanning studies involving dyadic conversations.
+
+## Installation
+
+Hypline can be installed using `pip`:
+
+```bash
+pip install hypline
+```
+
+It can also be installed using other package managers such as [`uv`](https://docs.astral.sh/uv/) and [`poetry`](https://python-poetry.org/docs/).
+
+## Quick Start
+
+Once the package is installed, `hypline` command will be available, like so:
+
+```bash
+hypline --help
+```
+
+Running the above will display an overview of the tool, including supported subcommands.
+
+For instance, `clean` is a subcommand for performing confound regression to clean BOLD outputs from [fMRIPrep](https://fmriprep.org/en/stable/index.html), and its details can be viewed by running:
+
+```bash
+hypline clean --help
+```
+
+## What Next
+
+If you want to learn more about Hypline, please check out the official project [documentation](https://princeton-ddss.github.io/hypline/).

hypline-0.1.0/docs/mkdocs/guides/clean.md

@@ -0,0 +1,188 @@
+# Cleaning BOLD Data
+
+## Overview
+
+Hypline supports confound regression to clean BOLD outputs from [fMRIPrep](https://fmriprep.org/en/stable/index.html).
+
+Specifically, the `clean` subcommand supports this, and its details can be checked by running:
+
+```bash
+hypline clean --help
+```
+
+The `clean` subcommand takes in three required arguments:
+
+| Argument        | Description                                                  |
+| --------------- | ------------------------------------------------------------ |
+| `fmriprep_dir`  | Directory containing fMRIPrep outputs                        |
+| `config_file`   | Configuration file containing model specs, etc.              |
+| `model_name`    | Confound regression model to run (defined in configuration)  |
+
+and several options:
+
+| Option                    | Description                             | Default                   |
+| ------------------------- | --------------------------------------- | ------------------------- |
+| `--output-dir`            | Directory to store cleaned BOLD data    | `<fmriprep_dir>_cleaned`  |
+| `--custom-confounds-dir`  | Directory containing custom confounds   | None                      |
+| `--session-name`          | Target session name                     | All                       |
+| `--task-name`             | Target task name                        | All                       |
+| `--data-space-name`       | Target BOLD data space                  | `MNI152NLin2009cAsym`     |
+| `--n-processes`           | Number of processes to run in parallel  | `1`                       |
+
+## Example
+
+For illustration, consider we have the fMRIPrep outputs stored in the following location:
+
+``` hl_lines="3-6"
+data/
+└── derivatives/
+    └── fmriprep/
+        ├── logs/
+        ├── sub-003/
+        └── ...
+```
+
+### Setting up configuration
+
+We can start by defining the desired confound regression model(s) in the configuration file, like so:
+
+```yaml title="config.yaml"
+model_specs:
+
+  default:
+    confounds:
+      - "trans_x"
+      - "trans_y"
+      - "trans_z"
+      - "rot_x"
+      - "rot_y"
+      - "rot_z"
+      - "cosine"
+    aCompCor:
+      - n_comps: 5
+        tissue: "CSF"
+      - n_comps: 5
+        tissue: "WM"
+
+  default_task:
+    confounds:
+      - "trans_x"
+      - "trans_y"
+      - "trans_z"
+      - "rot_x"
+      - "rot_y"
+      - "rot_z"
+      - "cosine"
+    custom_confounds:
+      - "trial_boxcar"
+      - "prompt_boxcar"
+      - "speech_boxcar"
+      - "listen_boxcar"
+      - "button_press"
+      - "receive_press"
+      - "screen_change"
+    aCompCor:
+      - n_comps: 5
+        tissue: "CSF"
+      - n_comps: 5
+        tissue: "WM"
+```
+
+We can store the configuration file anywhere we want. Let's say we stored it as follows:
+
+``` hl_lines="3-4"
+data/
+└── derivatives/
+    ├── hypline/
+    │   └── config.yaml
+    └── fmriprep/
+        ├── logs/
+        ├── sub-003/
+        └── ...
+```
+
+### Using custom confounds
+
+If the model involves custom confounds, we should provide the data as subject-level TSV files that each contain a given subject’s confound values per TR. Hence, each TSV file will be a tabular data of shape $n \times m$, where $n$ equals the number of total TRs in a run and $m$ equals the number of custom confounds. With the current directory structure, we may prepare custom confounds as follows:
+
+``` hl_lines="5-9"
+data/
+└── derivatives/
+    ├── hypline/
+    │   ├── config.yaml
+    │   └── custom_confounds/
+    │       ├── sub-003/ses-1/func/
+    │       │   ├── sub-003_ses-1_task-Conv_run-1_desc-customConfounds_timeseries.tsv
+    │       │   └── ...
+    │       └── ...
+    │
+    └── fmriprep/
+        ├── logs/
+        ├── sub-003/ses-1/func/
+        │   ├── sub-003_ses-1_task-Conv_run-1_desc-confounds_timeseries.tsv
+        │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-L_bold.func.gii
+        │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-R_bold.func.gii
+        │   └── ...
+        └── ...
+```
+
+!!! note
+
+    The custom confound TSV file should have the same name as its corresponding standard confound TSV file, except for the description (i.e., `desc` entity).
+
+### Running the command
+
+With this setup, we can run the following to clean surface-level BOLD data for all subjects:
+
+```bash
+hypline clean \
+  data/derivatives/fmriprep/ \
+  data/derivatives/hypline/config.yml \
+  default_task \
+  --custom-confounds-dir  data/derivatives/hypline/custom_confounds/ \
+  --data-space fsaverage6
+  --n-processes 8
+```
+
+Note that we are here leveraging multiprocessing (i.e., 8 parallel processes) to speed up the cleaning.
+
+### Outputs
+
+The cleaned data will then be stored in the designated location[^1] as follows:
+
+``` hl_lines="20-28"
+data/
+└── derivatives/
+    ├── hypline/
+    │   ├── config.yaml
+    │   └── custom_confounds/ses-1/func/
+    │       ├── sub-003/
+    │       │   ├── sub-003_ses-1_task-Conv_run-1_desc-customConfounds_timeseries.tsv
+    │       │   └── ...
+    │       └── ...
+    │
+    ├── fmriprep/
+    │   ├── logs/
+    │   ├── sub-003/ses-1/func/
+    │   │   ├── sub-003_ses-1_task-Conv_run-1_desc-confounds_timeseries.tsv
+    │   │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-L_bold.func.gii
+    │   │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-R_bold.func.gii
+    │   │   └── ...
+    │   └── ...
+    │
+    └── fmriprep_cleaned/
+        ├── logs/
+        │   ├── sub-003.log
+        │   └── ...
+        ├── sub-003/ses-1/func/
+        │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-L_desc-clean_bold.func.gii
+        │   ├── sub-003_ses-1_task-Conv_run-1_space-fsaverage6_hemi-R_desc-clean_bold.func.gii
+        │   └── ...
+        └── ...
+```
+
+As shown above, the cleaned data files will be of the same format as their corresponding originals. In fact, their data dimension and other metadata will be the same as the originals, with the only difference being values in the data.
+
+Note that log files are automatically generated to record the details of the cleaning process, which will be useful for reproducibility.
+
+[^1]: In this case, the default value (`<fmriprep_dir>_cleaned`) is used because the given command does not explicitly specify the output directory (`--output-dir`).

hypline-0.1.0/docs/mkdocs/index.md

@@ -0,0 +1,45 @@
+# Welcome to Hypline
+
+Hypline is a Python package that provides a CLI tool for cleaning and analyzing data from hyperscanning studies involving dyadic conversations.
+
+## Installation
+
+Hypline can be installed using `pip` or other package managers such as [`uv`](https://docs.astral.sh/uv/) and [`poetry`](https://python-poetry.org/docs/).
+
+=== "pip"
+
+    ```bash
+    pip install hypline
+    ```
+
+=== "uv"
+
+    ```bash
+    uv add hypline
+    ```
+
+=== "poetry"
+
+    ```bash
+    poetry add hypline
+    ```
+
+## Quick Start
+
+Once the package is installed, `hypline` command will be available, like so:
+
+```bash
+hypline --help
+```
+
+Running the above will display an overview of the tool, including supported subcommands.
+
+For instance, `clean` is a subcommand for performing confound regression to clean BOLD outputs from [fMRIPrep](https://fmriprep.org/en/stable/index.html), and its details can be viewed by running:
+
+```bash
+hypline clean --help
+```
+
+## What Next
+
+Please check out user [guides](guides/clean.md) for more detailed instructions and examples.

hypline-0.1.0/docs/mkdocs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+    tex: {
+      inlineMath: [["\\(", "\\)"]],
+      displayMath: [["\\[", "\\]"]],
+      processEscapes: true,
+      processEnvironments: true
+    },
+    options: {
+      ignoreHtmlClass: ".*|",
+      processHtmlClass: "arithmatex"
+    }
+  };
+
+  document$.subscribe(() => {
+    MathJax.startup.output.clearCache()
+    MathJax.typesetClear()
+    MathJax.texReset()
+    MathJax.typesetPromise()
+  })

hypline-0.1.0/docs/mkdocs.yml

@@ -0,0 +1,58 @@
+docs_dir: mkdocs
+site_name: Hypline
+repo_name: princeton-ddss/hypline
+repo_url: https://github.com/princeton-ddss/hypline
+copyright: Copyright © 2025 The Trustees of Princeton University
+
+theme:
+  name: material
+  # logo: images/logo.png
+  # favicon: images/favicon.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.annotate
+    - content.code.copy
+    - header.autohide
+    - navigation.instant
+    - navigation.tabs
+    - navigation.top
+    - navigation.footer
+    - search.highlight
+    - search.suggest
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Guides:
+    - Cleaning BOLD Data: guides/clean.md

hypline-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "hypline"
+version = "0.1.0"
+description = "Data Cleaning and Analysis Pipeline for Hyperscanning Research"
+readme = "README.md"
+authors = [
+    { name = "Sangyoon Park", email = "datumvitae@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "dill>=0.3.9",
+    "natsort>=8.4.0",
+    "nibabel>=5.3.2",
+    "nilearn>=0.11.1",
+    "numpy>=2.2.4",
+    "polars>=1.26.0",
+    "pydantic>=2.10.6",
+    "pyyaml>=6.0.2",
+    "rich>=14.0.0",
+    "typer>=0.15.2",
+]
+
+[project.urls]
+Repository = "https://github.com/princeton-ddss/hypline"
+Documentation = "https://princeton-ddss.github.io/hypline/"
+
+[project.scripts]
+hypline = "hypline:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.6.11",
+]

hypline-0.1.0/src/hypline/__init__.py

@@ -0,0 +1,5 @@
+from .cli import app
+
+
+def main():
+    app()

hypline-0.1.0/src/hypline/cli.py

@@ -0,0 +1,122 @@
+import multiprocessing as mp
+from pathlib import Path
+
+import typer
+from rich import print
+from typing_extensions import Annotated
+
+from .regression import ConfoundRegression
+from .utils import DillProcess
+
+app = typer.Typer()
+
+
+@app.command()
+def clean(
+    fmriprep_dir: Annotated[
+        str,
+        typer.Argument(
+            help="Directory containing fMRIPrep outputs",
+            show_default=False,
+        ),
+    ],
+    config_file: Annotated[
+        str,
+        typer.Argument(
+            help="Configuration file",
+            show_default=False,
+        ),
+    ],
+    model_name: Annotated[
+        str,
+        typer.Argument(
+            help="Confound regression model to run (defined in config)",
+            show_default=False,
+        ),
+    ],
+    output_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Directory to store cleaned BOLD data",
+            show_default="<fmriprep_dir>_cleaned",
+        ),
+    ] = None,
+    custom_confounds_dir: Annotated[
+        str | None,
+        typer.Option(help="Directory containing custom confounds"),
+    ] = None,
+    session_name: Annotated[
+        str,
+        typer.Option(
+            help="Target session name",
+            show_default="all",
+        ),
+    ] = "*",
+    task_name: Annotated[
+        str,
+        typer.Option(
+            help="Target task name",
+            show_default="all",
+        ),
+    ] = "*",
+    data_space_name: Annotated[
+        str,
+        typer.Option(help="Target BOLD data space"),
+    ] = "MNI152NLin2009cAsym",
+    n_processes: Annotated[
+        int,
+        typer.Option(help="Number of processes to run in parallel"),
+    ] = 1,
+):
+    """
+    Clean BOLD data for all subjects in the given fMRIPrep outputs.
+    """
+    subject_ids = [
+        path.name[4:] for path in Path(fmriprep_dir).glob("sub-*") if path.is_dir()
+    ]
+
+    def clean_bold(subject_ids: list[str]):
+        reg = ConfoundRegression(
+            config_file=config_file,
+            fmriprep_dir=fmriprep_dir,
+            output_dir=output_dir,
+            custom_confounds_dir=custom_confounds_dir,
+        )
+
+        reg.clean_bold(
+            model_name=model_name,
+            subject_ids=subject_ids,
+            session_name=session_name,
+            task_name=task_name,
+            data_space_name=data_space_name,
+        )
+
+    if n_processes < 2:
+        clean_bold(subject_ids)
+    else:
+        if mp.current_process().name == "MainProcess":
+            max_processes = mp.cpu_count()
+            if n_processes > max_processes:
+                n_processes = max_processes
+                print(
+                    "[bold yellow]Warning:[/bold yellow] "
+                    "Requested processes exceed available CPU "
+                    "cores. Resetting to match available cores."
+                )
+
+            processes: list[DillProcess] = []
+            for i in range(n_processes):
+                p = DillProcess(target=clean_bold, args=(subject_ids[i::n_processes],))
+                processes.append(p)
+                p.start()
+            for p in processes:
+                p.join()
+
+
+@app.callback()
+def callback():
+    """
+    An opinionated framework/toolbox for conducting
+    data cleaning and analysis in hyperscanning studies
+    involving dyadic conversations.
+    """

hypline-0.1.0/src/hypline/enums.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class CompCorMethod(Enum):
+    ANATOMICAL = "aCompCor"
+    TEMPORAL = "tCompCor"
+    MEAN = "Mean"
+
+
+class CompCorTissue(Enum):
+    CSF = "CSF"
+    WM = "WM"
+    COMBINED = "combined"
+
+
+class SurfaceSpace(Enum):
+    FS_AVERAGE_5 = "fsaverage5"
+    FS_AVERAGE_6 = "fsaverage6"
+
+
+class VolumeSpace(Enum):
+    MNI_152_NLIN_6_ASYM = "MNI152NLin6Asym"
+    MNI_152_NLIN_2009_C_ASYM = "MNI152NLin2009cAsym"