Sources of model content

Sources of models.

ASKEM AMR (mira.sources.amr)

model_from_url(url)[source]

Return a model from a URL, handling multiple frameworks.

Parameters:

url – The URL to the JSON file.

Returns:

A TemplateModel object.

model_from_json_file(fname)[source]

Return a model from a file, handling multiple frameworks.

Parameters:

fname – The path to the JSON file.

Returns:

A TemplateModel object.

model_from_json(model_json)[source]

Return a model from a JSON object, handling multiple frameworks.

Parameters:

model_json – The JSON object containing the model information.

Returns:

A TemplateModel object.

sanity_check_amr(amr_json)[source]

Check that the AMR is valid

Parameters:

amr_json – The JSON object containing the AMR.

Raises:

  • AssertionError – If the AMR doesn’t have a header or a schema.

  • jsonschema.exceptions.ValidationError – If the instance is invalid

  • jsonschema.exceptions.SchemaError – If the schema itself is invalid

ASKEM AMR Petri nets (mira.sources.amr.petrinet)

This module implements parsing Petri net models defined in https://github.com/DARPA-ASKEM/Model-Representations/tree/main/petrinet.

MIRA TemplateModel representation limitations to keep in mind:

  • Model version not supported

  • Model schema not supported

  • Initials only have a value, cannot be expressions so information on initial condition parameter relationship is lost

model_from_url(url)[source]

Return a model from a URL

Parameters:

url (str) – The URL to the JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel object.

model_from_json_file(fname)[source]

Return a model from a JSON file.

Parameters:

fname (str) – The path to the JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel object.

template_model_from_amr_json(model_json)[source]

Return a model from a JSON object.

Parameters:

model_json – The JSON object.

Return type:

TemplateModel

Returns:

A TemplateModel object.

ASKEM AMR Stockflow (mira.sources.amr.stockflow)

This module implements parsing Stock and Flow models defined in https://github.com/DARPA-ASKEM/Model-Representations/tree/main/stockflow.

template_model_from_amr_json(model_json)[source]

Return a model from a JSON object.

Parameters:

model_json – The JSON object.

Return type:

TemplateModel

Returns:

A TemplateModel object.

stock_to_concept(stock)[source]

Return a Concept from a stock

Parameters:

stock – A stock JSON object.

Return type:

Concept

Returns:

The Concept corresponding to the provided stock.

model_from_url(url)[source]

Return a model from a URL

Parameters:

url (str) – The URL to the JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel object.

ASKEM AMR Regulatory nets (mira.sources.amr.regnet)

This module implements parsing RegNet models defined in https://github.com/DARPA-ASKEM/Model-Representations/tree/main/regnet.

model_from_url(url)[source]

Return a model from a URL

Parameters:

url (str) – The URL to the JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel object.

model_from_json_file(fname)[source]

Return a model from a JSON file.

Parameters:

fname (str) – The path to the JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel object.

template_model_from_amr_json(model_json)[source]

Return a model from a JSON object.

Parameters:

model_json – The JSON object.

Return type:

TemplateModel

Returns:

A TemplateModel object.

Reconstruct ODE semantics (mira.sources.amr.flux_span)

This module implements handling flux span model representations that are the result of stratification and map back to original models before stratification.

reproduce_ode_semantics(flux_span)[source]

Reproduce ODE semantics from a stratified model (flux span)

Parameters:

flux_span – The AMR JSON object to reproduce ODE semantics from.

Return type:

TemplateModel

Returns:

The reproduced TemplateModel

SBML extraction (mira.sources.sbml)

template_model_from_sbml_file(file_path, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a file containing SBML XML.

Parameters:

  • file_path – The path to the SBML file.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML file if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted MIRA template model.

template_model_from_sbml_file_obj(file, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a file object containing SBML XML.

Parameters:

  • file – The open file object containing the SBML XML.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML file if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted MIRA template model.

template_model_from_sbml_string(s, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a string representing SBML XML.

Parameters:

  • s (str) – The string containing the SBML XML.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML xml if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted TemplateModel.

template_model_from_sbml_model(sbml_model, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from an SBML model object.

Parameters:

  • sbml_model – The SBML model object.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML model if it’s a BIOMODELS model.

Return type:

TemplateModel

Returns:

The extracted TemplateModel.

sbml_model_from_file(fname)[source]

Return an SBML model object from an SBML file.

Parameters:

fname – The path to the SBML file.

Returns:

An SBML model object.

SBML Qual extraction (mira.sources.sbml.qual_api)

template_model_from_sbml_qual_file(file_path, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a file containing SBML Qual XML.

Parameters:

  • file_path – The path to the SBML Qual file.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML Qual file if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted MIRA template model.

template_model_from_sbml_qual_file_obj(file, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a file object containing SBML Qual XML.

Parameters:

  • file – The open file object containing the SBML Qual XML.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML Qual file if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted MIRA template model.

template_model_from_sbml_qual_string(s, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from a string representing SBML Qual XML.

Parameters:

  • s (str) – The string containing the SBML Qual XML.

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML Qual xml if it’s a BIOMODELS model.

  • reporter_ids (Optional[Iterable[str]]) – An iterable of reporter IDs

Return type:

TemplateModel

Returns:

The extracted TemplateModel.

template_model_from_sbml_qual_model(sbml_model, qual_model, *, model_id=None, reporter_ids=None)[source]

Extract a MIRA template model from an SBML Qual model object.

Parameters:

  • sbml_model – The SBML model object.

  • qual_model – The SBML Qual model object

  • model_id (Optional[str]) – The ID of the model to extract. (Optional) If not provided, an attempt will be made to extract an ID from the SBML Qual model if it’s a BIOMODELS model.

Return type:

TemplateModel

Returns:

The extracted TemplateModel.

sbml_qual_model_from_file(fname)[source]

Return an SBML model object and SBML Qual model object from an SBML Qual file.

Parameters:

fname – The path to the SBML Qual file.

Returns:

  • An SBML model object.

  • An SBMl Qual Model object.

BioModels client (mira.sources.biomodels)

The BioModels database lists several high quality models at https://www.ebi.ac.uk/biomodels/covid-19.

NON_COVID_EPI_MODELS = {'BIOMD0000000249', 'BIOMD0000000294', 'BIOMD0000000715', 'BIOMD0000000716', 'BIOMD0000000717', 'BIOMD0000000726', 'BIOMD0000000922', 'BIOMD0000000949', 'BIOMD0000000950', 'BIOMD0000001045', 'MODEL1008060000', 'MODEL1008060002', 'MODEL1805220001', 'MODEL1805230001', 'MODEL1808280006', 'MODEL1808280011', 'MODEL2212310001'}

Additional model identifiers for epidemiology models that do not appear in the BioModels curated list of COVID-19 models

MODEL_TO_PUBMED = {'BIOMD0000000716': '30839942', 'BIOMD0000000717': '30839942'}

Annotation of missing pubmeds to model ids

query_biomodels(query='submitter_keywords:COVID-19', limit=30)[source]

Query and paginate over results from the BioModels API.

See also

https://www.ebi.ac.uk/biomodels/docs/

Parameters:

  • query (str) – The query string to search for. Defaults to “submitter_keywords:COVID-19”.

  • limit (int) – The maximum number of results to return. Defaults to 30.

Return type:

List[Dict[str, str]]

Returns:

A list of model metadata dictionaries.

get_sbml_model(model_id)[source]

Return the SBML string content for a BioModels model from the web.

Parameters:

model_id (str) – The BioModels ID of the model.

Return type:

str

Returns:

The SBML XML string corresponding to the model.

get_template_model(model_id)[source]

Return the Template Model processed from a BioModels model from the web.

Parameters:

model_id (str) – The BioModels ID of the model.

Return type:

TemplateModel

Returns:

The Template model corresponding to the BioModels model.

SymPy ODE extraction (mira.sources.sympy_ode)

template_model_from_sympy_odes(odes, concept_data=None, param_data=None)[source]

Return a TemplateModel from a set of sympy ODEs.

Parameters:

  • odes (list of sympy.Eq) –

    A list of sympy equations representing the ODEs. example input: odes = [Eq(Derivative(S(t), t), -b*I(t)*S(t)),

    Eq(Derivative(E(t), t), b*I(t)*S(t) - r*E(t)), Eq(Derivative(I(t), t), -g*I(t) + r*E(t)), Eq(Derivative(R(t), t), g*I(t))]

  • concept_data (Optional[dict]) – An optional dictionary of data used when constructing concepts. The keys are the names of the concepts and the values are dictionaries of data to pass to the Concept constructor.

  • param_data (Optional[dict]) – An optional dictionary of data used when constructing parameters. The keys are the names of the parameters and the values are dictionaries of data to pass to the Parameter constructor.

Returns:

A template model representing the ODEs.

Return type:

TemplateModel

exception CodeExecutionError[source]

Bases: Exception

An error raised when there is an error executing the code

pdf_file_to_odes_str(pdf_path, client)[source]

Get an ODE string from a PDF file depicting an ODE system

Parameters:

  • pdf_path (str) – The path to the PDF file

  • client (OpenAIClient) – A mira.openai_utility.OpenAIClient instance

Return type:

str

Returns:

The ODE string extracted from the PDF. The string should contain the code necessary to define the ODEs using sympy.

pdf_to_odes_str(pdf_bytes, client)[source]

Get an ODE string from PDF bytes depicting an ODE system

Parameters:

  • pdf_bytes (bytes) – The bytes of the PDF file

  • client (OpenAIClient) – The OpenAI client

Return type:

str

Returns:

The ODE string extracted from the PDF. The string should contain the code necessary to define the ODEs using sympy.

extract_ode_str_from_base64_pdf(base64_pdf, client, prompt=None)[source]

Get the ODE string from a PDF in base64 format

Parameters:

  • base64_pdf (str) – The base64 encoded PDF

  • client (OpenAIClient) – The OpenAI client

  • prompt (Optional[str]) – The prompt to send to the OpenAI chat completion. If None, the default prompt is used (see mira.sources.sympy_ode.constants.ODE_PDF_PROMPT)

Return type:

str

Returns:

The ODE string extracted from the PDF. The string should contain the code necessary to define the ODEs using sympy.

image_file_to_odes_str(image_path, client)[source]

Get an ODE string from an image file or a list of image files depicting an ODE system

Parameters:

  • image_path (Union[str, List[str]]) – The path to the image file or a list of paths to each image file

  • client (OpenAIClient) – A mira.openai_utility.OpenAIClient instance

Return type:

str

Returns:

The ODE string extracted from the image(s). The string should contain the code necessary to define the ODEs using sympy.

image_to_odes_str(image_bytes, client, image_format)[source]

Get an ODE string from an image or a list of images depicting an ODE system

Parameters:

  • image_bytes (Union[bytes, List[bytes]]) – The bytes of the image or a list of bytes for each image

  • client (OpenAIClient) – The OpenAI client

  • image_format (Union[Literal['jpeg', 'jpg', 'png', 'webp', 'gif'], List[Literal['jpeg', 'jpg', 'png', 'webp', 'gif']]]) – The format of the image or a list of formats for each image.

Return type:

str

Returns:

The ODE string extracted from the image. The string should contain the code necessary to define the ODEs using sympy.

clean_response(response)[source]

Clean up the response from the OpenAI chat completion

Parameters:

response (str) – The response from the OpenAI chat completion.

Return type:

str

Returns:

The cleaned up response. The response is stripped of the code block markdown, i.e. the triple backticks and the language specifier. It is also stripped of leading and trailing whitespaces.

extract_ode_str_from_base64_image(base64_image, image_format, client, prompt=None)[source]

Get the ODE string from an image or list of images in base64 format

Parameters:

  • base64_image (Union[str, List[str]]) – The base64 encoded image or a list of base64 encoded images

  • image_format (Union[Literal['jpeg', 'jpg', 'png', 'webp', 'gif'], List[Literal['jpeg', 'jpg', 'png', 'webp', 'gif']]]) – The format of the image or a list of each image format

  • client (OpenAIClient) – The OpenAI client

  • prompt (str) – The prompt to send to the OpenAI chat completion. If None, the default prompt is used depending on if one or multiple images are sent (see mira.sources.sympy_ode.constants.ODE_IMAGE_PROMPT and mira.sources.sympy_ode.constants.ODE_MULTIPLE_IMAGE_PROMPT)

Returns:

The ODE string extracted from the image. The string should contain the code necessary to define the ODEs using sympy.

get_concepts_from_odes(ode_str, client)[source]

Get the concepts data from the ODEs defined in the code snippet

Parameters:

  • ode_str (str) – The string containing the code snippet defining the ODEs

  • client (OpenAIClient) – The openAI client

Return type:

Optional[dict]

Returns:

The concepts data in the form of a dictionary, or None if no concepts data could be generated.

test_execution(code)[source]

Test if code executes successfully

Parameters:

code (str) – The Python code

Return type:

tuple[bool, str]

Returns:

Tuple of (success, error_message). success is True if code executed and defined odes, False otherwise. error_message is empty on success.

test_ode_model(odes)[source]

Test if a list of SymPy ODEs can be converted to a TemplateModel

Parameters:

odes – The list of sympy.Eq ODEs to test

Return type:

tuple[bool, str]

Returns:

Tuple of (success, error_message).

Bilayer extraction (mira.sources.bilayer)

This module implements an input processor for bilayer representations of models based on mass-action kinetics.

template_model_from_bilayer_file(fname)[source]

Return a TemplateModel by processing a bilayer JSON file.

Parameters:

fname (str) – The path to a bilayer JSON file.

Return type:

TemplateModel

Returns:

A TemplateModel extracted from the bilayer.

template_model_from_bilayer(bilayer_json)[source]

Return a TemplateModel by processing a bilayer JSON file.

Parameters:

bilayer_json (dict) – A bilayer JSON structure.

Return type:

TemplateModel

Returns:

A TemplateModel extracted from the bilayer.

ACSets Petri Net extraction (mira.sources.acsets.petri)

template_model_from_petri_json(petri_json)[source]

Return a TemplateModel by processing a Petri net JSON dict

Parameters:

petri_json (dict) – A Petri net JSON structure.

Return type:

TemplateModel

Returns:

A TemplateModel extracted from the Petri net.

ACSets Stockflow extraction (mira.sources.acsets.stockflow)

This module implements parsing of a Stock and Flow acset model and turns it into a MIRA template models.

template_model_from_stockflow_ascet_json(model_json)[source]

Returns a TemplateModel by processing a Stock and flow JSON dict.

Parameters:

model_json (JSON) – The stock and flow JSON structure.

Return type:

TemplateModel

Returns:

A TemplateModel extracted from the Stock and flow model.

stock_to_concept(stock)[source]

Creates a concept from a stock

Parameters:

stock (JSON) – The stock to be converted

Return type:

Concept

Returns:

The concept created from the stock

ACSets Decapodes extraction (mira.sources.acsets.decapodes.decapodes)

process_decapode(decapode_json)[source]

Process a Decapode compute graph JSON structure into a Decapode object.

Parameters:

decapode_json (JSON) – The Decapode compute graph JSON of a model.

Return type:

Decapode

Returns:

The corresponding MIRA Decapode object.

ACSets DecaExpr extraction (mira.sources.acsets.decapodes.deca_expr)

process_decaexpr(decaexpr_json)[source]

Process a DecaExpr JSON into a Decapode object.

Parameters:

decaexpr_json (JSON) – The DecaExpr JSON of a model.

Return type:

Decapode

Returns:

The corresponding MIRA Decapode object.

Vensim models (mira.sources.system_dynamics.vensim)

This module implements an API interface for retrieving Vensim models by Ventana Systems denoted by the .mdl extension through a locally downloaded file or URL. We then convert the Vensim model into a generic pysd model object that will be parsed and converted to an equivalent MIRA template model. We preprocess the vensim file to extract variable expressions.

Vensim model documentation:https://www.vensim.com/documentation/sample_models.html

Repository of sample Vensim models: https://github.com/SDXorg/test-models/tree/master/samples

template_model_from_mdl_file(fname, *, grounding_map=None, initials=None, initials_from_integ=False)[source]

Return a template model from a local Vensim file

Parameters:

  • fname (str or pathlib.Path) – The path to the local Vensim file

  • grounding_map (dict[str, Concept]) – A grounding map, a map from label to Concept

  • initials (dict[str, float]) – Explicit initial values to use for compartments in the model. Will overwrite model-internal definitions.

  • initials_from_integ (bool) – If true, gets initial values from INTEG expressions. If initials are given, they override anything from INTEG expressions

Return type:

TemplateModel

Returns:

A MIRA template model

template_model_from_mdl_url(url, *, grounding_map=None, initials=None, initials_from_integ=False)[source]

Return a template model from a Vensim file provided by an url

Parameters:

  • url (str) – The url to the mdl file

  • grounding_map (dict[str, Concept]) – A grounding map, a map from label to Concept

  • initials (dict[str, float]) – Explicit initial values to use for compartments in the model. Will overwrite model-internal definitions.

  • initials_from_integ (bool) – If true, gets initial values from INTEG expressions. If initials are given, they override anything from INTEG expressions

Return type:

TemplateModel

Returns:

A MIRA Template Model

Stella models (mira.sources.system_dynamics.stella)

This module implements an API interface for retrieving Stella models by ISEE Systems denoted by the .xmile, .xml, or .stmx extension through a locally downloaded file or URL. We cannot process stella models with the .itmx extension. Additionally, the PySD library depends on the parsimonious library which fails to parse a number of stella models with valid file extensions due to incompatible symbols and characters in equations for variables. We implemented preprocessing for stella models that fixes a number of these parsing errors when using PySD to ingest these models; however, a number of models still fail to be parsed by PySD’s “read_xmile” method. We extract the contents of the model as a string, perform expression preprocessing, and then convert the Stella model into a generic pysd model object that will be converted to an equivalent MIRA template model.

Landing page for Stella: https://www.iseesystems.com/store/products/stella-online.aspx

Website containing sample Stella models: https://www.vensim.com/documentation/sample_models.html

template_model_from_stella_model_file(fname)[source]

Return a template model from a local Stella model file

Parameters:

fname (str or pathlib.Path) – The path to the local Stella model file

Return type:

TemplateModel

Returns:

A MIRA template model

template_model_from_stella_model_url(url)[source]

Return a template model from a Stella model file provided by an url

Parameters:

url (str) – The url to the Stella model file

Return type:

TemplateModel

Returns:

A MIRA Template Model

template_model_stella_model_string(xml_str)[source]

Returns a semantically equivalent template model to the stella model represented by the xml string

Parameters:

xml_str (The contents of the Stella model) –

Return type:

TemplateModel

Returns:

A MIRA template model

PySD models (mira.sources.system_dynamics.pysd)

This module implements parsing of a generic pysd model irrespective of source and source type and extracting its contents to create an equivalent MIRA template model.

template_model_from_pysd_model(pysd_model, expression_map, *, grounding_map=None, initials_map=None)[source]

Given a model and its accompanying expression_map, extract information from the arguments to create an equivalent MIRA template model.

Parameters:

  • pysd_model (Model) – The pysd model object

  • expression_map (dict[str,str]) – Map of variable name to expression

  • grounding_map (dict[str, Concept]) – A grounding map, a map from label to Concept

  • initials_map (dict[str, float]) – A pre-populated mapping of initial values

Return type:

TemplateModel

Returns:

MIRA template model

SIF networks (mira.sources.sif)

This module provides functions to create a MIRA TemplateModel from a Simple Interaction Format (SIF) file. The SIF format is a simple space-delimited format where each line represents a relationship between two entities. The first column is the source node, the second column is the relation, and the third column is the target node. The relation is a string that represents the type of interaction between the source and target nodes. SIF files are useful as a minimal representation of regulatory networks with positive/negative regulation.

template_model_from_sif_edges(edges)[source]

Return TemplateModel from a list of SIF edges.

Parameters:

edges (list) – A list of tuples of the form (source, rel, target) where source and target are strings representing the source and target nodes and rel is a string representing the relation between them.

Returns:

A MIRA TemplateModel.

Return type:

TemplateModel

template_model_from_sif_file(fname)[source]

Return TemplateModel from a SIF file.

Parameters:

fname (str) – The path to the SIF file.

Returns:

A MIRA TemplateModel.

Return type:

TemplateModel

template_model_from_sif_url(url)[source]

Return TemplateModel from a SIF URL.

Parameters:

url (str) – The URL to the SIF file.

Returns:

A MIRA TemplateModel.

Return type:

TemplateModel

Utility Methods (mira.sources.util)

transition_to_templates(input_concepts, output_concepts, controller_concepts, transition_rate, transition_id, transition_name=None)[source]

Return a list of templates from a transition.

Parameters:

  • input_concepts (list[Concept]) – A list of Concepts serving as input to a transition.

  • output_concepts (list[Concept]) – A list of Concepts serving as output to a transition.

  • controller_concepts (list[Concept]) – A list of Concepts serving as controllers towards a transition.

  • transition_rate (sympy.Expr) – The rate law associated with the transition.

  • transition_id (str) – The id of the transition.

  • transition_name (str) – The name of the transition.

Returns:

A list containing Templates.

Return type:

list[Template]

get_sympy(expr_data, local_dict=None)[source]

Return a sympy expression from a dict with an expression or MathML.

Sympy string expressions are prioritized over MathML.

Parameters:

  • expr_data (Dict[str,Any]) – A dict with an expression and/or MathML.

  • local_dict (Dict[str, Any]) – A dict of local variables to use when parsing the expression.

Return type:

Optional[Expr]

Returns:

A sympy expression or None if no expression was found.

parameter_to_mira(parameter, param_symbols=None)[source]

Return a MIRA parameter from a mapping of MIRA Parameter attributes to values.

Parameters:

  • parameter (Dict[str,Any]) – A mapping containing MIRA Parameter attributes to values.

  • param_symbols (Optional[Dict]) – An optional dict of all parameter symbols that are needed if expressions are used in parameter distributions so that these can be recognized as symbols.

Return type:

Parameter

Returns:

The corresponding MIRA Parameter.