Feature fNIRS hyperscanning (#226)

fNIRS hyperscanning features:

* group recordings in dyads
* group dyads in a study
* use WTC for coherence
* plot intra/inter subject coherence
* plot connectogram
* coherence as time series
* coherence by region of interest
* export coherence metrics as pandas dataframe
* one shiny dashboard for wavelet exploration
* one shiny dashboard for hyperscanning study exploration
* load already preprocessed fNIRS data or use a basic preprocessor

Author: patricefortin

.gitignore

@@ -136,4 +136,8 @@ _build/
 
 # Ignore Mac DS_Store files
 .DS_Store
-**/.DS_Store
+**/.DS_Store
+
+# Preprocessed and results data
+data/results/
+private/

README.md

@@ -4,7 +4,7 @@ The **Hy**perscanning **Py**thon **P**ipeline
 
 [![PyPI version shields.io](https://img.shields.io/pypi/v/hypyp.svg)](https://pypi.org/project/HyPyP/) [![CI](https://github.com/ppsp-team/HyPyP/actions/workflows/Build.yml/badge.svg)](https://github.com/ppsp-team/HyPyP/actions/workflows/Build.yml) <a href="https://hypyp.readthedocs.io"><img src="https://readthedocs.org/projects/hypyp/badge/?version=latest"></a> [![license](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Mattermost](https://img.shields.io/discord/1065810348944408616?color=blue)](https://discord.gg/zYzjeGj7D6)
 
-⚠️ This software is in beta and thus should be considered with caution. While we have done our best to test all the functionalities, there is no guarantee that the pipeline is entirely bug-free. 
+⚠️ This software is in beta and thus should be considered with caution. While we have done our best to test all the functionalities, there is no guarantee that the pipeline is entirely bug-free.
 
 📖 See our [paper](https://academic.oup.com/scan/advance-article/doi/10.1093/scan/nsaa141/5919711) for more explanation and our plan for upcoming functionalities (aka Roadmap).
 
@@ -13,14 +13,14 @@ The **Hy**perscanning **Py**thon **P**ipeline
 🤓 For the motivated contributors, you can even help directly in the development of HyPyP. You will need to install [Poetry](https://python-poetry.org/) (see section below).
 
 ## Contributors
+
 Original authors: Florence BRUN, Anaël AYROLLES, Phoebe CHEN, Amir DJALOVSKI, Yann BEAUXIS, Suzanne DIKKER, Guillaume DUMAS  
 New contributors: Marine Gautier MARTINS, Rémy RAMADOUR, Patrice FORTIN, Ghazaleh RANJBARAN, Quentin MOREAU, Caitriona DOUGLAS, Franck PORTEOUS, Jonas MAGO, Juan C. AVENDANO, Julie BONNAIRE
 
 ## Installation
 
 `pip install HyPyP`
 
-
 ## Documentation
 
 HyPyP documentation of all the API functions is available online at [hypyp.readthedocs.io](https://hypyp.readthedocs.io/)
@@ -43,11 +43,20 @@ For getting started with HyPyP, we have designed a little walkthrough: [getting_
 
 🎓 [Tutorials](https://github.com/ppsp-team/HyPyP/tree/master/tutorial) - Examples & documentation (Anaël, Florence, Yann, Ghazaleh, Caitriona, Guillaume)
 
+## fNIRS hyperscanning
+
+🔦 [fnirs/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/fnirs) — Functional Near Infrared Spectroscopy hyperscanning features (Patrice)
+
+🌊 [wavelet/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/wavelet) — Continuous Wavelet Transform and Wavelet Transform Coherence (Patrice)
+
+📊 [shiny/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/app) — Shiny dashboards, install using `poetry install --extras shiny` (Patrice)
+
 ## Poetry Installation (Only for Developers and Adventurous Users)
 
 To develop HyPyP, we recommend using [Poetry 2.x](https://python-poetry.org/). Follow these steps:
 
 ### 1. Install Poetry:
+
 ```bash
    pip install poetry
 ```
@@ -73,6 +82,7 @@ poetry install --with dev
 ```
 
 ### 4. Launch Jupyter Lab to Run Notebooks:
+
 Instead of entering a shell, launch Jupyter Lab directly within the Poetry environment:
 
 ```bash
@@ -111,10 +121,12 @@ As of version 0.5.0b5, hypyp now supports visualization of parent-child or adult
 To use this functionality, simply set the `children=True` parameter in visualization functions and specify which participant is the child using the `child_head` parameter.
 
 Example:
+
 ```python
 # Visualize parent-child data (epo1 = parent, epo2 = child)
 viz_3D_inter(epo1, epo2, C, threshold=0.95, steps=10, children=True, child_head=True)
 ```
 
 # License
+
 This project is licensed under the BSD 3-Clause License. See the license for details.

dashboards/run-shiny-study-viewer.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")"
+cd ..
+
+shiny run hypyp/shiny/study_viewer.py --reload --host 0.0.0.0 --port 8001
+

dashboards/run-shiny-wavelet-explorer.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")"
+cd ..
+
+shiny run hypyp/shiny/wavelet_explorer.py --reload --host 0.0.0.0 --port 8000
+

data/FNIRS/DCARE_02_sub1.snirf data/NIRS/DCARE_02_sub1.snirfdata/FNIRS/DCARE_02_sub1.snirf renamed to data/NIRS/DCARE_02_sub1.snirf

@@ -0,0 +1,51 @@
+1,1,2,-59.589,60.168,-4.362,36.0,-48.397,53.595,-3.640
+2,1,3,-63.186,56.591,-18.141,30.5,-50.213,49.385,-13.146
+3,1,4,-70.017,43.913,-18.167,60.3,-54.884,39.019,-12.881
+4,1,9,-30.160,84.531,-12.342,59.3,-24.948,68.494,-8.425
+5,2,1,-18.354,83.517,24.189,39.1,-15.289,69.407,18.903
+6,2,2,-52.105,65.735,13.046,41.9,-43.323,57.220,11.174
+7,2,9,-18.177,86.630,4.132,44.3,-16.246,73.086,3.451
+8,3,1,-15.190,75.206,45.743,45.3,-10.724,61.013,36.471
+9,3,2,-50.770,57.978,35.587,60.0,-42.166,49.318,28.033
+10,4,2,-72.412,34.597,14.859,34.1,-59.347,30.002,13.237
+11,4,3,-74.924,30.775,-0.144,45.5,-59.197,28.910,2.306
+12,4,4,-78.803,16.889,0.924,37.5,-61.706,11.719,5.411
+13,4,5,-81.342,2.605,21.617,34.0,-66.735,-2.042,21.018
+14,5,3,-79.144,14.004,-17.001,60.9,-62.770,4.267,-18.239
+15,5,4,-82.152,-0.704,-17.684,30.6,-68.519,-6.250,-17.471
+16,5,5,-85.287,-14.179,3.539,41.1,-71.139,-16.615,3.790
+17,5,7,-87.447,-30.648,-14.486,30.4,-71.878,-29.085,-13.310
+18,6,5,-85.028,-29.926,25.727,33.6,-70.249,-29.517,25.781
+19,6,6,-78.594,-47.958,46.962,40.1,-66.061,-44.683,41.730
+20,6,7,-83.896,-46.505,6.450,40.8,-70.708,-44.929,4.667
+21,6,8,-77.374,-64.104,26.858,33.6,-64.798,-57.811,25.338
+22,7,7,-79.372,-61.256,-10.554,31.4,-67.051,-55.811,-8.560
+23,7,8,-72.834,-77.390,8.481,33.5,-60.527,-68.587,7.722
+24,8,6,-65.587,-64.985,61.605,36.4,-54.221,-59.265,51.918
+25,8,8,-65.270,-80.772,41.942,33.2,-53.237,-72.288,37.074
+26,9,9,29.767,84.573,-11.278,58.3,24.176,69.371,-7.719
+27,9,10,59.018,60.776,-3.202,35.5,48.699,53.534,-2.917
+28,9,11,62.819,57.261,-18.622,30.0,50.231,49.039,-13.444
+29,9,12,70.344,43.115,-17.403,59.4,54.996,39.185,-12.562
+30,10,1,18.291,83.473,24.403,38.7,15.082,69.478,18.810
+31,10,9,17.831,86.686,3.610,43.9,16.506,73.218,3.487
+32,10,10,51.371,66.117,14.439,41.2,42.576,57.797,11.904
+33,10,11,56.230,63.966,-1.296,60.6,46.677,56.527,-1.044
+34,11,1,15.300,75.099,45.855,44.9,10.965,60.522,37.243
+35,11,10,49.862,58.910,35.785,59.6,41.139,49.871,28.325
+36,12,10,72.157,35.093,15.105,33.7,59.275,30.339,13.621
+37,12,11,74.451,32.220,-0.202,45.1,59.194,30.549,2.685
+38,12,12,78.527,18.038,1.437,37.3,61.691,13.172,6.356
+39,12,13,80.866,4.380,23.264,33.4,66.287,1.652,21.358
+40,13,11,79.111,14.306,-17.266,59.8,61.789,4.977,-17.612
+41,13,12,81.902,0.854,-15.968,30.0,68.127,-4.878,-17.109
+42,13,13,85.078,-12.698,4.825,41.1,70.959,-15.756,3.812
+43,13,15,86.471,-30.117,-13.132,31.0,71.939,-28.479,-12.700
+44,14,13,84.951,-28.595,27.436,34.3,70.241,-28.296,27.273
+45,14,14,78.473,-47.501,47.691,40.3,66.074,-44.187,42.081
+46,14,15,83.928,-46.190,8.435,40.9,70.328,-44.159,7.384
+47,14,16,78.121,-62.051,27.562,33.9,65.312,-56.526,25.661
+48,15,15,79.743,-60.240,-9.105,31.7,67.228,-55.810,-7.129
+49,15,16,73.274,-76.332,9.546,33.6,61.114,-67.834,8.169
+50,16,14,65.533,-64.259,62.278,36.6,54.451,-58.185,52.283
+51,16,16,66.047,-79.714,41.904,33.4,53.553,-71.577,37.290