Updating Documentation

Each Pulse system has its own methodology page that includes information about the design and results in the form of a Markdown file. The system methodology documents are located here. These files leverage Doxygen to produce html that includes static elements such as text, tables, and images; as well as automatically generated elements from the latest results such as validation tables and scenario plots.

In this post, we will discuss the process to update methodology documents with an emphasis on adding new models, actions, and conditions. See the Generating Documentation Wiki for how to compile new methodology updates.

Methodology Layout

All reports have the same basic layout and information that follows the Methodology Template. These documents need to be updated as part of the contribution process.

Adding Text

All new or modified functionality should be described in the appropriate methodology Markdown document located in the methodology directory.

Adding Citations

All references must be added in BibTeX format to the Sources.bib file. They can then be cited using the @cite tag and will be automatically during the Generating Documentation process.

Adding Equations

Formulas can be inserted into the text using MathJax format and will be automatically generated during the Generating Documentation process.

Adding Images and Plots

Static Figures

You can add images to the documentation by saving them to the Images directory and referencing them with a tag in the Markdown file you are editing. There are many examples of this in the existing reports.

Most Pulse figures were generated in PowerPoint before being saved as images to allow for easy future modification. These working files can be found in the Figures directory. Updates to each system's data flow diagram can be done here, which is required for new functionality like the addition of an action or condition.

Existing Pulse circuit diagrams were created using TinyCAD and can be found in the CircuitDiagrams directory. Like the other static figures, circuit diagrams should also be manually saved as images in the Images directory.

To update any existing figure, merely replace it with the same filename in the Images directory. As long as the tag in the markdown file does not change, it will be used when the html is generated (see Generating Documentation).

Static Plots from Excel

Some static plots are created in an Excel file located in either the Figures directory or the validation directory and manually saved as an image to the Images directory.

Static Plots from CSV

Other static plots are automatically generated during the documentation compiling process from CSV data. These CSV files are located in the Waveforms directory. Once you add a new CSV file you can add the commands to generate the plot image in the PlotRun.config configuration file using the ValidationData tag. There are many examples to see how

The plot images will be automatically generated and stored during the Generating Documentation process. The resulting jpg plot images will be stored in the <pulse/build>/install/bin/docs/htmlplots directory. You will then need to add an image tag to insert the images in the appropriate Markdown file location.

Validation Plots

Validation plots are automatically generated from verification scenario outputs during the Generating Documentation process. Each condition and action should have at least one scenario associated with it. Each of these scenarios should have plots and validation tables. You must pull all of the baseline scenarios, which can be done executing the updateBaselines command described here. Note that these plots are generated from the baseline CSV data in the <pulse/build>/install/bin/verification directory, NOT from the outputs you may have generated in the <pulse/build>/install/bin/test_results directory.

New plots can be added PlotRun.config file. Follow the examples that already exist. The resulting jpg plot images will be stored in the <pulse/build>/install/bin/docs/htmlplots directory. You will then need to add an image tag to insert the images in the appropriate Markdown file location.

Adding Tables

System or Compartment Tables

With a few exceptions, all system variables (i.e., vitals) should have a healthy standard validation value associated with it. These tables are in the Validation - Resting Physiologic State section of each system methodology document (see the respiratory report example here). The tables are automatically generated from verification scenario outputs during the Generating Documentation process.

Values can be added to the validation table by following these steps:

1. Add the new DataRequest to the appropriate pba scenario file in the <pulse/build>/install/bin/verification/scenarios/validation directory. You will need to update the baselines as part of the submission process.

2. Add the associated properly cited validation data to a new row in the proper validation Excel spreadsheet located in the validation directory.

Static Tables

Static tabular data can be added directly to the Markdown files using the appropriate format.

Scenario Validation Tables

Each action and condition should have at least one scenario associated with it and all scenarios should have expected values for important parameters to validate correct functionality. These tables are not automatically generated, so you will need to add them directly to the Markdown file by following these steps:

1. Add the table as a new tab in the appropriate validation excel spreadsheet located in the scenarios validation directory directory. You will need to include any citations for where these validation values come from. See the examples to include cells with Markdown table formatting for easy copying and pasting into the Markdown file.

2. Format the expected results cells in the table to be color coded using the following:

• <span class="success"> *expected result* </span> tag to color things green that have <10% deviation from the expected value or have good agreement with the expected trend.
• <span class="warning"> *expected result* </span> tag to color things yellow that have <30% deviation from the expected value or have some deviation from the expected trend.
• <span class="danger"> *expected result* </span> tag to color things red that have >30% deviation from the expected value or have poor agreement with the expected trend.

3. Copy and paste the table into the Scenario Validation section of the methodology document (see the respiratory example here).

Generate and Review

See the How to generate the documentation page to create the html files.