cobrawap_publication_code/README.md

Cobrawap Publication Code Archive

This is the code and data archive accompanying the publication

Gutzen, R., De Bonis, G., De Luca, C., Pastorelli, E., Capone, C., Allegra Mascaro, A. L., Resta, F., Manasanch, A., Pavone, F. S., Sanchez-Vives, M. V., Mattia, M., Grün, S., Paolucci, P. S., & Denker, M. (2023). "Using a modular and adaptable analysis pipeline to compare slow cerebral rhythms across heterogeneous datasets". Cell Reports Methods

The above publication also introduces the software

Collaborative Brain Wave Analysis Pipeline (Cobrawap) 0.1.0. RRID:SCR_022966. https://cobrawap.readthedocs.io. doi:10.5281/zenodo.10198749

How to reproduce the results/figures from the publication

Setup

• Setup the Python environment (conda env create -f environment.yaml) and activate it.
• Setup Cobrawap with cobrawap init and follow the instructions to
  • set the cobrawap output path (<cobrawap_output>),
  • set the cobrawap config path (<cobrawap_configs>) (see also the documentation).
• Set the local project paths in project_utils/project_paths.py.

Get the data

• Download the ECoG (IDIBAPS) and calcium imaging (LENS) datasets from the EBRAINS KnowledgeGraph:
  • IDIBAPS_WBS: doi:10.25493%2FDZWT-1T8
  • IDIBAPS_FXS: doi:10.25493/ANF9-EG3
  • IDIBAPS_PM: 10.25493/WKA8-Q4T
  • LENS_M: 10.25493/QFZK-FXS
  • LENS_ISO: 10.25493/XJR8-QCA
• Set the path parameter (DATA_SETS) in the stage01_data_entry/config/config_<profile>.yaml files to the corresponding data locations.

Run the analysis pipeline

• To produce all the possible pipeline outputs <cobrawap_output>/<profile><variant>/stage05_(channel_)wave_characterization/<event-type>_<measure-type>_measures.csv, set the event-type and measure-type accordingly and execute:

  cobrawap run --profile=<profile>
  

  Note: the folder cobrawap_output/ contains example output for the profiles IDIBAPS_WBS_WT4 and LENS_M2_t1.

Profiles: The names that are used for the individual recordings and their corresponding configurations are listed in project_utils/profiles.txt.

Variants: Variants are alternative configurations for a profile and can be specified by appending a corresponding label to the profile with a '|', e.g. <profile>|minimatrigger. Here, additional variants for spatial downsampling and alternative trigger detection are applied to all LENS datasets: |macrodim3, |macrodim5, |macrodim7, |macrodim9, |macrodim11, |minimatrigger.

Measure types: There are two alternative final stages of the pipeline stage05_wave_characterization and stage05_channel_wave_characterization, corresponding to calculating either wave-wise or channel-wise characteristic measures. You can select between them in the top-level pipeline config <cobrawap_configs>/configs/config.yaml.

Event types: The wave characterization in the pipeline output can be either given for all wavefronts or all wavemodes (wavemode = average of similar wavefronts). You can select between them by setting the parameter EVENT_NAME in the corresponding stage05 config file. Also change the prefix of the STAGE_OUTPUT accordingly as wavefronts or wavemodes.

Aggregate the output of the analysis pipeline

In the folder aggregate_pipeline_output run snakemake (snakemake -c1) to create the combined dataframes from the individual pipeline outputs:

• <event-type>_<measure-type><variant>_measures.csv containing the pipeline outputs for all profiles,
• wavefronts_<measure-type>_trend_measures.csv containing the moments of each measure for the downsampled (|macrodim) calcium imaging data,
• wavemodes_<measure-type>_avg_measures.csv containing the measures per wavefront averaged for each wavemode.

Note: the folder cobrawap_output/aggregated_output/ already contains these precomputed dataframes.

Plot the figures

In folder plot_figures:

• Run snakemake -c1 to produce Figure 5 and 6.
• Execute plot_wavemodes_dashboard.ipynb to produce Figure 4 and S3 (change profile name in notebook accordingly).
• Execute plot_trigger_detection_f-anesthesia.ipynb to produce Figure S4.
  • Note: requires running the analysis pipeline for the IDIBAPS_PM recordings, for which the pipeline output is not contained in this repository.
• Execute plot_examples_frames.ipynb to produce wave frames in Figure 2.
  • Note: to plot the ECoG waves frames data, it requires the additional pipeline run of the corresponding profile with reduced rate cobrawap run --profile=IDIBAPS_WBS_WT4|25Hz.

Note: the folder figures/ already contains these generated figures.