Version 70.1 by denker on 2020/05/02 16:46
Hide last authors
robing 1.1 1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
debonisg 50.1 5 = (% style="--darkreader-inline-color:inherit; color:inherit" %)Slow Wave Analysis Pipeline (SWAP)(%%) =
robing 1.1 6
denker 22.2 7 (% class="wikigeneratedid" id="HUseCaseSGA2-SP3-002:IntegratingmultiscaledataA0inareproducibleandadaptablepipeline" %)
debonisg 50.1 8 (% style="--darkreader-inline-color:inherit; color:inherit; font-size:24px" %)**Use Case SGA2-SP3-002 KR3.2: Integrating multi-scale data and the output of simulations in a reproducible and adaptable pipeline**
denker 25.1 9
debonisg 50.1 10 Robin Gutzen^^1^^, Giulia De Bonis^^2^^, Elena Pastorelli^^2,3^^, Cristiano Capone^^2^^,
denker 25.1 11
debonisg 50.1 12 Chiara De Luca^^2,3^^, Michael Denker^^1^^, Sonja Grün^^1^^,
denker 25.1 13
debonisg 50.1 14 Pier Stanislao Paolucci^^2^^, Andrew Davison^^4^^
denker 25.1 15
debonisg 50.1 16 Experiments: Anna Letizia Allegra Mascaro^^5,6^^, Francesco Resta^^5^^, Francesco Saverio Pavone^^5^^, Maria-Victoria Sanchez-Vives^^7,8^^
denker 41.2 17
denker 25.1 18 ,,1) Institute of Neuroscience and Medicine (INM-6) and Institute for Advanced Simulation (IAS-6) and JARA-Institute Brain Structure-Function Relationships (INM-10), Jülich Research Centre, Jülich, Germany,,
19
debonisg 50.1 20 ,,2) Istituto Nazionale di Fisica Nucleare (INFN), Sezione di Roma, Rome, Italy,,
denker 25.1 21
debonisg 50.1 22 ,,3) Ph.D. Program in Behavioural Neuroscience, “Sapienza” University of Rome, Rome, Italy,,
denker 41.2 23
debonisg 50.1 24 ,,4) Unité de Neurosciences, Information et Complexité, Neuroinformatics Group, CNRS FRE 3693, Gif-sur-Yvette, France,,
denker 41.2 25
robing 59.1 26 ,,5) European Laboratory for Non-linear Spectroscopy (LENS), (% style="--darkreader-inline-color:inherit; color:inherit" %)University of Florence, Florence, Italy(%%),,
debonisg 50.1 27
28 ,,6) Istituto di Neuroscienze, CNR, Pisa, Italy,,
29
30 ,,7) Institut d’Investigacions Biomèdiques August Pi i Sunyer (IDIBAPS), Barcelona, Spain,,
31
32 ,,8) Institució Catalana de Recerca i Estudis Avanc ̨ats (ICREA), Barcelona, Spain,,
robing 1.1 33 )))
34 )))
35
36 (% class="row" %)
37 (((
38 (% class="col-xs-12 col-sm-8" %)
39 (((
denker 23.1 40 == Flexible workflows to generate multi-scale analysis scenarios ==
robing 1.1 41
robing 39.1 42 This Collab is aimed at experimental and computational neuroscientists interested in the usage of the [[Neo>>https://neo.readthedocs.io/en/stable/]] and [[Elephant>>https://elephant.readthedocs.io/en/latest/]] tools in performing data analysis of spiking data.
pierstanpaolucci 57.2 43 Here, the collab illustrates the tool usage with regards to the SGA2-SP3-UC002 KR3.2, investigating sleep, anesthesia, and the transition to wakefulness: see Chapter 1 and Figure 2  of SGA2[[ Deliverable D3.2.1.>>https://drive.ebrains.eu/smart-link/17ac0d6e-e050-4a49-8ca2-e223b70a3121/]], for an overview of the scientific motivations and a description of the UseCase workflow; Chapter 2 (same document) for an introduction to KR3.2; Chapter 3, for a description of the mice ECoG data sets; Chapter 5, about the Slow Wave Analysis Pipeline and Chapter 6 for the mice wide-field GECI data)
robing 1.1 44
robing 51.1 45 [[image:https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png||height="35" width="35"]][[INM-6/wavescalephant>>https://github.com/INM-6/wavescalephant]]
46
robing 61.1 47 == How the pipeline works ==
robing 36.1 48
robing 39.1 49 The design of the pipeline aims at interfacing a variety of general and specific analysis and processing steps in a flexible modular manner. Hence, it enables the pipeline to adapt to diverse types of data (e.g., electrical ECoG, or optical Calcium Imaging recordings) and to different analysis questions. This makes the analyses a) more reproducible and b) comparable amongst each other since they rely on the same stack of algorithms and any differences in the analysis are fully transparent.
debonisg 57.3 50 The individual processing and analysis steps (**blocks**//, //see// //the arrow-connected elements below) are organized in sequential **stages**// (//see the columns below//). //Following along the stages, the analysis becomes more specific but also allows to branch off at after any stage, as each stage yields useful intermediate results and is autonomous so that it can be reused and recombined. Within each stage, there is a collection of blocks from which the user can select and arrange the analysis via a config file. Thus, the pipeline can be thought of as a curated database of methods on which an analysis can be constructed by drawing a path along the blocks and stages.
robing 36.1 51
robing 37.1 52 (% class="wikigeneratedid" id="H" %)
53 [[image:pipeline_flowchart.png]]
robing 36.1 54
robing 10.1 55 == Executing the pipeline ==
robing 6.1 56
debonisg 57.3 57 There are two ways of getting started and testing the pipeline, i) online using the collab drive and jupyter hub, or ii) downloading the code and data from GitHub and the collab storage and running it locally.
robing 8.1 58
robing 38.1 59 === i) In the collab ===
60
robing 36.1 61 * (((
robing 38.1 62 **Copy the collab drive to your personal drive space**
robing 36.1 63
robing 38.1 64 * Open the Drive from the left menu
robing 40.1 65 * Select the folders //pipeline// and //datasets,//
denker 41.1 66 and the notebook// run_snakemake_in_collab.ipynb//
robing 36.1 67 * Select 'Copy', and then 'My Library' from the dropdown 'Other Libraries'
robing 19.1 68
robing 36.1 69 )))
robing 19.1 70 * **Start a Jupyter Hub instance **
robing 38.1 71 In another browser tab, open [[https:~~/~~/lab.ebrains.eu>>https://lab.ebrains.eu]]
robing 40.1 72
robing 10.1 73 * **Edit the config files**
robing 64.1 74 Each stage has config files (//pipeline/<stage_name>/configs/config_<profile>.yaml//) to specify which analysis/processing blocks to execute and which parameters to use. General and specific information about the blocks and parameters can be found in the README and config files of each stage. There are preset configuration profiles for the benchmark datasets IDIBAPS ([[ECoG, anesthetized mouse>>https://kg.ebrains.eu/search/?facet_type[0]=Dataset&q=sanchez-vives#Dataset/2ead029b-bba5-4611-b957-bb6feb631396]]) and LENS ([[Calcium Imaging, anesthetized mouse>>https://kg.ebrains.eu/search/instances/Dataset/71285966-8381-48f7-bd4d-f7a66afa9d79]]).
robing 10.1 75
robing 20.1 76 * **Run the notebook**
robing 38.1 77 In the jupyter hub, navigate to //drive/My Libraries/My Library/pipeline/showcase_notebooks/run_snakemake_in_collab.ipynb//, or where you copied the //pipeline// folder to.
robing 65.1 78 Follow the notebook to install the required packages into your Python kernel, set the output path, and execute the pipeline with snakemake
robing 10.1 79
robing 38.1 80 === ii) Local execution ===
robing 10.1 81
82 * **Get the code**
robing 64.1 83 The source code of the pipeline is available via Github: [[INM-6/wavescalephant>>https://github.com/INM-6/wavescalephant]] and can be cloned to your machine ([[how to get started with Github>>https://guides.github.com/activities/hello-world/]]).
robing 10.1 84
robing 38.1 85 * (((
86 **Build the Python environment**
robing 64.1 87 In the wavescalephant git repository, there is an environment file ([[pipeline/environment.yaml>>https://drive.ebrains.eu/smart-link/1a0b15bb-be87-46ee-b838-4734bc320d20/]]) specifying the required packages and versions. To build the environment, we recommend using conda ([[how to get started with conda>>https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html]]).
88 ##conda env create ~-~-file environment.yaml
89 conda activate wavescalephant_env##
robing 10.1 90
robing 38.1 91 )))
robing 10.1 92 * **Edit the settings**
robing 51.1 93 The settings file specifies the path to the output folder, where results are saved to. Open the template file //[[pipeline/settings_template.py>>https://drive.ebrains.eu/lib/905d7321-a16b-4147-8cca-31d710d1f946/file/pipeline/settings_template.py]]//, set the ##output_path## to the desired path, and save it as //pipeline/settings.py//.
robing 10.1 94
95 * **Edit the config files**
robing 64.1 96 Each stage uses a config file to specify which analysis/processing blocks to execute and which parameters to use. Edit the config template files //pipeline/stageXX_<stage_name>/configs/config_template.yaml// according to your dataset and analysis goal, and save them as //pipeline/stageXX_<stage_name>/configs/config_<profile>.yaml//. A detailed description of the available parameter settings and their meaning is commented in the template files, and a more general description of the working mechanism of each stage can be found in the respective README file //pipeline/stageXX_<stage_name>/README.md//.
robing 38.1 97 //Links are view-only//
robing 52.1 98 ** full pipeline: [[README.md>>https://drive.ebrains.eu/smart-link/d2e93a2a-09f6-4dce-982d-0370953a4da8/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/7948fbb3-bf8a-4785-9b28-d5c15a1aafa7/]]
robing 64.1 99 ** stage01_data_entry: [[README.md>>https://drive.ebrains.eu/smart-link/896f8880-a7d1-4a30-adbf-98759860fed5/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/9bef8f59-1007-48c4-b5ba-30de4ff18f34/]]
100 ** stage02_processing: [[README.md>>https://drive.ebrains.eu/smart-link/01f21fa5-94f7-4883-8388-cc50957f9c81/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/7e75caf6-e2d6-4393-a97c-4f481c908cf8/]]
101 ** stage03_trigger_detection: [[README.md>>https://drive.ebrains.eu/smart-link/18d276cd-a691-4ee1-81c6-7978cef9c1b4/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/dfa375c0-cc80-4f95-b3ed-40140acbd96b/]]
102 ** stage04_wavefront_detection: [[README.md>>https://drive.ebrains.eu/smart-link/a8e80096-06a0-4ff4-b645-90e134e46ac5/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/3a54be8c-b9f4-4698-a85d-6ad97990b40a/]]
103 ** stage05_wave_characterization: [[README.md>>https://drive.ebrains.eu/smart-link/3009a214-a11f-424c-8a6e-13e7506545eb/]], [[config.yaml>>https://drive.ebrains.eu/smart-link/83f68955-0ca8-4123-9734-6e93349ca3e3/]]
robing 10.1 104
105 * **Enter a dataset**
robing 38.1 106 There are two test datasets in the collab drive (IDIBAPS and LENS) for which there are also corresponding config files and scripts in the data_entry stage. So, these datasets are ready to be used and analyzed.
robing 52.1 107 For adding new datasets see //[[pipeline/stage01_data_entry/README.md>>https://drive.ebrains.eu/smart-link/d2e93a2a-09f6-4dce-982d-0370953a4da8/]]//
robing 10.1 108
109 * **Run the pipeline (-stages)**
robing 64.1 110 To run the pipeline with [[snakemake>>https://snakemake.readthedocs.io/en/stable/]]), activate the Python environment ##conda activate wavescalephant_env,## make sure you are in the working directory (//pipeline/)//, and call ##snakemake## to run the entire pipeline.
111 For a more detailed executed guide and how to execute individual stages and blocks see the pipeline [[Readme>>https://drive.ebrains.eu/smart-link/3009a214-a11f-424c-8a6e-13e7506545eb/]].
robing 10.1 112
113 == Accessing and using the results ==
114
robing 38.1 115 All results are stored in the path specified in the //settings.py// file. The folder structure reflects the structuring of the pipeline into stages and blocks. All intermediate results are stored as //.nix// files using the [[Neo data format>>https://neo.readthedocs.io/en/stable/]] and can be loaded with ##neo.NixIO('/path/to/file.nix').read_block()##. Additionally, most blocks produce a figure, and each stage a report file, to give an overview of the execution log, parameters, intermediate results, and to help with debugging. The final stage (//stage05_wave_characterization//) stores the results as[[ //pandas.DataFrames//>>https://pandas.pydata.org/]] in //.csv// files, separately for each measure as well as in a combined dataframe for all measures.
robing 10.1 116
robing 65.1 117 == Outlook ==
118
119 * Using the **KnowledgeGraph API **to insert data directly from the Knowledge Graph into the pipeline and also register and store the corresponding results as Analysis Objects. Such Analysis Objects are to incorporate **Provenance Tracking, **using [[fairgraph>>https://github.com/HumanBrainProject/fairgraph]],** **to record the details of the processing and analysis steps.
120 * Adding support for the pipeline to make use of **HPC** resources when running on the collab.
121 * Further extending the available **methods** to address a wider variety of analysis objectives and support the processing of other datatypes. Additional documentation and guides should also make it easier for non-developers to contribute new method blocks.
122 * Extending the **application** of the pipeline to the analysis of other types of activity waves and oscillations.
123 * Integrating and co-developing new features of the underlying **software tools **[[Elephant>>https://elephant.readthedocs.io/en/latest/]], [[Neo>>https://neo.readthedocs.io/en/stable/]], [[Nix>>https://github.com/G-Node/nix]], [[Snakemake>>https://snakemake.readthedocs.io/en/stable/]].
124
robing 10.1 125 == References ==
126
robing 59.1 127 * [[Celotto, Marco, et al. "Analysis and Model of Cortical Slow Waves Acquired with Optical Techniques." //Methods and Protocols// 3.1 (2020): 14.>>https://doi.org/10.3390/mps3010014]]
128 * [[De Bonis, Giulia, et al. "Analysis pipeline for extracting features of cortical slow oscillations." //Frontiers in Systems Neuroscience// 13 (2019): 70.>>https://doi.org/10.3389/fnsys.2019.00070]]
129 * [[Resta, F., Allegra Mascaro, A. L., & Pavone, F. (2020). "Study of Slow Waves (SWs) propagation through wide-field calcium imaging of the right cortical hemisphere of GCaMP6f mice" //EBRAINS//>>https://doi.org/10.25493/3E6Y-E8G]]// //
robing 62.1 130 * [[Sanchez-Vives, M. (2020). "Propagation modes of slow waves in mouse cortex".  //EBRAINS//>>https://doi.org/10.25493/WKA8-Q4T]]
robing 63.1 131 * [[Sanchez-Vives, M. (2019). "Cortical activity features in transgenic mouse models of cognitive deficits (Fragile X Syndrome).//" EBRAINS//>>https://doi.org/10.25493/ANF9-EG3]]
robing 10.1 132
denker 70.1 133 == License ==
denker 22.1 134
denker 70.1 135 Text is licensed under the Creative Commons CC-BY 4.0 license. LENS data is licensed under the Creative Commons CC-BY-NC-ND 4.0 license. IDIBAPS data is licensed under the Creative Commons CC-BY-NC-SA 4.0 license. Software code is licensed under GNU General Public License v3.0.
denker 22.1 136
denker 29.1 137 [[image:https://i.creativecommons.org/l/by/4.0/88x31.png||style="float:left"]]
138
denker 70.1 139 [[image:https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png||alt="https://i.creativecommons.org/l/by/4.0/88x31.png" style="float:left"]]
denker 33.1 140
denker 70.1 141 [[image:https://licensebuttons.net/l/by-nc-nd/4.0/88x31.png||alt="https://i.creativecommons.org/l/by/4.0/88x31.png" style="float:left"]]
142
143
robing 10.1 144 == Acknowledgments ==
145
denker 22.1 146 This open source software code was developed in part or in whole in the Human Brain Project, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 785907 (Human Brain Project SGA2).
denker 33.1 147
148
149 [[image:logos_sga2_sp3_uc002.png||alt="Logos SP3 Use Case 2"]]
robing 1.1 150 )))
151
152
robing 67.1 153 == ==
robing 36.1 154
robing 1.1 155 (% class="col-xs-12 col-sm-4" %)
156 (((
157 {{box title="**Contents**"}}
robing 68.1 158 {{toc depth="3"/}}
robing 1.1 159 {{/box}}
160
161
162 )))
163 )))