This page describes how to use the AcCoRD post-processing utilities that were developed in MATLAB (for version R2015a or newer), including functions to plot signal curves and generate videos. These instructions assume that you have already imported simulation output to MATLAB. If not, then please refer to the AcCoRD Output page for details or the How to Use AcCoRD page for an overview. If you have a configuration file that you want to draw without simulating it first, then please refer to the AcCoRD Configuration page to learn more about using the utility accordEmptyEnvironment.m. AcCoRD has two primary post-processing utility files, neither of which you should call directly:

1. accordPlotMaker.m (the Plot Maker) - Plot curves on a figure showing observed signals from one or more realizations of a simulation. Can also plot non-simulation data (in fact, this can be used as a generic plotting function if desired).
2. accordVideoMaker.m (the Video Maker) - Build video files or a sequence of figures showing molecules from a single realization of a simulation. Optional commands enable you to add annotations, a timer, and molecule counters.

Both of these files, which are found in the AcCoRD "matlab" directory, have a wrapper file that you should copy and modify for your specific simulation and plotting requirements. The wrapper files prepare all of the necessary input arguments and include some documentation about how the arguments can be modified. Generally, you should have a different wrapper for every plot or video that you want to make. This makes it easier to re-generate any plot or video at a later time, as needed. The rest of this page will describe how to prepare the wrappers for these two AcCoRD post-processing functions. If you are interested in other post-processing tasks, e.g., calculating bit error rates, then you should refer to the AcCoRD Output page for details on how to read the simulation output after it has been imported.

Plot Maker

The default wrapper for plotting curves is the file accordPlotMakerWrapper.m. To prepare a plot, you should start by copying and renaming this file. By default, it plots the time-varying signal of the number of molecules observed by the passive actor in the default configuration ("accord_config_sample.txt"). This is actually rather boring, since the environment is a box with 2 molecules in it and the actor watches the whole box! The default wrapper is designed to plot one signal from one passive actor in one output file; this can be expanded by adding for loops. The wrapper takes no input arguments, but it has up to two output arguments:

• "hFig" - handle to the figure. This can be used to modify the figure after it has been created.
• "hAxes" - handle to the figure axes. This can be used to modify the axes (including adding new curves) after it has been created.

The parameters that are defined by the default Plot Maker wrapper are as follows:

• "fileToLoad" - Name of the MATLAB "mat" file whose data will be plotted.
• "hAxes" - Handle to the figure axes to add the curve. If its value is 0, then a new figure and axes will be created.
• "customFigProp" - Structure of figure properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildFigureStruct.m" lists some of the structure fields and their default values. Generally, most valid MATLAB figure properties can be modified here (i.e., figure properties that you can change via the "set" command). Examples include the background color and the size of the figure.
• "customAxesProp" - Structure of axes properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildAxesStruct.m" lists some of the structure fields and their default values. Generally, most valid MATLAB axes properties can be modified here (i.e., axes properties that you can change via the "set" command). Examples include the axis limits and visibility of the grid. The default values are set to favor video generation, so it is recommended to change the "Visible" field to "on" (to show the coordinate axes), the "Projection" field to "orthographic" (which removes depth perception), and the "Clipping" field to "on".
• "passiveID" - Index of passive actor whose signal is to be plotted. The indexing here is from the list of passive actors whose observations were recorded (and not the underlying actor IDs in the original simulation).
• "molID" - Index of the molecule type whose signal is to be plotted. The indexing here is from the list of molecule types that the passive actor recorded (and not the underlying molecule type IDs in the original simulation).
• "customObsProp" - Structure of display properties to configure the curve. It can be an empty array if there are no properties to change (default is the time-varying number of molecules observed, averaged over all realizations). There are many different types of plots and settings to configure the curve. For complete details, please refer to the "accordBuildObserverStruct.m" file. The most critical field of this structure is "obsType", which defines the type of curve. The options for this field are as follows:
  • "Sample" (default) - 2D plot of the time-varying simulation observations. Can be from a specific realization or averaged over any set of realizations (default is to average over all).
  • "Expected" (non-simulation) - 2D plot of user-supplied data. Useful for plotting expected curves, but can be any data. Set the "data1" and "data2" fields as vectors of (x, y) data.
  • "3D Expected" (non-simulation) - 3D version of "Expected". Set the "data1", "data2", and "data3" fields as matrices of (x, y, z) data.
  • "Empirical CDF" - 2D plot of the cumulative distribution function of the simulation observations, i.e., measures the probability that an observation will be less than or equal to some value. Includes all observations at all observation times into one CDF.
  • "3D Empirical CDF" - time-varying version of "Empirical CDF". Every observation time has its own corresponding CDF.
  • "Expected CDF" (non-simulation) - 2D plot of the cumulative distribution function for the specified probability distribution. Options are based on the Binomial distribution, with a corresponding number of trials "numTrials" and success probability "trialProbability". The other distributions are the Poisson and Gaussian approximations of the Binomial distribution.
  • "3D Expected CDF" (non-simulation) - 3D version of "Expected CDF", where the "trialProbability" is a vector instead of a scalar and the "data2" field lists event times associated with the each trial probability.
  • "Empirical PMF" - 2D plot of the probability mass function of the simulation observations, i.e., measures the probability that an observation will be equal to some value. Includes all observations at all observation times into one PMF.
  • "3D Empirical PMF" - time-varying version of "Empirical PMF". Every observation time has its own corresponding PMF.
  • "Expected PMF" (non-simulation) - 2D plot of the probability mass function for the specified probability distribution. Options are based on the Binomial distribution, with a corresponding number of trials "numTrials" and success probability "trialProbability". The other distributions are the Poisson and Gaussian approximations of the Binomial distribution.
  • "3D Expected PMF" (non-simulation) - 3D version of "Expected PMF", where the "trialProbability" is a vector instead of a scalar and the "data2" field lists event times associated with the each trial probability.
  • "Mutual Information" - 2D plot of mutual information between simulation observations relative to a reference observation, which tells you how much the knowledge of the reference observation helps in predicting the value of other observations. The reference observation is the first one specified. Generally, mutual information should decrease as observations become more separated in time. It is measured using all realizations.
  • "3D Mutual Information" - 3D version of "Mutual Information", where there are multiple reference observations. The "data1" vector defines what (relative) observations to measure from each reference. If a value in "data1" is 0, then the corresponding surface points will measure the entropy of each reference observation.
  • "Monte Carlo Mutual Information" (non-simulation) - 2D plot of mutual information between independent random variables generated from Binomial distributions with different success probabilities. Since there is a finite number of realizations of the random variables, the mutual information will have a non-zero value (even though the true mutual information between independent random variables is 0). This kind of curve can take a long time to generate.
  • "3D Monte Carlo Mutual Information" (non-simulation) - 3D version of "Monte Carlo Mutual Information", where there is a matrix instead of a vector of success probabilities. This kind of curve can take a very long time to generate.
• "customCurveProp" - Structure of curve (2D) or surface (3D) properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildCurveStruct.m" lists some of the structure fields and their default values for 2D plots. The file "accordBuildSurfStruct.m" lists some of the structure fields and their default values for 3D plots. Generally, most valid MATLAB curve and surface properties can be modified here (i.e., curve or surface properties that you can change via the "set" command). Examples include marker size, line style, and display name (which you see if you turn on the legend).

Once the wrapper is configured as desired, you can run it to run the Plot Maker and generate the figure. Complete examples of modified wrapper files for generating plots can be found on the AcCoRD Examples page.

Video Maker

Before running simulations to create videos, you should consider the following guidelines:

• Generally, the simulations that you run to create videos may not the same as those for other post-processing. This is because you probably want passive actors to observe more of the environment, and they need exact molecule locations. Recording molecule locations results in larger output files and takes longer to import into MATLAB.
• In order to see molecules in a video, their locations need to be recorded by a passive actor. If not, then there will be nothing to see! So, if you want to watch molecules everywhere in the environment (and in an isolated location, e.g., at an intended receiver), then you will need to configure one or more passive actors to occupy the entire simulation environment. One reason for multiple passive actors that do not overlap is so that you can use different colors to indicate when molecules have entered different areas of the environment.
• A video will only display a single realization, so a simulation run to create a video will mostly likely only need one realization (unless you want to try multiple realizations and pick one with the observations that you want to use).
• The display of any actor or region in the environment is optional and independent of what molecules are being drawn. You can have molecules moving in an environment that appears to be empty.

The Video Wrapper File

The default wrapper for creating videos is the file accordVideoMakerWrapper.m. To prepare a video, you should start by copying and renaming this file. By default, it makes a video of the two molecules diffusing in the default configuration ("accord_config_sample.txt"). The wrapper takes no input arguments, but it has up to two output arguments:

• "hFig" - Array of handles to the figure. This can be used to modify the figures after they have been created (there is an option to create multiple figures instead of building a video).
• "hAxes" - Array of handles to the figure axes. This can be used to modify the axes after they have been created.

The parameters that are defined by the default Video Maker wrapper are as follows (you can see that a number of them are the same as those for the Plot Maker wrapper):

• "fileToLoad" - Name of the MATLAB "mat" file whose data will be plotted.
• "bMakeVideo" - Switch to control whether a video is generated. If false, then each observation will be plotted as a separate figure. If true (or a positive integer), then all observations are plotted in the same figure and stitched into a video file. Entering a number greater than 1 will repeat each frame the specified number of times (to decrease the apparent frame rate).
• "videoName" - Filename to save the video file to. The relevant extension will be added automatically.
• "videoFormat" - Format of the video. See the MATLAB documentation for the "VideoWriter" function to see the full list of options. "Motion JPEG AVI" creates a high quality video with a large file size (but which can be easily converted to a high quality mp4 with a much smaller file size with free tools like VLC Media Player). To generate a small file directly in Windows, set to "MPEG-4" (though experience has shown much better results by building an avi file first and the converting with VLC).
• "curRepeat" - Index of the simulation realization to use.
• "scale" - A scaling factor used to mitigate display problems observed when trying to draw objects that have very small dimensions. This factor is applied to region and actor coordinates. It is recommended that the smallest object (that isn't a molecule) have a length on the order of 1, so a system defined on the order of microns should set "scale" to 1e6.
• "observationToPlot" - Array of indices listing the observations that will be recorded and in what order. Actual actor start times and action intervals are ignored; it is assumed that all recorded actors make observations at the same times. Indices that are larger than the maximum number of observations in the simulation are just ignored.
• "customFigProp" - Structure of figure properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildFigureStruct.m" lists some of the structure fields and their default values. Generally, most valid MATLAB figure properties can be modified here (i.e., figure properties that you can change via the "set" command). Examples include the background color and the size of the figure.
• "customAxesProp" - Structure of axes properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildAxesStruct.m" lists some of the structure fields and their default values. Generally, most valid MATLAB axes properties can be modified here (i.e., axes properties that you can change via the "set" command). Examples include the axis limits and visibility of the grid. The default values are set to favor video generation, so you may not need to change any values from their defaults.
• "customVideoProp" - Structure of video properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordInitializeVideo.m" lists some of the structure fields and their default values. Generally, most valid MATLAB video object properties can be modified here (i.e., video properties that you can change via the "set" command). Examples include the frame rate and the video quality (although video quality does not apply to lossless formats).
• "regionToPlot" - Array of indices of the regions that will be plotted. This can be an empty array if no regions are to be drawn. Choosing to draw a region is independent of choosing to draw the molecules that are inside that region.
• "customRegionProp" - Structure of region display properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildDispStruct.m" lists the structure fields and their default values, which do not correspond to a specific set of MATLAB properties. Properties include color and opacity.
• "actorToPlot" - Array of indices of the actors that will be plotted. Indexing is from the initial actor list (of both active and passive actors). This can be an empty array if no actors are to be drawn. Choosing to draw a actor is independent of choosing to draw the molecules that are inside that actor. Actors are drawn after regions, so if an actor is defined by regions then it will be drawn on top of its regions.
• "customActorProp" - Structure of actor display properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. The file "accordBuildDispStruct.m" lists the structure fields and their default values, which do not correspond to a specific set of MATLAB properties. Properties include color and opacity.
• "passiveActorToPlot" - Array of indices of passive actors whose molecules are to be plotted. Indexing is from the list of passive actors whose observations were recorded. Actors listed here will have their observed molecules plotted and not the actor shapes themselves.
• "molToPlot" - Cell array of arrays of indices of molecule types to plot. Each cell corresponds to the passive actor index specified in "passiveActorToPlot". The array in a given cell lists the indices of the molecule types of that actor that are to be drawn, where the indexing corresponds only to the molecule types that the specific actor observed. For example, if a simulation used 4 types of molecules, and an actor only observed the 4th type of molecule, then its corresponding array can only be [1].
• "customMolProp" - Cell array of structures of molecule display properties to modify from their AcCoRD defaults. It can be an empty array if there are no properties to change. Indexing in this cell array matches the "molToPlot" cell array. The file "accordBuildMarkerStruct.m" lists the structure fields and their default values, which do not correspond to a specific set of MATLAB properties.
• "cameraAnchorArray" - Cell array of cell arrays defining anchor points for the camera display. It can be an empty cell array if the camera view will not be modified. You can control how the camera behaves during a video such that it moves between anchor locations that are defined for specific frames. Each anchor point is a cell array that defines a complete set of camera settings, in the format {'CameraPosition', 'CameraTarget', 'CameraViewAngle', % 'CameraUpVector'}. See the MATLAB camera documentation for more details. You can also add camera anchors to this cell array via the command line at run time (see Running the Video Maker below).
• "frameCameraAnchor" - Array that specifies the camera anchor (from the "cameraAnchorArray" cell array or defined at run time) used in each frame. Length of this array should be equal to that of "observationToPlot". It can be an empty array if "cameraAnchorArray" is also empty. Values in the array must be 0 or match the index of of anchor points in "cameraAnchorArray". If a frame has value 0, and there are anchor points defined for an earlier and a later frame, then the camera settings for the current frame will be linearly interpolated between the camera settings for the surrounding anchors. You can also modify this array via the command line at run time (see Running the Video Maker below).

Once the wrapper is configured as desired, you can run it. See the following section for more details.

Running the Video Maker

The wrapper function is run without any import arguments (unless you added them to your copy). When it calls the Video Maker, a figure is generated and the environment is plotted according to the wrapper arguments (without any molecules yet). If a video file is to be generated, then it is initialized (and over-writing the file if it already existed). Then, execution enters MATLAB's "debug mode" so that you can do any of the following:

1. Change how the regions and actors appear. If you are making a video (and not a sequence of images), then changing the appearance of any regions or actors (e.g., color, line width) will apply to the video.
2. Modify the camera settings.
   • Call the function "accordAddCameraAnchor(FRAME_INDICES)" to add a new camera anchor to the "cameraAnchorArray" cell array, where the current camera settings are used to define a camera anchor point for the frames defined by the FRAME_INDICES array.
   • If the "cameraAnchorArray" cell array defined in the wrapper file was originally empty, then you will see a default view. You can modify the camera as desired (i.e., by panning, zooming, rotating, etc.) and it will be applied as-is for all of the video or sequence of images.
   • If the "cameraAnchorArray" cell array was not originally empty, then the camera settings will show the first anchor point. Changes made to the camera will only apply if you add new anchors.
   • Calling "accordAddCameraAnchor" without any arguments will delete all existing anchors and creates an anchor for every frame using the current camera settings.
3. Add text or graphic annotations. You can add custom text or other annotations that will appear on-screen for any specified subset of the frames. Once you have created the desired annotations for a particular subset of frames, call "accordAddAnnotation(FRAME_INDICES)" to save the annotations, which will appear for the frames defined by the FRAME_INDICES array. Here are some tips and guidelines:
   • De-select the "Edit Plot" button in the figure toolbar before calling accordAddAnnotation. If not, then the last selected object will have the selection highlighting included in the annotation capture. This highlighting will be visible in the final video or image sequence.
   • Generally, annotations will be drawn on top of the molecules.
   • Any annotations that are still on screen when you resume execution of the Video Maker will remain in all frames.
   • Simulation timers and molecule counters (see below) are all ignored when you call accordAddAnnotation.
4. Add a simulation timer. Call the function "accordAddTimeDisplay(NUM_DECIMAL_PLACES)" to print dynamic simulation time in seconds, where NUM_DECIMAL_PLACES is the (optional) number of decimal places. The default is 4 places. The timer text that appears can be moved or re-configured (e.g., font size) as desired.
5. Add a molecule counter. Call the function "accordAddObservationCount(PASSIVE_ACTOR_INDEX, MOLECULE_INDEX, TEXT)" to print a molecule counter. PASSIVE_ACTOR_INDEX is the index of the passive actor to count, from the list of passive actors whose observations were saved to output. MOLECULE_INDEX is the index of molecule to count, from the passive actor's molecule list. TEXT is prefix text that will appear before the counter value. The counter text that appears can be moved or re-configured (e.g., font size) as desired.

To resume execution and generate the video (or sequence of images), enter "dbcont" at the command line. If you want to cancel execution, enter "dbquit".

The Next Step

This is the "end" of the regular instructions. For sample configurations and wrapper files, you can refer to the AcCoRD Examples page.