|
|
Conditions are the method used to get instructions into Pulse and direct a physiology model to change its patient physiology to a new homeostatic stabilization point. This happens during stabilization, which is when Pulse examines the patient data and configure itself to meet the provided inputs (i.e. stabilize to the requested mean arterial blood pressure). The physiology model is dependent on the model implementation, while an condition is a generic data structure usually associated with a general long term state of the patient. An engine is free to interpret and modify its models according to the intent of the condition and the data it provides. The engine will take the condition into account during stabilization and modify the patient to come to a new homeostatic physiology with the condition taken into account.
|
|
|
Conditions are the method used to get instructions into Pulse and direct a physiology model to change its patient physiology to a new homeostatic stabilization point. This happens during stabilization, which is when Pulse examines the patient data and configures itself to meet the provided inputs (i.e. stabilize to the requested mean arterial blood pressure). The physiology model is dependent on the model implementation, while a condition is a generic data structure usually associated with a general long-term state of the patient. An engine is free to interpret and modify its models according to the intent of the condition and the data it provides. The engine will take the condition into account during stabilization and modify the patient to come to a new homeostatic physiology with the condition taken into account.
|
|
|
|
|
|
In this post we will discuss how to create the infrastructure to design and implement a new condition in the Common Data Model so it can be included in scenario and used by Pulse integrators. We will also look at how a physiology modeler can use the condition in their methodology implementation.
|
|
|
In this post, we will discuss how to create the infrastructure to design and implement a new condition in the Common Data Model so it can be included in scenarios and used by Pulse integrators. We will also look at how a physiology modeler can use the condition in their methodology implementation.
|
|
|
|
|
|
Create the Common Data Model Condition Proto buffer
|
|
|
---------------------------------------------------
|
|
|
You will need to define the data structure for your condition. The data structures are defined in google protocol buffers. The condition structures are organized by the object the condition takes place on. The following files are where we define conditions associated with various objects.
|
|
|
## Create the Common Data Model Condition Proto buffer
|
|
|
|
|
|
* [Environment Conditions](https://gitlab.kitware.com/physiology/engine/blob/master/schema/proto/cdm/EnvironmentConditions.proto)
|
|
|
* [Patient Conditions](https://gitlab.kitware.com/physiology/engine/blob/master/schema/proto/cdm/PatientConditions.proto)
|
|
|
You will need to define the data structure for your condition. The data structures are defined in Google Protocol Buffers. The condition structures are organized by the object on which the condition takes place. The following files are where we define conditions associated with various objects.
|
|
|
|
|
|
For this discussion, we will look at adding a patient condition, but the same principles can be applied to other object related conditions.
|
|
|
* [Environment Conditions](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/schema/pulse/cdm/bind/EnvironmentConditions.proto)
|
|
|
* [Patient Conditions](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/schema/pulse/cdm/bind/PatientConditions.proto)
|
|
|
|
|
|
Open the PatientConditions.proto file in your favorite editor and add the following. (Typically we strive to keep the conditions in alphabetical order)
|
|
|
Note the naming convention is to end each data structure with ``Data``
|
|
|
For this discussion, we will look at adding a patient condition, but the same principles can be applied to other object-related conditions.
|
|
|
|
|
|
```
|
|
|
Open the PatientConditions.proto file in your favorite editor and add the following. (Typically we strive to keep the conditions in alphabetical order) Note the naming convention is to end each data structure with `Data`
|
|
|
|
|
|
```plaintext
|
|
|
message MyNewConditionData
|
|
|
{
|
|
|
// Set the first field to be the encapsulation of the base class
|
... | ... | @@ -25,21 +24,25 @@ message MyNewConditionData |
|
|
}
|
|
|
```
|
|
|
|
|
|
Next, add your new condition object to the list of available patient conditions.
|
|
|
Next, add your new condition object to the list of available patient conditions.
|
|
|
|
|
|
```
|
|
|
```plaintext
|
|
|
message AnyPatientConditionData
|
|
|
{
|
|
|
oneof Condition
|
|
|
{
|
|
|
ChronicAnemiaData ChronicAnemia = 1;
|
|
|
ChronicObstructivePulmonaryDiseaseData ChronicObstructivePulmonaryDisease = 2;
|
|
|
ChronicPericardialEffusionData ChronicPericardialEffusion = 3;
|
|
|
ChronicRenalStenosisData ChronicRenalStenosis = 4;
|
|
|
ChronicVentricularSystolicDysfunctionData ChronicVentricularSystolicDysfunction = 5;
|
|
|
ConsumeMealData ConsumeMeal = 6;
|
|
|
ImpairedAlveolarExchangeData ImpairedAlveolarExchange = 7;
|
|
|
LobarPneumoniaData LobarPneumonia = 8;
|
|
|
AcuteRespiratoryDistressSyndromeData AcuteRespiratoryDistressSyndrome = 1;
|
|
|
ChronicAnemiaData ChronicAnemia = 2;
|
|
|
ChronicObstructivePulmonaryDiseaseData ChronicObstructivePulmonaryDisease = 3;
|
|
|
ChronicPericardialEffusionData ChronicPericardialEffusion = 4;
|
|
|
ChronicRenalStenosisData ChronicRenalStenosis = 5;
|
|
|
ChronicVentricularSystolicDysfunctionData ChronicVentricularSystolicDysfunction = 6;
|
|
|
ConsumeMealData ConsumeMeal = 7;
|
|
|
ImpairedAlveolarExchangeData ImpairedAlveolarExchange = 8;
|
|
|
PneumoniaData Pneumonia = 9;
|
|
|
PulmonaryFibrosisData PulmonaryFibrosis = 10;
|
|
|
PulmonaryShuntData PulmonaryShunt = 11;
|
|
|
SepsisData Sepsis = 12;
|
|
|
|
|
|
// Set this property to a large number, if you do submit this new action
|
|
|
// As a merge request into the master branch, we will assign it a new id
|
... | ... | @@ -49,7 +52,7 @@ message AnyPatientConditionData |
|
|
}
|
|
|
```
|
|
|
|
|
|
```
|
|
|
```plaintext
|
|
|
cmake -DTYPE:STRING=protoc -P run.cmake
|
|
|
# There is also .bat and .sh scripts to make this a little easier
|
|
|
# On windows, you can type
|
... | ... | @@ -58,15 +61,13 @@ run protoc |
|
|
./run.sh protoc
|
|
|
```
|
|
|
|
|
|
Update Convergence Criteria
|
|
|
---------------------------
|
|
|
## Update Convergence Criteria
|
|
|
|
|
|
A condition is applied during patient stabilization in order to ensure the homeostatic baselines properly take into account any and all condition data set on the patient. Each condition can modify any values in the engine, with the goal of affecting various system level properties. At the end of stabilization all of these affected system properties need to be in a homeostatic state, i.e. at a relatively level value. We provide a way to define your convergence criteria for your condition in our [Data Spread Sheet](https://gitlab.kitware.com/physiology/engine/blob/master/data/Data.xlsx). You will need to add a convergence criteria block for your condition in this spreadsheet. We suggest you copy the standard convergence block and add system level data specific associated with your condition. You provide the amount change the value needs to stay within during stabilization to signal that the condition is stable and the engine can start simulation.
|
|
|
A condition is applied during patient stabilization in order to ensure the homeostatic baselines properly take into account any and all condition data set on the patient. Each condition can modify any values in the engine, with the goal of affecting various system-level properties. At the end of stabilization, all of these affected system properties need to be in a homeostatic state, i.e. at a relatively level value. We provide a way to define your convergence criteria for your condition in our [Data Spread Sheet](https://gitlab.kitware.com/physiology/engine/blob/master/data/Data.xlsx). You will need to add a convergence criteria block for your condition in this spreadsheet. We suggest you copy the standard convergence block and add system-level data specifically associated with your condition. You provide the amount of change the value needs to stay within during stabilization to signal that the condition is stable and the engine can start the simulation.
|
|
|
|
|
|
With our changes in place, we will need to generate the convergence data file. From the \<path/to/pulse/build\>/install/bin directory run the following command:
|
|
|
|
|
|
With our changes in place, we will need to generate the convergence data file.
|
|
|
From the <path/to/pulse/build>/install/bin directory run the following command:
|
|
|
```
|
|
|
```plaintext
|
|
|
cmake -DTYPE:STRING=genData -P run.cmake
|
|
|
# There is also .bat and .sh scripts to make this a little easier
|
|
|
# On windows, you can type
|
... | ... | @@ -75,20 +76,18 @@ run genData |
|
|
./run.sh genData
|
|
|
```
|
|
|
|
|
|
Create the Common Data Model C++ Condition
|
|
|
------------------------------------------
|
|
|
Now we are ready to create the C++ files specific to this condition class.
|
|
|
The easiest thing to do is to create copies of [engine/cdm/cpp/patient/conditions/SEChronicAnemia.h](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/patient/conditions/SEChronicAnemia.h) and [engine/cdm/cpp/patient/conditions/SEAcuteStress.cpp](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/patient/conditions/SEChronicAnemia.cpp) files and rename them to SE``your_condition_name``.h/.cpp Then replace the string ``AcuteStress`` with the name of your condition, then create the properties to match your condition protobuf structure. Note the naming convention is to start each file and class name with ``SE``
|
|
|
## Create the Common Data Model C++ Condition
|
|
|
|
|
|
Now we are ready to create the C++ files specific to this condition class. The easiest thing to do is to create copies of [engine/src/cpp/cdm/patient/conditions/SEChronicAnemia.h](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/patient/conditions/SEChronicAnemia.h) and [engine/src/cpp/cdm/patient/conditions/SEChronicAnemia.cpp](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/patient/conditions/SEChronicAnemia.cpp) files and rename them to SE`your_condition_name`.h/.cpp Then replace the string `AcuteStress` with the name of your condition, then create the properties to match your condition Protobuf structure. Note the naming convention is to start each file and class name with `SE`
|
|
|
|
|
|
## Add the Serialization Support for your Condition Class
|
|
|
|
|
|
Add the Serialization Support for your Condition Class
|
|
|
------------------------------------------------------
|
|
|
All CDM classes support serialization to and from a binding class.
|
|
|
You will need to update the appropriate binding class for your action type.
|
|
|
All CDM classes support serialization to and from a binding class. You will need to update the appropriate binding class for your action type.
|
|
|
|
|
|
**Headers**
|
|
|
|
|
|
* [Environment Condition](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/io/protobuf/PBEnvironmentConditions.h)
|
|
|
* [Patient Condition](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/io/protobuf/PBPatientConditions.h)
|
|
|
* [Environment Condition](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/io/protobuf/PBEnvironmentConditions.h)
|
|
|
* [Patient Condition](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/io/protobuf/PBPatientConditions.h)
|
|
|
|
|
|
In our example, for adding a patient condition we will add something like the following code to the appropriate header
|
|
|
|
... | ... | @@ -105,13 +104,12 @@ In our example, for adding a patient condition we will add something like the fo |
|
|
|
|
|
**Code**
|
|
|
|
|
|
* [Environment Condition](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/io/protobuf/PBEnvironmentConditions.cpp)
|
|
|
* [Patient Condition](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/io/protobuf/PBPatientConditions.cpp)
|
|
|
* [Environment Condition](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/io/protobuf/PBEnvironmentConditions.cpp)
|
|
|
* [Patient Condition](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/io/protobuf/PBPatientConditions.cpp)
|
|
|
|
|
|
Implement the newly added methods. I suggest you just copy another condition class method set and use the correct class names.
|
|
|
|
|
|
The Serialization class is also responsible for translating the condition object to and from the AnyCondition object.
|
|
|
You will need to update the following methods to ensure generic condition support.
|
|
|
The Serialization class is also responsible for translating the condition object to and from the AnyCondition object. You will need to update the following methods to ensure generic condition support.
|
|
|
|
|
|
```cpp
|
|
|
|
... | ... | @@ -142,15 +140,16 @@ cdm::AnyPatientConditionData* PBPatientCondition::Unload(const SEPatientConditio |
|
|
...
|
|
|
```
|
|
|
|
|
|
Add the Common Data Model Condition to the Condition Manager
|
|
|
------------------------------------------------------------
|
|
|
The condition manager contains different classes to organize the collection of conditions associated with the engine. Since there are so few conditions, there is only one manager for managing environment and patient conditions (unlike the action manager).
|
|
|
## Add the Common Data Model Condition to the Condition Manager
|
|
|
|
|
|
* [Condition Manager](https://gitlab.kitware.com/physiology/engine/blob/master/cdm/cpp/scenario/SEConditionManager.h.cpp)
|
|
|
The condition manager contains different classes to organize the collection of conditions associated with the engine. Since there are so few conditions, there is only one manager for managing environment and patient conditions (unlike the action manager).
|
|
|
|
|
|
In this example we will basically duplicate the code that manages the SEChronicAnemia condition. Just like we used the SEChronicAnemia condition files as a basis, you can go through the SEConditionManager files and look for SEChronicAnemia and copy the patterns in the file. (Again, we organize instructions alphabetically)
|
|
|
* [Condition Manager](https://gitlab.kitware.com/physiology/engine/-/blob/stable/src/cpp/cdm/engine/SEConditionManager.h)
|
|
|
|
|
|
In this example, we will basically duplicate the code that manages the SEChronicAnemia condition. Just like we used the SEChronicAnemia condition files as a basis, you can go through the SEConditionManager files and look for SEChronicAnemia and copy the patterns in the file. Again, we organize instructions alphabetically.
|
|
|
|
|
|
In the header file you will need to :
|
|
|
|
|
|
```cpp
|
|
|
// Include the header to your action file
|
|
|
#include "patient/conditions/SEMyNewCondition.h"
|
... | ... | @@ -161,9 +160,10 @@ SEMyNewCondition* GetMyNewCondition() const; |
|
|
|
|
|
// Add the member variable
|
|
|
SEMyNewCondition* m_MyNewCondition;
|
|
|
|
|
|
```
|
|
|
|
|
|
In the cpp file you will need to :
|
|
|
|
|
|
```cpp
|
|
|
// initialize the member variable in the constructor
|
|
|
m_MyNewCondition = nullptr;
|
... | ... | @@ -206,14 +206,12 @@ void SEConditionManager::GetActiveConditions(std::vector<const SECondition*>& co |
|
|
if(HasMyNewCondition())
|
|
|
conditions.push_back(GetMyNewCondition());
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
With this file complete, the condition has been added to the Common Data Model and the engine is able to accept this condition and the engine may now implement logic based on this condition.
|
|
|
|
|
|
Adding Support for a Condition to the Engine
|
|
|
--------------------------------------------
|
|
|
You will need to identify the system(s) you wish to check for this condition and put the following code inside
|
|
|
## Adding Support for a Condition to the Engine
|
|
|
|
|
|
You will need to identify the system(s) you wish to check for this condition and put the following code inside
|
|
|
|
|
|
TODO |
|
|
TODO |
|
|
\ No newline at end of file |