Welcome to Neuro-Integrative Connectivity’s documentation!¶
The Neuro-Integrative Connectivity (NIC) was developed to enable users with little computational experience to perform efficient network analysis on SEEG data to investigate epilepsy in patients. This documentation has been created to walk you through the steps necessary to calculate the supported network analysis measures and interpret the results as effortlessly as possible.
Create an Account¶
The first step is to create an account. If you are using the server edition of NIC, you will have to create an account on the signup page shown below.
Once you sign up, you will see a confirmation message like the one below.
Please wait while we verify your account. You should hear from us within a day or two. If not, please contact vxs215@case.edu.
Once your account is verified, you’ll be able to move on to the next step. You should start with Step 1: Entry of Patient Demographics.
Overview of Steps¶
Here, we will briefly outline the major steps that will be discussed in greater detail in further sections. Before these steps, we ask that you enter the patient demographics identified by the patient ID into our secure system.
Conversion from EDF-CSF Files¶
In this first step, we convert the conventional _European Data Format (EDF)_ files that you probably have to our defined _Cloudwave Signal Format (CSF)_ files.
For this step, please click Step 1: Entry of Patient Demographics.
Calculation of Coupling Measures¶
In this second step, once you have created and outputted CSF files, we can calulate coupling measures between electrodes.
For this step, please click Step 2: Conversion from EDF-CSF Files.
Calculation of Network Analysis Measures¶
In this third step, we can calculate network analysis measures from the coupled electrodes in step 3.
For this step, please click Step 3: Calculation of Coupling Measures.
Step 1: Entry of Patient Demographics¶
Once you create an account and login, you will be taken to a page where you’ll enter your patient demographics. It will look like this:
The page will guide you through the steps. There are two options that you can choose. You can start analysis about a New Patient or an Old Patient.
New Patient¶
If you select the New Patient button, you need to fill out the form and upload a discharge summary file. All fields are required. This information is stored in the database for later use. The patient ID you enter will then be automatically pre-filled in both the Conversion and Correlation steps.
Old Patient¶
If you select the Old Patient button, you will be presented with a table where you can select from all your previously entered users. The patient ID you select will then be automatically pre-filled in both the Conversion and Correlation steps.
Finally, the buttons at the bottom will allow you to move on to the next step. As the tooltip states, generally, for newly processed patient, you will need to create CSF files from EDF files before performing further analysis on them.
Step 2: Conversion from EDF-CSF Files¶
The NIC system assumes that you start with EDF files from an epilepsy patient that you have collected data for. The first step is to convert these EDF files to our defined CSF file format.
Our system only supports CSF files and we encourage their use as they provide support for human-readability and better management of your metadata (e.g. clinical seizure event annotations, EEG instrument and electrode details, study details). If you’d like to learn more information, please visit https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4360820/
This step is pretty simple. You will see a form that accepts a number of inputs described below:
Caution
This form assumes that the input EDF folder pertains to only one patient and contains both the EDF files and the clinical annotations in .txt format.
| Input | Description |
|---|---|
| Patient ID | The patient ID from the patient demographics page |
| Path to EDF Files | The path to the EDF Files. This would be the server path on NIC Server Edition and the bound container path on NIC Docker Edition (Refer to Docker documentation) |
| Output Path of CSF Files | The full path of your output CSF Files |
| Epoch Duration | The length of each fragment in your CSF file in seconds |
| Epochs Per Segment | The number of fragments to each CSF file |
Once you click Run Conversion you will be taken to a status page that looks like this:
This page will continue to update every few minutes with a status update. Eventually, you will see a popup that takes you to the next step, Calculation of Correlation Measures.
Step 3: Calculation of Coupling Measures¶
In this step, we will be calculating coupling measures between electrodes to determine any temporal correlations.
This allows us to create an adjacency matrix representation of a network graph that we can calcalate network summary statistics on. For more information regarding network graph representations, please check Network Graph Representations.
We support three different correlation measures: the linear Pearson’s Correlation, and non-linear mean phase coherence correlation, and the non-linear correlation coefficient (Pijn’s Measure).
When you get to the Correlation page, you will see the following form. This page works very similarly to the conversion page.
| Input | Description |
|---|---|
| Patient ID | The patient ID from the patient demographics page |
| Path to CSF Files | The full path to the CSF fules produced in step 1. |
| Coupling Measures | The list of coupling measures you’d like to select |
Once you have selected the location of the CSF files (for one patient), you can select as many event windows as you’d like by clicking Add Seizure Event and Remove.
| Input | Description |
|---|---|
| Event Start Time | The start time of the event |
| Event Start Time | The end time of the event |
| Lag Window | The lag window to calculate over |
| List of Channels | The list of electrodes over which you’d like to calculate correlations |
| Path to Correlation Metrics Output File | The output file path for each event (must be unique for each entry) |
Once you click Run Correlations you will be taken to a very similar screen that allows you to view your status as shown below:
Again, a popup will take you to the next step, network analysis.
Step 4: Calculation of Network Analysis Measures¶
Once we calculate our coupling measures, we can create an adjacency matrix representation to better draw conclusions about our coupled electrodes created in step 3. See more detailed information regarding these summary metrics at Summary Metrics Of Network Graphs.
You will be taken to a form that looks like the following:
| Input | Description |
|---|---|
| Name of Seizure Event | The name you’d like to output for the seizure event |
| Full Path of Correlation Metric File | This is the full path of the correlation metric file you produced in step 3. |
| Network Analysis Measures | The list of network analysis measures you’d like to calculate |
| Coupling Measures | The coupling measures you’d like to perform the network analysis on |
| Output File | This will produce a file with delimited tables for each of the network analyses and coupling measures selected. |
You will fill out the network analysis form on the left side of the page and the outputs will be displayed on the right once they are calculated. You are also able to download a text/csv version of this output for your analysis later.
Tip
Congratulations! You have successfully completed use of the NIC system.
There are a few other features such as rerunning previous runs that you should feel free to play around with.
Provenance and Run History¶
Due to the lack of scientific reproducibility in biomedicine, in general, the NIC platform has implemented several features we hope will encourage reproducible science. In addition to a PostgreSQL database that stores all inputs, we also allow the user to recreate past runs.
After you have completed a conversion and correlation run, you are able to rerun one of these runs.
Note
You will only be able to see your past runs and no one else can see your runs.
The page will look like this:
When you click either Rerun Conversion Input or Rerun Correlation Inputs, you will be taken back to those respective pages with the forms automatically populated with that run’s data. Then you can follow the process described in steps 2 or 3.
Setting up NIC on Docker¶
Documentation coming soon!
Installing Docker¶
Documentation coming soon!
Opening Kitematic (Optional)¶
Documentation coming soon!
Pulling the NIC Container¶
Documentation coming soon!
Running the System¶
Documentation coming soon!
Additional Computational Background¶
Here is some background on the computational methods implemented by our system so that you can better interpret your results.
Documentation coming soon!
Network Graph Representations¶
There are a number of ways to represent a network graph.
Documentation coming soon!
Summary Metrics Of Network Graphs¶
Documentation coming soon!
How to Use NIC and this Documentation¶
There are two editions of the NIC system.
- NIC Server Edition (at https://bmhinformatics.case.edu/nicworkflow)
The Server Edition is only for use with data on the CWRU servers in the Population and Quantitative Health Sciences department and UH Epilepsy Center.
- NIC Docker Container (at https://hub.docker.com/r/vsocrates/nicworkflow)
The Docker Container can be downloaded from the public repository and run on any platform with your own data. Additional instructions can be found at Setting up NIC on Docker.