RegNets Schema Discussion

[mehalter]

I started taking a look at making a JSON format for RegNets. This takes some ideas from our already existing Petri Net schema such as grounding and how we represent rates/initial conditions and applies them to the idea of signed graphs. This is to be a starting point for our discussion in the coming week for formalizing a JSON Schema.

We can use this issue to forward the development before the meeting and bring up missing information/fields.

{
  "name": "Lotka Volterra",
  "schema": "TODO",
  "description": "Lotka Volterra model",
  "model_version": "0.1",
  "model": {
    "vertices": [
      {
        "id": "R",
        "name": "Rabbits",
        "grounding": {},
        "initial": {
          "expression": "R0",
          "expression_mathml": "<mi>R0</mi>"
        },
        "rate": {
          "expression": "",
          "expression_mathml": ""
        }
      },
      {
        "id": "W",
        "name": "Wolves",
        "grounding": {},
        "initial": {
          "expression": "W0",
          "expression_mathml": "<mi>W0</mi>"
        },
        "rate": {
          "expression": "",
          "expression_mathml": ""
        }
      }
    ],
    "edges": [
      {
        "id": "rabbit_growth",
        "src": "R",
        "tgt": "R",
        "sign": true,
        "properties": {
          "name": "",
          "rate": {
            "expression": "",
            "expression_mathml": ""
          }
        }
      },
      {
        "id": "wolf_growth",
        "src": "W",
        "tgt": "W",
        "sign": true,
        "properties": {
          "name": "",
          "rate": {
            "expression": "",
            "expression_mathml": ""
          }
        }
      },
      {
        "id": "predation",
        "src": "W",
        "tgt": "R",
        "sign": false,
        "properties": {
          "name": "",
          "function": {
            "expression": "",
            "expression_mathml": ""
          }
        }
      }
    ],
    "parameters": [
      {
        "id": "R0",
        "description": "Initial rabbit population",
        "value": 10
      },
      {
        "id": "W0",
        "description": "Initial wolf population",
        "value": 1
      }
    ]
  }
}

Pinging @bgyori @brandomr specifically to get eyes on this and for feedback!

I think the only thing that may be missing is currently missing is intrinsic growth rates on the vertices themselves, @jpfairbanks could you weigh in on how we should add that in along with the initial conditions. I'm also not 100% clear as to why intrinsic growth rates are needed and why they aren't positive edges in the regulatory network.

UPDATE: I have cleared up my understanding of why intrinsic growth is necessary for modeling regulatory networks and are different than positive/negative self loops. I updated the example above to include a rate for each vertex as well.

[djinnome]

Will Observables be included as part of the specification as they currently are in MIRA models?

[bgyori]

Will Observables be included as part of the specification as they currently are in MIRA models?

Observables aren't yet represented in the other (petrinet) framework either, I was going to add them soon. We can discuss in today's meeting how to handle them in this framework too.

[jpfairbanks]

@mehalter, we need to also add a human readable description of the Lotka-Volterra Semantics to the documentation here.

[bgyori]

I'm attempting to summarize the discussion points with some changes below:

• Changed src to source and tgt to target just for readability
• Added an example expression to the R vertex to represent natural decay, this comes with a parameter alpha
• Replaced some empty strings with nulls
• Finally, for the rates associated with edges: here I came up with a compromise where I call it a rate_constant that can either be null, a floating point value, or a string. Null means rate is not given, floating point value means a single scalar rate constant, and string means a reference to a model parameter defined under parameters. By calling it rate_constant instead of rate, we make it clear that under this assumption, the source/target are ommitted, and the full rate expression is always source*target*rate_constant.

Let's continue discussion options and try to finalize things by Friday in a PR!

{
  "name": "Lotka Volterra",
  "schema": "TODO",
  "description": "Lotka Volterra model",
  "model_version": "0.1",
  "model": {
    "vertices": [
      {
        "id": "R",
        "name": "Rabbits",
        "grounding": {},
        "initial": {
          "expression": "R0",
          "expression_mathml": "<mi>R0</mi>"
        },
        "rate": {
          "expression": "-alpha",
          "expression_mathml": "<apply><minus/><ci>alpha</ci></apply>"
        }
      },
      {
        "id": "W",
        "name": "Wolves",
        "grounding": {},
        "initial": {
          "expression": "W0",
          "expression_mathml": "<mi>W0</mi>"
        },
        "rate": null
      }
    ],
    "edges": [
      {
        "id": "rabbit_growth",
        "source": "R",
        "target": "R",
        "sign": true,
        "properties": {
          "name": "Rabbit growth"
          "rate_constant": 0.2
        }
      },
      {
        "id": "wolf_growth",
        "source": "W",
        "target": "W",
        "sign": true,
        "properties": {
          "name": null,
          "rate_constant": "beta"
        }
      },
      {
        "id": "predation",
        "source": "W",
        "target": "R",
        "sign": false,
        "properties": {
          "name": null
        }
      }
    ],
    "parameters": [
      {
        "id": "R0",
        "description": "Initial rabbit population",
        "value": 10
      },
      {
        "id": "W0",
        "description": "Initial wolf population",
        "value": 1
      },
      {
        "id": "alpha",
        "description": "Natural decay of rabbits",
        "value": 0.01
      },
      {
        "id": "beta",
        "description": null,
        "value": 0.02
      }
    ]
  }
}

[bgyori]

@mehalter if the modified version looks reasonable, do you want to open a PR with the example and its schema? We can still make changes at the PR stage if needed.

[mehalter]

Yeah I'll get that open by the first of the week! I think it looks pretty good. do we also want t ochange vertices rate to rate_constant? @bgyori

[bgyori]

The reason I left it like that is that we need some way to at least represent polarity for those rates. If we want to move away from the more general rate, I would suggest something like replacing

        "rate": {
          "expression": "-alpha",
          "expression_mathml": "<apply><minus/><ci>alpha</ci></apply>"
        }

with

        "rate_constant": "alpha",
        "rate_sign": false

[djinnome]

Hi folks,

Based on @bgyori 's suggestions, this would be the schema describing a fully-specified Lotka-Volterra model. Can we take this as a canonical example, or are there still missing components?

{
  "name": "Lotka Volterra",
  "schema": "TODO",
  "description": "Lotka Volterra model",
  "model_version": "0.1",
  "model": {
    "vertices": [
      {
        "id": "R",
        "name": "Rabbits",
        "grounding": {},
        "initial_value": "R0",
        "rate_constant": "alpha",
        "rate_sign": true
      },
      {
        "id": "W",
        "name": "Wolves",
        "grounding": {},
        "initial_value": "W0",
        "rate_constant": "gamma"
        "rate_sign": false
      }
    ],
    "edges": [
      {
        "id": "wolf_eats_rabbit",
        "source": "W",
        "target": "R",
        "rate_sign": false,
        "rate_constant": "beta"
      },
      {
        "id": "rabbit_feeds_wolf",
        "source": "R",
        "target": "W",
        "rate_sign": true,
        "rate_constant": "delta"
      },
    ],
    "parameters": [
      {
        "id": "R0",
        "description": "Initial rabbit population",
        "value": 1.0
      },
      {
        "id": "W0",
        "description": "Initial wolf population",
        "value": 1.0
      },
      {
        "id": "alpha",
        "description": "Maximum per capita prey growth rate",
        "value": 0.67
      },
      {
        "id": "beta",
        "description":  "Effect of predators on prey",
        "value": 1.33
      },
      {
        "id": "gamma",
        "description":  "Effect of prey on predators",
        "value": 1.0
      },
      {
        "id": "delta",
        "description":  "Maximum per capita predator death rate",
        "value": 1.0
      }
    ]
  }
}