Getting Started

Our video tutorial covers all the content in this page, plus explanations of how ASCENT works! See it below:

Installation

Installing commercial software

In ASCENT, all programs/commands are run from a command line environment (Bash terminal for macOS/Linux, Powershell for Windows). It is highly recommended that you install the package management system Miniconda or Anaconda (if using macOS, choose .pkg for ease of use). However, advanced users who wish to use another Python distribution may.

First, these software packages must be manually installed:

  • Miniconda/Anaconda We recommend that you install Miniconda (Miniconda is a stripped down version of Anaconda; Anaconda is optional for intermediate users). If you already have an existing installation, there is no need to reinstall.

    • Recommended: Select add to path

    • Recommended: Select “Install for individual user”

  • Java SE Development Kit 8 (1.8) (need to register for a free account)

    • If your COMSOL version is 6.0 or newer, you may instead install Java 11.

  • COMSOL Multiphysics 5.4 or newer (requires purchase of license; only base package needed, which includes the COMSOL Java API)

    • Once COMSOL is installed, alter ‘File System Access’ permissions via File → Preferences → Security → Methods and Java Libraries → File System Access → All Files.

  • NEURON 7.6.7 or newer (newer versions have been released, but compatibility has yet to be confirmed; choose appropriate installer depending on operating system; install auxiliary software as prompted by NEURON installer)

    • Depending on your operating system, some additional dependencies may be required. Make sure to follow the installation instructions carefully.

    • NEURON must be in your PATH in order to run simulations. Either choose the add to path option during installation, or on Linux, you can add to your bash profile: export PATH=<path/to/neuron/>:$PATH. The NEURON path should end with bin.

Users may also download a text editor or integrated development environment (IDE) of their choosing to view/edit code (e.g., Atom, Visual Studio Code, IntelliJ IDEA). For Java code, full autocomplete functionality requires adding both the path to the COMSOL installation ending in plugins as well as the path <ASCENT_PATH>/bin/json-20190722.jar to the list of available libraries (usually from within the IDE’s project settings). To run code in your IDE, newer version of COMSOL may also require you to check the box File>Preferences>Security>Methods and Java Libraries>Allow access to network sockets.

Installing ASCENT

  1. First, download or clone the SPARC ASCENT pipeline from GitHub to a desired location that will be referenced in step 3. Downloading is a much simpler process than cloning via Git, but does not easily allow for you to get the most recent updates/bug fixes, nor does it allow you to suggest new features/changes. If you are interested in either of these features, you should clone via Git rather than downloading.

    • Downloading: Click the download button on GitHub and choose the location to which you would like to save. Note that you will need to extract the files, as they will be downloaded in a compressed format. When presented with a choice of compression format, “.zip” is a safe choice that most computers will be able to extract.

    • Cloning via Git:

      1. You must first have an account with GitHub, and if you have been granted special permissions to the code repository, you must use the email address to which those permissions were granted.

      2. If you have not already done so, add an SSH key to your account (see instructions for GitHub). This is a required standard authentication method.

      3. In a Miniconda (or Git, for advanced users) command line environment, navigate to the location to where you would like to clone the code repository (see instructions for navigating the file system from the command line for Mac or Linux and Windows).

      4. Clone the repository (see instructions for GitHub).

      5. For more information on using Git, check out the official documentation.

  2. Next, install ASCENT dependencies:

    • Windows: Open the Anaconda Powershell Prompt from the Windows Start Menu as Administrator, and use cd to navigate to the root directory of the pipeline. Then, run python run install.

      Caution

      If reinstalling ASCENT after having changed your Anaconda/Miniconda installation, it may be necessary to delete the #region conda initialize block from C:\Users\<username>\Documents\WindowsPowerShell\profile.ps1 in order to use Anaconda Powershell Prompt.

    • MacOS/Linux: Open Anaconda Prompt and use cd to navigate to the root directory of the pipeline. Then, run python run install.

    • For advanced users using their own (non-conda) Python distribution:

      • From the ascent root directory execute python run install --no-conda

      • From the ascent root directory execute pip install -r requirements.txt

      • This method is highly discouraged as newer versions of packages/Python could potentially break ASCENT or introduce unexpected bugs

After confirming that you are in the correct directory, the script will install the required Python packages.

  1. Then, configure the environment variables. This step may be completed several ways, described below.

    • Recommended Setup: Open Anaconda prompt, navigate to the ASCENT root directory, and execute python run env_setup. You will be prompted for the following paths:

      • ASCENT_COMSOL_PATH: Path to the COMSOL installation, ending in the directory name “Multiphysics”, as seen in the template and JSON Overview.

      • ASCENT_JDK_PATH: Path to the JDK 1.8 installation, ending in bin, as seen in the template and JSON Overview. Hint: This is the correct path if the directory contains many executables (for Windows: java.exe, etc.; MacOS/Linux: java, etc.).

      • ASCENT_PROJECT_PATH: Path to the root directory of the pipeline, as chosen for step 1.

      • ASCENT_NSIM_EXPORT_PATH: Path to the export location for NEURON “simulation” directories. This path only depends on the user’s desired file system organization.

    • Manual Setup: Copy the file config/templates/env.json into config/system/env.json (new file). This file holds important paths for software used by the pipeline (see env.json in Enums and JSON Overview). Then, edit each of the four values as specified below. Use \\ in Windows and / in macOS/Linux operating systems. Note that the file separators are operating system dependent, so even if you installed in step 2 with Unix-like command environment on a Windows machine (e.g., using Git Bash, Cygwin, or a VM with Ubuntu), you will still need to choose the proper file separator for Windows, i.e., \\). See example env.json files for both macOS and Windows (Environment Parameters).

    • Automatic setup: Upon the initiation of your first run, you will be prompted to enter the above four paths if you did not choose to complete the manual setup. Enter them as prompted, following the guidelines detailed above and exemplified in JSON Overview. Note that you may at any time update paths with python run env_setup to rewrite this file if the information should change.

Metadata required to model an in vivo experiment using the ASCENT pipeline

Note

All metadata required for the tutorial run are provided with ASCENT.

  1. Detailed specifications / dimensions of the stimulating cuff electrode.

  2. Transverse cross-section of the nerve where the cuff is placed, stained to visualize the different tissue types (e.g., using Masson’s trichrome), with a scale bar (Fig 2 and Morphology Inputs)) or known scale (micrometers/pixel). Different possible sources for defining the nerve sample morphology include:

    a. For best specificity, the nerve would be sampled from the specific animal used in the experiment being modeled. In this case, two colors of tissue dye may be used on the ventral and medial aspects of the nerve to maintain orientation information.

    b. Otherwise, a sample from another animal of the same species could be used at the correct nerve level.

    c. If multiple samples from other animals are available, they could be used to generate a representative nerve model, knowing the range of morphological metrics across individuals using the scripts/mock_morphology_generator.py script (Mock Morphology).

    d. Lastly, published data could be used.

  3. Orientation and rotation of the cuff on the nerve (e.g., cuff closure on the ventral side of the nerve).

  4. Fiber diameters

    a. Distributions of fiber diameters may be obtained from literature; otherwise, detailed electromicroscopic studies are required.

    b. The fiber diameters found in the target nerve that will be simulated in NEURON. All diameters or a subset of diameters may be of interest.

    c. Each fiber diameter of interest can be simulated for each fiber location of interest, or specific fiber diameters can be simulated in specific locations.

  5. Approximate tissue or fluids surrounding the nerve and cuff (e.g., muscle, fat, or saline).

  6. Stimulation waveforms, pulse widths, and other parameters of the electrical signal.

  7. If comparing to neural recordings: distance between the stimulation and recording cuffs.

  8. If comparing to functional recordings (e.g., EMG): distance from the stimulation cuff to the location where the nerve inserts into the muscle.

Setting up a run of ASCENT

How to run the ASCENT tutorial, after completing the initial setup.

Overview

Follow the instructions below and verify the threshold value to familiarize yourself with the ASCENT code and documentation.

We provide segmented histology of a rat cervical vagus nerve. Use the provided histology and configurations files to simulate activation thresholds in response to a charge balanced, biphasic pulse (PW1 = 100 μs, interphase gap of 100 μs, PW2 = 400 μs) using Purdue’s bipolar cuff design.

  • MRG 8.7 μm diameter fibers

  • Fibers placed in nerve cross-section using a 6 spoke wheel with 2 fibers per spoke

  • Custom material for surrounding medium with isotropic conductivity 1/20 [S/m]

After your thresholds have been computed, build a heatmap for the thresholds at each fiber location.

Through this exercise, you will:

  • Set up nerve morphology masks

  • Define model with a custom material

  • Build and solve a finite element model

  • Define placement of fibers in the nerve cross-section

  • Simulate activation thresholds for a specific fiber model using a custom waveform

  • Generate a heatmap of fiber activation thresholds

Step-by-step instructions

Note

For this tutorial, use the files provided in the examples/tutorial/ directory. The below example directory structure may be helpful.

Example directory structure

tutorial directory structure

  1. Input Masks: Create the directory input/tutorial/. Place the masks (.tif images) from examples/tutorial/ here

    Important

    In steps 2-5, you can choose any number for sample_index, model_index, sim_index, and run_index. However, the instructions here assume you chose 0 for all of these indices.

  2. Sample: Create the directory samples/<sample_index>/. Copy sample.json from examples/tutorial/ to the folder you just created (e.g. samples/0/).

  3. Model: Create the directory samples/<sample_index>/models/<model_index>/. Copy model.json from examples/tutorial/ to the folder you just created (e.g. samples/0/models/0/).

  4. Sim: Copy sim.json from examples/tutorial/ to config/user/sims/ and rename the file to <sim_index>.json.

  5. Run: Copy run.json from config/templates/ to config/user/runs/ and rename the file to <run_index>.json. Open the file and edit your sample, model, and sim indices to match the ones you chose above.

  6. Run the pipeline with the commandpython run pipeline <run_index> (e.g. python run pipeline 0). The pipeline will generate ready-to-run NEURON simulations and export them to the "ASCENT_NSIM_EXPORT_PATH" defined during installation.

  7. Run the NEURON simulations by navigating to the your "ASCENT_NSIM_EXPORT_PATH" and running the command python submit.py <run_index>. This may take some time.

  8. After the NEURON simulations have completed, move the outputs back to the ASCENT directory structure by running the command python run import_n_sims <run_index>.

    Check

    Threshold for inner0_fiber0 (samples/<sample_index>/models/<model_index>/sims/<sim_index>/n_sims/data/outputs/thresh_inner0_fiber0.dat) should be -0.027402 mA

  9. To generate a heatmap of activation thresholds, open the script examples/analysis/threshold_heatmap.py and edit the sample, model, and sim indices to match the ones you chose above. Run the script from the repository root with the command python examples/analysis/threshold_heatmap.py, and a heatmap plot will be generated in output/analysis/. Your heatmap should look like the one below. tutorial directory structure

How to run the ASCENT pipeline, after completing the initial setup.

_images/pipeline_requirements.png

Overview of the requirements to run the ASCENT pipeline.

To set up a run of the pipeline, you must provide binary mask inputs for the nerve and save Sample (i.e., sample.json), Model(s) (i.e., model.json), and Sim(s) (i.e., sim.json) JSON configurations in directories, relative to the project path defined in config/system/env.json. The directory names must use indices that are consistent with the indices of Sample, Model(s), and Sim(s) defined in Run.

  1. Masks: Populate input/<NAME>/ (e.g., “Rat1-1”, which must match “sample” parameter in Sample) with binary masks of neural tissue boundaries using either:

    a. Segmented histology and Fig 2), or

    b. The mock_morphology_generator.py script (Mock Morphology).

    1. Copy mock_sample.json from config/templates/ to config/user/mock_samples/ as <mock_sample_index>.json and update file contents, including the “NAME” parameter used to construct the destination path for the output binary masks, which serve as inputs to the pipeline.

    2. Call "python run mock_morphology_generator <mock_sample_index>".

    3. The program saves a copy of your mock_sample.json and binary masks in input/<NAME>/.

  2. For one Sample: Copy sample.json from config/templates/ to samples/<sample_index>/ as sample.json and edit its contents to define the processing of binary masks to generate the two-dimensional cross-section geometry of the nerve in the FEM. In particular, change “sample” to match <NAME>, the "scale_bar_length" parameter for s.tif (i.e., length in microns of your scale bar, which is oriented horizontally), and "mask_input" in Sample accordingly (Sample Parameters). You have now created the directory for your first sample: sample #<sample_index>. Note: in lieu of a scale bar image, the user may optionally specify the microns/pixel ratio for the sample mask(s).

  3. For each Model: Copy model.json from config/templates/ to samples/<sample_index>/models/<model_index>/ as model.json and edits its contents to define the three-dimensional FEM.

    a. Assign the cuff geometry to be used by placing a file name from config/system/cuffs in "cuff":"preset".

    b. Optionally, define a new cuff geometry specific to your needs:

    1. Preset: User defines a new “preset” cuff JSON file, which contains instructions for creating their cuff electrode, and saves it as config/system/cuffs/<preset_str>.json.

    2. The <preset_str>.json file name must be assigned to the “preset” parameter in Model (Model Parameters).

  4. For each Sim: Copy sim.json from config/templates/ to config/user/sims/ as <sim_index>.json and edit its contents to inform the NEURON simulations (Sim Parameters).

  5. Run: Copy run.json from config/templates/ to config/user/runs/ as <run_index>.json and edit the indices for the created Sample, Model(s), and Sim(s) configurations (Run Parameters).

  6. The pipeline is run from the project path (i.e., the path to the root of the ASCENT pipeline, which is defined in config/system/env.json) with the command "python run pipeline <run indices>", where <run indices> is a list of space-separated Run indices (if multiple Sample indices, one Run for each). The pipeline outputs ready-to-submit NEURON simulations and associated Run file(s) to the "ASCENT_NSIM_EXPORT_PATH" directory as defined in config/system/env.json (Environment Parameters). NEURON simulations are run locally or submitted to a computer cluster with the command "python submit.py <run indices>" from the export directory.

See also

For more information on ASCENT read about ASCENT usage, ASCENT inputs and controls, and ASCENT parameter options.