|
|
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](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Methodology). 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] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) Wiki for how to compile new methodology updates.
|
|
|
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](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) Wiki for how to compile new methodology updates.
|
|
|
|
|
|
Methodology Layout
|
|
|
------------------
|
|
|
|
|
|
All reports have the same basic layout and information that follows the [Methodology Template] (https://gitlab.kitware.com/physiology/engine/blob/master/docs/Methodology/MethodologyTemplate.md). These documents need to be updated as part of the contribution process.
|
|
|
All reports have the same basic layout and information that follows the [Methodology Template](https://gitlab.kitware.com/physiology/engine/blob/master/docs/Methodology/MethodologyTemplate.md). 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] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Methodology).
|
|
|
All new or modified functionality should be described in the appropriate methodology Markdown document located in the [methodology directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Methodology).
|
|
|
|
|
|
Adding Citations
|
|
|
----------------
|
|
|
|
|
|
All references must be added in BibTeX format to the [Sources.bib] (https://gitlab.kitware.com/physiology/engine/blob/master/docs/Sources.bib) file. They can then be cited using the *@cite* tag and will be automatically during the [Generating Documentation] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) process.
|
|
|
All references must be added in BibTeX format to the [Sources.bib](https://gitlab.kitware.com/physiology/engine/blob/master/docs/Sources.bib) file. They can then be cited using the *@cite* tag and will be automatically during the [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) process.
|
|
|
|
|
|
Adding Equations
|
|
|
----------------
|
|
|
|
|
|
Formulas can be inserted into the text using [MathJax format] (https://www.stack.nl/~dimitri/doxygen/manual/formulas.html) and will be automatically generated during the [Generating Documentation] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) process.
|
|
|
Formulas can be inserted into the text using [MathJax format](https://www.stack.nl/~dimitri/doxygen/manual/formulas.html) and will be automatically generated during the [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) process.
|
|
|
|
|
|
Adding Images and Plots
|
|
|
-----------------------
|
|
|
|
|
|
### Static Figures
|
|
|
|
|
|
You can add images to the documentation by saving them to the [Images directory] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images) and referencing them with a tag in the Markdown file you are editing. There are many examples of this in the [existing reports] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Methodology).
|
|
|
You can add images to the documentation by saving them to the [Images directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images) and referencing them with a tag in the Markdown file you are editing. There are many examples of this in the [existing reports](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Methodology).
|
|
|
|
|
|
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] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures). 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.
|
|
|
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](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures). 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] (https://sourceforge.net/projects/tinycad/) and can be found in the [CircuitDiagrams] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures/CircuitDiagrams) directory. Like the other static figures, circuit diagrams should also be manually saved as images in the [Images directory] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images).
|
|
|
Existing Pulse circuit diagrams were created using [TinyCAD](https://sourceforge.net/projects/tinycad/) and can be found in the [CircuitDiagrams](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures/CircuitDiagrams) directory. Like the other static figures, circuit diagrams should also be manually saved as images in the [Images directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images).
|
|
|
|
|
|
To update any existing figure, merely replace it with the same filename in the [Images directory] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images). As long as the tag in the markdown file does not change, it will be used when the html is generated (see [Generating Documentation] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation)).
|
|
|
To update any existing figure, merely replace it with the same filename in the [Images directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images). As long as the tag in the markdown file does not change, it will be used when the html is generated (see [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation)).
|
|
|
|
|
|
### Static Plots from Excel
|
|
|
|
|
|
Some static plots are created in an Excel file located in either the [Figures directory] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures) or the [validation directory] (https://gitlab.kitware.com/physiology/engine/tree/master/test/validation) and manually saved as an image to the [Images directory] (https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images).
|
|
|
Some static plots are created in an Excel file located in either the [Figures directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Figures) or the [validation directory](https://gitlab.kitware.com/physiology/engine/tree/master/test/validation) and manually saved as an image to the [Images directory](https://gitlab.kitware.com/physiology/engine/tree/master/docs/Images).
|
|
|
|
|
|
### 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] (https://gitlab.kitware.com/physiology/engine/tree/master/test/validation/Waveforms). Once you add a new CSV file you can add the commands to generate the plot image in the [PlotRun.config] (https://gitlab.kitware.com/physiology/engine/blob/master/test/config/PlotRun.config) configuration file using the *ValidationData* tag. There are many examples to see how
|
|
|
Other static plots are automatically generated during the documentation compiling process from CSV data. These CSV files are located in the [Waveforms directory](https://gitlab.kitware.com/physiology/engine/tree/master/test/validation/Waveforms). Once you add a new CSV file you can add the commands to generate the plot image in the [PlotRun.config] (https://gitlab.kitware.com/physiology/engine/blob/master/test/config/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] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) 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.
|
|
|
The plot images will be automatically generated and stored during the [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) 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] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) 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] (https://gitlab.kitware.com/physiology/engine/wikis/home). 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.
|
|
|
Validation plots are automatically generated from verification scenario outputs during the [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) 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](https://gitlab.kitware.com/physiology/engine/wikis/home). 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] (https://gitlab.kitware.com/physiology/engine/blob/master/test/config/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.
|
|
|
New plots can be added [PlotRun.config](https://gitlab.kitware.com/physiology/engine/blob/master/test/config/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] (https://pulse.kitware.com/_respiratory_methodology.html#respiratory-validation)). The tables are automatically generated from verification scenario outputs during the [Generating Documentation] (https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) process.
|
|
|
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](https://pulse.kitware.com/_respiratory_methodology.html#respiratory-validation)). The tables are automatically generated from verification scenario outputs during the [Generating Documentation](https://gitlab.kitware.com/physiology/engine/wikis/Generating%20Documentation) 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] (https://gitlab.kitware.com/physiology/engine/wikis/Updating%20Baselines) as part of the submission process.
|
|
|
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](https://gitlab.kitware.com/physiology/engine/wikis/Updating%20Baselines) 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] (https://gitlab.kitware.com/physiology/engine/tree/master/test/validation).
|
|
|
2. Add the associated properly cited validation data to a new row in the proper validation Excel spreadsheet located in the [validation directory](https://gitlab.kitware.com/physiology/engine/tree/master/test/validation).
|
|
|
|
|
|
### Static Tables
|
|
|
|
|
|
Static tabular data can be added directly to the Markdown files using the [appropriate format] (https://help.github.com/articles/organizing-information-with-tables/).
|
|
|
Static tabular data can be added directly to the Markdown files using the [appropriate format](https://help.github.com/articles/organizing-information-with-tables/).
|
|
|
|
|
|
### Scenario Validation Tables
|
|
|
|
... | ... | @@ -79,7 +79,7 @@ Each action and condition should have at least one scenario associated with it a |
|
|
- `<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] (https://pulse.kitware.com/_respiratory_methodology.html#respiratory-actionvalidation)).
|
|
|
3. Copy and paste the table into the *Scenario Validation* section of the methodology document (see the respiratory example [here](https://pulse.kitware.com/_respiratory_methodology.html#respiratory-actionvalidation)).
|
|
|
|
|
|
Generate and Review
|
|
|
-------------------
|
... | ... | |