Mass balance plots: configurable splitting

[Yuri05]

At the moment, the compartments which are used for the summation of the drug amounts are fixed.

Example

The user wish to allow the definition of groups of container/molecules which should be summed up and displayed in the mass balance plots.

For each plot, it should be possible to specify all {container, molecule} combinations which should appear in the plot (and give a name to every such combination).

E.g., if in my model there are 2 compounds: C1 and C2 and 1 metabolite per compound (C1-CYP3A4-Metabolite and C2-CYP3A4-Metabolite), it should be possible to define the grouping like this:

• Plot 1
  • C1 and C1-CYP3A4-Metabolite in every plasma/interstitial/intracellular/blood cells compartments - except for brain
  • C1 and C1-CYP3A4-Metabolite in every plasma/interstitial/intracellular/blood cells compartments of the brain
  • C1 in feces and urine
  • C1 in the rest of the system (= all containers which are not included into the previous definitions)
• Plot2 (same groping as plot 1, but for C2 and C2-CYP3A4-Metabolite)

Possible specification for such a grouping:

• List of mass balance plot configurations. Each configuration has the properties:
  • Name of the plot (to be displayed in the report)
  • List of subgroupings. Each subgrouping has the properties:
    • Name of the subgrouping (to be displayed in the report)
    • List of paths to include. Each path in the ospsuite-R recognizable format (using the wildcards * and ** ). Must contain at least one entry
    • List of paths to exclude. Each path in the ospsuite-R recognizable format. May be empty.
  • "Rest"-subgroup with the properties:
    • Name to be used in the report
    • List of the molecule names

Json code for the mass balance settings for the example above

{
  "Mass balance plots": [
    {
      "Name": "C1 mass balance",
      "Groupings": [
        {
          "Name": "Brainless",
          "Include": [
            "Organism|**|Plasma|C1*",
            "Organism|**|Interstitial|C1*",
            "Organism|**|Intracellular|C1*",
            "Organism|**|BloodCells|C1*"
          ],
          "Exclude": [
            "Organism|Brain|*|C1*"
          ]
        },
        {
          "Name": "Brain",
          "Include": [
            "Organism|Brain|*|C1*"
          ]
        },
        {
          "Name": "Excreted",
          "Include": [
            "Organism|Kideny|Urine|C1*",
            "Organism|Lumen|Feces|C1*"
          ]
        }
      ],
      "Rest": {
        "Name": "Rest of C1",
        "Molecules": [
          "C1"
        ]
      }
    },
    {
      "Name": "C2 mass balance",
      "Groupings": [
        {
          "Name": "Brainless",
          "Include": [
            "Organism|**|Plasma|C2*",
            "Organism|**|Interstitial|C2*",
            "Organism|**|Intracellular|C2*",
            "Organism|**|BloodCells|C2*"
          ],
          "Exclude": [
            "Organism|Brain|**|C2*"
          ]
        },
        {
          "Name": "Brain",
          "Include": [
            "Organism|Brain|*|C2*"
          ]
        },
        {
          "Name": "Excreted",
          "Include": [
            "Organism|Kideny|Urine|C2*",
            "Organism|Lumen|Feces|C2*"
          ]
        }
      ],
      "Rest": {
        "Name": "Rest of C2",
        "Molecules": [
          "C2"
        ]
      }
    }
  ]
}

[Yuri05]

@msevestre @pchelle @KatrinCoboeken @sfrechen @AnnikaRPS Thoughts/Comments?

[KatrinCoboeken]

Looks good

[pchelle]

Looks also good to me.
I think the grouping should be defined as a Json file format.
This way it may be easier for the user to re-use it and the workflow can directly read and translate it.

I'll draft a template example to illustrate.

[pchelle]

Here is a template that was inspired from plotMeanMassBalance() and that would leverage the json input

mass-balance.zip

[Yuri05]

Looks good!
Just one remark:
Exclude section in the "Rest" grouping is redundant. It is the union of the Include sections of all other groupings.
We should provide a flag which indicates that the rest group is.. well, the rest group.
E.g. something like this:

{
    "Name": "Rest of Raltegravir",
    "ExcludeOtherGroupings": 1,
    "Include": [
        "Organism|**|Raltegravir*"
    ]
}

It would be still possible to define additional Exclude-conditions in the rest group ig required - which would be then combined with the includes from all other groups, e.g.

{
    "Name": "Rest of Raltegravir",
    "ExcludeOtherGroupings": 1,
    "Include": [
        "Organism|**|Raltegravir*"
    ],
    "Exclude": [
        "Organism|Applications|*|Raltegravir*"
    ]
}

[pchelle]

I like the idea, I would even go further and use a ExcludePreviousGroupings.
If undefined, default would be always TRUE for all the groupings, this way it should prevents redundant groupings unless the user specifically asks for it.
Thoughts ?

[pchelle]

I did not discuss the integration, in my opinion, the best way to integrate this is within the SimulationSet objects (that could perform a few checks beforehand - such as checking that the molecules exist in the simulation).

[Yuri05]

I like the idea, I would even go further and use a ExcludePreviousGroupings. If undefined, default would be always TRUE for all the groupings, this way it should prevents redundant groupings unless the user specifically asks for it. Thoughts ?

fine for me :)

[Yuri05]

I did not discuss the integration, in my opinion, the best way to integrate this is within the SimulationSet objects (that could perform a few checks beforehand - such as checking that the molecules exist in the simulation).

it should be a setting of Mass Balance Task.
If Mass Balance Task is not active - there is no need to check the configuration of the groupings.

EDIT: after discussion - SimulationSet is better location for the MassBalance options (as the simulations in different SimulationSets can e.g. have different compounds)