This Notebook tests whether your cedalion installation is working

Everything that is specific to the installation of Cedalion can be found on our documentation page: https://doc.ibs.tu-berlin.de/cedalion/doc/dev

It is assumed that you already followed the steps below:

• Have the conda package manager installed, either by installing Anaconda or Miniconda.

• Clone the Cedalion repository from github to your local disk. The main branch is the release branch.

• In your IDE, switch to the Cedalion folder as your local working folder or “add to path”.

• In its Python terminal create a conda environment with the necessary dependencies by running:

$ conda env create -n cedalion -f environment_dev.yml

• This installs all relevant dependencies and creates an environment in which you can run the toolbox. It also includes Jupyter Notebook to run the example notebooks.

• Afterwards activate the environment and add an editable install of Cedalion to it:

$ conda activate cedalion
$ pip install -e .

If creating the environment is slow:

• To create the environment conda needs to find a set of packages that fulfills all requirements. If conda needs too much time to find a solution, there are two ways to speed it up.

• Install libmamba-solver and configure conda to use it. (recommended )

• If you have a recent conda version (23.10 or later), libmamba is already preconfigured. Otherwise update:

$ conda update -n base conda

# This cells setups the environment when executed in Google Colab.
try:
    import google.colab
    !curl -s https://raw.githubusercontent.com/ibs-lab/cedalion/dev/scripts/colab_setup.py -o colab_setup.py
    # Select branch with --branch "branch name" (default is "dev")
    %run colab_setup.py
except ImportError:
    pass

Import Cedalion Dependencies

If you get an error here, revisit the setup above.

import cedalion
import cedalion.datasets
import cedalion.plots

Download datasets

These will be cached and are used by amongst others by the example notebooks.

• Image Reconstruction

• Photogrammetric Coregistration

Depending on your operating system the user cache directory is one of these:

• Mac: ~/Library/Caches/cedalion

• Unix: ~/.cache/cedalion

• Windows: C:\Users\<user>\AppData\Local\cedalion\cedalion\Cache

It is safe to delete the downloaded files, if they are not needed anymore. During a new run of the example notebooks they are downloaded again.

# loads finger tapping data with sparse probe
rec = cedalion.datasets.get_fingertapping()
display(rec)

<Recording |  timeseries: ['amp'],  masks: [],  stim: ['1.0', '15.0', '2.0', '3.0'],  aux_ts: [],  aux_obj: []>

# loads finger tapping data with high density probe
rec = cedalion.datasets.get_fingertappingDOT()
display(rec)

<Recording |  timeseries: ['amp'],  masks: [],  stim: ['1', '2', '3', '4', '5'],  aux_ts: ['ACCEL_X_1', 'ACCEL_Y_1', 'ACCEL_Z_1', 'GYRO_X_1', 'GYRO_Y_1', 'GYRO_Z_1', 'ExGa1', 'ExGa2', 'ExGa3', 'ExGa4', 'ECG', 'Respiration', 'PPG', 'SpO2', 'Heartrate', 'GSR', 'Temperature'],  aux_obj: []>

cedalion.datasets.get_colin27_segmentation()

('/home/runner/.cache/cedalion/v25.1.0/colin27_segmentation.zip.unzip/colin27_segmentation',
 {'csf': 'mask_csf.nii',
  'gm': 'mask_gray.nii',
  'scalp': 'mask_skin.nii',
  'skull': 'mask_bone.nii',
  'wm': 'mask_white.nii'},
 'landmarks.mrk.json')

Adot = cedalion.datasets.get_precomputed_sensitivity("fingertappingDOT", "colin27")
display(Adot)

<xarray.DataArray (channel: 100, vertex: 25052, wavelength: 2)> Size: 40MB
array([[[1.21179827e-17, 1.21179827e-17],
        [3.96194809e-20, 3.96194809e-20],
        [4.10971853e-19, 4.10971853e-19],
        ...,
        [3.50555240e-12, 3.50555240e-12],
        [5.26119937e-13, 5.26119937e-13],
        [8.08679933e-13, 8.08679933e-13]],

       [[7.61680927e-18, 7.61680927e-18],
        [1.23019221e-18, 1.23019221e-18],
        [1.67531031e-19, 1.67531031e-19],
        ...,
        [2.33481439e-12, 2.33481439e-12],
        [4.92126651e-13, 4.92126651e-13],
        [1.07023130e-12, 1.07023130e-12]],

       [[5.52717640e-17, 5.52717640e-17],
        [1.78701021e-18, 1.78701021e-18],
        [6.99671883e-18, 6.99671883e-18],
        ...,
...
        ...,
        [5.98963847e-19, 5.98963847e-19],
        [6.62891414e-18, 6.62891414e-18],
        [1.28914788e-15, 1.28914788e-15]],

       [[3.15260006e-12, 3.15260006e-12],
        [8.79590880e-12, 8.79590880e-12],
        [1.06539458e-11, 1.06539458e-11],
        ...,
        [3.80802873e-19, 3.80802873e-19],
        [1.03147281e-16, 1.03147281e-16],
        [2.13242570e-16, 2.13242570e-16]],

       [[2.51903559e-12, 2.51903559e-12],
        [6.00967488e-12, 6.00967488e-12],
        [1.87582313e-12, 1.87582313e-12],
        ...,
        [2.80353969e-20, 2.80353969e-20],
        [1.96006079e-18, 1.96006079e-18],
        [3.81463022e-16, 3.81463022e-16]]], shape=(100, 25052, 2))
Coordinates:
    parcel      (vertex) object 200kB 'VisCent_ExStr_8_LH' ... 'scalp'
    is_brain    (vertex) bool 25kB True True True True ... False False False
  * channel     (channel) object 800B 'S1D1' 'S1D2' 'S1D4' ... 'S14D31' 'S14D32'
    source      (channel) object 800B 'S1' 'S1' 'S1' 'S1' ... 'S14' 'S14' 'S14'
    detector    (channel) object 800B 'D1' 'D2' 'D4' 'D5' ... 'D29' 'D31' 'D32'
  * wavelength  (wavelength) float64 16B 760.0 850.0
Dimensions without coordinates: vertex
Attributes:
    units:    mm

xarray.DataArray

• channel: 100
• vertex: 25052
• wavelength: 2

• 1.212e-17 1.212e-17 3.962e-20 ... 1.96e-18 3.815e-16 3.815e-16

  array([[[1.21179827e-17, 1.21179827e-17],
          [3.96194809e-20, 3.96194809e-20],
          [4.10971853e-19, 4.10971853e-19],
          ...,
          [3.50555240e-12, 3.50555240e-12],
          [5.26119937e-13, 5.26119937e-13],
          [8.08679933e-13, 8.08679933e-13]],
  
         [[7.61680927e-18, 7.61680927e-18],
          [1.23019221e-18, 1.23019221e-18],
          [1.67531031e-19, 1.67531031e-19],
          ...,
          [2.33481439e-12, 2.33481439e-12],
          [4.92126651e-13, 4.92126651e-13],
          [1.07023130e-12, 1.07023130e-12]],
  
         [[5.52717640e-17, 5.52717640e-17],
          [1.78701021e-18, 1.78701021e-18],
          [6.99671883e-18, 6.99671883e-18],
          ...,
  ...
          ...,
          [5.98963847e-19, 5.98963847e-19],
          [6.62891414e-18, 6.62891414e-18],
          [1.28914788e-15, 1.28914788e-15]],
  
         [[3.15260006e-12, 3.15260006e-12],
          [8.79590880e-12, 8.79590880e-12],
          [1.06539458e-11, 1.06539458e-11],
          ...,
          [3.80802873e-19, 3.80802873e-19],
          [1.03147281e-16, 1.03147281e-16],
          [2.13242570e-16, 2.13242570e-16]],
  
         [[2.51903559e-12, 2.51903559e-12],
          [6.00967488e-12, 6.00967488e-12],
          [1.87582313e-12, 1.87582313e-12],
          ...,
          [2.80353969e-20, 2.80353969e-20],
          [1.96006079e-18, 1.96006079e-18],
          [3.81463022e-16, 3.81463022e-16]]], shape=(100, 25052, 2))

• Coordinates: (6)
  • parcel
    (vertex)
    object
    'VisCent_ExStr_8_LH' ... 'scalp'

    array(['VisCent_ExStr_8_LH', 'VisCent_ExStr_8_LH', 'VisCent_Striate_2_LH',
           ..., 'scalp', 'scalp', 'scalp'], shape=(25052,), dtype=object)

  • is_brain
    (vertex)
    bool
    True True True ... False False

    array([ True,  True,  True, ..., False, False, False], shape=(25052,))

  • channel
    (channel)
    object
    'S1D1' 'S1D2' ... 'S14D31' 'S14D32'

    array(['S1D1', 'S1D2', 'S1D4', 'S1D5', 'S1D6', 'S1D8', 'S2D2', 'S2D3', 'S2D5',
           'S2D6', 'S2D7', 'S2D9', 'S3D1', 'S3D4', 'S3D5', 'S3D8', 'S3D10',
           'S3D11', 'S3D14', 'S4D2', 'S4D4', 'S4D5', 'S4D6', 'S4D7', 'S4D8',
           'S4D9', 'S4D10', 'S4D11', 'S4D12', 'S4D13', 'S4D15', 'S5D3', 'S5D6',
           'S5D7', 'S5D9', 'S5D12', 'S5D13', 'S5D16', 'S6D8', 'S6D10', 'S6D11',
           'S6D12', 'S6D14', 'S6D15', 'S7D9', 'S7D11', 'S7D12', 'S7D13', 'S7D15',
           'S7D16', 'S8D17', 'S8D18', 'S8D20', 'S8D21', 'S8D22', 'S8D24', 'S9D18',
           'S9D19', 'S9D21', 'S9D22', 'S9D23', 'S9D25', 'S10D17', 'S10D20',
           'S10D21', 'S10D24', 'S10D26', 'S10D27', 'S10D30', 'S11D18', 'S11D20',
           'S11D21', 'S11D22', 'S11D23', 'S11D24', 'S11D25', 'S11D26', 'S11D27',
           'S11D28', 'S11D29', 'S11D31', 'S12D19', 'S12D22', 'S12D23', 'S12D25',
           'S12D28', 'S12D29', 'S12D32', 'S13D24', 'S13D26', 'S13D27', 'S13D28',
           'S13D30', 'S13D31', 'S14D25', 'S14D27', 'S14D28', 'S14D29', 'S14D31',
           'S14D32'], dtype=object)

  • source
    (channel)
    object
    'S1' 'S1' 'S1' ... 'S14' 'S14'

    array(['S1', 'S1', 'S1', 'S1', 'S1', 'S1', 'S2', 'S2', 'S2', 'S2', 'S2',
           'S2', 'S3', 'S3', 'S3', 'S3', 'S3', 'S3', 'S3', 'S4', 'S4', 'S4',
           'S4', 'S4', 'S4', 'S4', 'S4', 'S4', 'S4', 'S4', 'S4', 'S5', 'S5',
           'S5', 'S5', 'S5', 'S5', 'S5', 'S6', 'S6', 'S6', 'S6', 'S6', 'S6',
           'S7', 'S7', 'S7', 'S7', 'S7', 'S7', 'S8', 'S8', 'S8', 'S8', 'S8',
           'S8', 'S9', 'S9', 'S9', 'S9', 'S9', 'S9', 'S10', 'S10', 'S10',
           'S10', 'S10', 'S10', 'S10', 'S11', 'S11', 'S11', 'S11', 'S11',
           'S11', 'S11', 'S11', 'S11', 'S11', 'S11', 'S11', 'S12', 'S12',
           'S12', 'S12', 'S12', 'S12', 'S12', 'S13', 'S13', 'S13', 'S13',
           'S13', 'S13', 'S14', 'S14', 'S14', 'S14', 'S14', 'S14'],
          dtype=object)

  • detector
    (channel)
    object
    'D1' 'D2' 'D4' ... 'D31' 'D32'

    array(['D1', 'D2', 'D4', 'D5', 'D6', 'D8', 'D2', 'D3', 'D5', 'D6', 'D7',
           'D9', 'D1', 'D4', 'D5', 'D8', 'D10', 'D11', 'D14', 'D2', 'D4',
           'D5', 'D6', 'D7', 'D8', 'D9', 'D10', 'D11', 'D12', 'D13', 'D15',
           'D3', 'D6', 'D7', 'D9', 'D12', 'D13', 'D16', 'D8', 'D10', 'D11',
           'D12', 'D14', 'D15', 'D9', 'D11', 'D12', 'D13', 'D15', 'D16',
           'D17', 'D18', 'D20', 'D21', 'D22', 'D24', 'D18', 'D19', 'D21',
           'D22', 'D23', 'D25', 'D17', 'D20', 'D21', 'D24', 'D26', 'D27',
           'D30', 'D18', 'D20', 'D21', 'D22', 'D23', 'D24', 'D25', 'D26',
           'D27', 'D28', 'D29', 'D31', 'D19', 'D22', 'D23', 'D25', 'D28',
           'D29', 'D32', 'D24', 'D26', 'D27', 'D28', 'D30', 'D31', 'D25',
           'D27', 'D28', 'D29', 'D31', 'D32'], dtype=object)

  • wavelength
    (wavelength)
    float64
    760.0 850.0

    array([760., 850.])

• Indexes: (2)
  • channel
    PandasIndex

    PandasIndex(Index(['S1D1', 'S1D2', 'S1D4', 'S1D5', 'S1D6', 'S1D8', 'S2D2', 'S2D3', 'S2D5',
           'S2D6', 'S2D7', 'S2D9', 'S3D1', 'S3D4', 'S3D5', 'S3D8', 'S3D10',
           'S3D11', 'S3D14', 'S4D2', 'S4D4', 'S4D5', 'S4D6', 'S4D7', 'S4D8',
           'S4D9', 'S4D10', 'S4D11', 'S4D12', 'S4D13', 'S4D15', 'S5D3', 'S5D6',
           'S5D7', 'S5D9', 'S5D12', 'S5D13', 'S5D16', 'S6D8', 'S6D10', 'S6D11',
           'S6D12', 'S6D14', 'S6D15', 'S7D9', 'S7D11', 'S7D12', 'S7D13', 'S7D15',
           'S7D16', 'S8D17', 'S8D18', 'S8D20', 'S8D21', 'S8D22', 'S8D24', 'S9D18',
           'S9D19', 'S9D21', 'S9D22', 'S9D23', 'S9D25', 'S10D17', 'S10D20',
           'S10D21', 'S10D24', 'S10D26', 'S10D27', 'S10D30', 'S11D18', 'S11D20',
           'S11D21', 'S11D22', 'S11D23', 'S11D24', 'S11D25', 'S11D26', 'S11D27',
           'S11D28', 'S11D29', 'S11D31', 'S12D19', 'S12D22', 'S12D23', 'S12D25',
           'S12D28', 'S12D29', 'S12D32', 'S13D24', 'S13D26', 'S13D27', 'S13D28',
           'S13D30', 'S13D31', 'S14D25', 'S14D27', 'S14D28', 'S14D29', 'S14D31',
           'S14D32'],
          dtype='object', name='channel'))

  • wavelength
    PandasIndex

    PandasIndex(Index([760.0, 850.0], dtype='float64', name='wavelength'))

• Attributes: (1)

  units :

  mm

# loads photogrammetry scan example
fname_scan, fname_snirf,fname_montage = cedalion.datasets.get_photogrammetry_example_scan()
s = cedalion.io.read_einstar_obj(fname_scan)

Optional: Plot a 3D scan with Pyvista

Note: If you run into problems here this will not be due to a faulty Cedalion installation, but your Pyvista setup

# plot the scan
import pyvista as pv
pv.set_jupyter_backend("static") # use "client" for interactive rendering
plt = pv.Plotter()
cedalion.plots.plot_surface(plt, s, opacity=1.0)
plt.show()

If you run into trouble you can get help by the community

Visit the Cedalion forum on openfnirs.org/community/cedalion and particularly the thread for installing cedalion