Merge pull request #265 from gyorilab/docs-update

Docs update

README.md

@@ -19,6 +19,14 @@ MIRA is a framework for representing systems using ontology-grounded **meta-mode
 * Using the MIRA Domain Knowledge Graph REST API: [Notebook 5](https://github.com/indralab/mira/blob/main/notebooks/dkg_api.ipynb)
 * Using the Model REST API to perform various model operations: [Notebook 6](https://github.com/indralab/mira/blob/main/notebooks/model_api.ipynb)
 * Using the web client in python that connects to the REST API: [Notebook 7](https://github.com/indralab/mira/blob/main/notebooks/web_client.ipynb)
+* Demonstrating MIRA TemplateModel capabilities [Notebook 8](https://github.com/gyorilab/mira/blob/main/notebooks/Hackathon%20Scenario%201.ipynb)
+* Rapid construction of DKGs in ASKEM: [Notebook 9](https://github.com/gyorilab/mira/blob/main/notebooks/Rapid%20construction%20of%20new%20DKGs.ipynb)
+* Implement a masking intervention in a compartmental model to simulate 
+  epidemic trajectories under different scenarios: 
+  [Notebook 10](https://github.com/gyorilab/mira/blob/main/notebooks/hackathon_2023.07/scenario1.ipynb)
+* Benchmarking the efficacy of DKG groundings on a set of COVID EPI Models: 
+  [Notebook 11](https://github.com/gyorilab/mira/blob/main/notebooks/hackathon_2023.10/Model%20Comparison.ipynb)
+
 
 [//]: # (Gromet Export fixme: uncomment when gromet works again)
 

docs/source/examples.rst

@@ -0,0 +1,22 @@
+Examples
+========
+
+This module contains examples of how to assemble and modify models in MIRA.
+
+Curated Example Models
+----------------------
+
+* `sir.py <https://github.com/gyorilab/mira/blob/main/mira/examples/sir.py>`_ - Simple examples of SIR epi models
+* `chime.py <https://github.com/gyorilab/mira/blob/main/mira/examples/chime.py>`_ -  Simple example of a SVIIvR epi model
+* `mech_bayes.py <https://github.com/gyorilab/mira/blob/main/mira/examples/mech_bayes.py>`_ A curated model describing the Mech Bayes model (an SEIRD epi model).
+* `nabi2021.py <https://github.com/gyorilab/mira/blob/main/mira/examples/nabi2021.py>`_ A curated model describing the Nabi et al. 2021 model (an 'SEIQAIRDL' epi model). See https://doi.org/10.1016/j.chaos.2021.110689 for more information.
+* `jin2022.py <https://github.com/gyorilab/mira/blob/main/mira/examples/jin2022.py>`_ A curated model describing the Jin et al. 2022 model, describing a vaccine-stratified epi model.
+
+
+Decapode Examples (:py:mod:`mira.examples.decapodes.decapodes_examples`)
+------------------------------------------------------------------------
+.. automodule:: mira.examples.decapodes.decapodes_examples
+   :members:
+   :show-inheritance:
+
+.. mdinclude:: ../../mira/examples/decapodes/decapodes_vs_decaexpr_composite/README.md

docs/source/index.rst

@@ -12,6 +12,7 @@ Table of Contents
    dkg
    metaregistry
    terarium_client
+   examples
 
 Indices and Tables
 ------------------

docs/source/metamodel.rst

@@ -14,7 +14,7 @@ Templates (:py:mod:`mira.metamodel.templates`)
 ----------------------------------------------
 .. automodule:: mira.metamodel.templates
     :members:
-    :exclude-members: Concept, ControlledConversion, NaturalConversion, Provenance, Template, NaturalDegradation, NaturalProduction, GroupedControlledConversion
+    :exclude-members: Concept
     :show-inheritance:
 
 Operations (:py:mod:`mira.metamodel.ops`)
@@ -58,3 +58,9 @@ Utilities (:py:mod:`mira.metamodel.utils`)
 .. automodule:: mira.metamodel.utils
    :members:
    :show-inheritance:
+
+Decapodes (:py:mod:`mira.metamodel.decapodes`)
+----------------------------------------------
+.. automodule:: mira.metamodel.decapodes
+   :members:
+   :show-inheritance:

docs/source/modeling.rst

@@ -1,29 +1,32 @@
 Modeling
 ========
+
+Modeling module (:py:mod:`mira.modeling`)
+-----------------------------------------
 .. automodule:: mira.modeling
     :members:
     :show-inheritance:
 
 ASKEM AMR Petri net generation (:py:mod:`mira.modeling.amr.petrinet`)
--------------------------------------------------------------------------
+---------------------------------------------------------------------
 .. automodule:: mira.modeling.amr.petrinet
     :members:
     :show-inheritance:
 
 ASKEM AMR Stockflow generation (:py:mod:`mira.modeling.amr.stockflow`)
--------------------------------------------------------------------------
+----------------------------------------------------------------------
 .. automodule:: mira.modeling.amr.stockflow
     :members:
     :show-inheritance:
 
 ASKEM AMR operations (:py:mod:`mira.modeling.amr.ops`)
-----------------------------------------------------------
+------------------------------------------------------
 .. automodule:: mira.modeling.amr.ops
     :members:
     :show-inheritance:
 
 ASKEM AMR Regulatory net generation (:py:mod:`mira.modeling.amr.regnet`)
-----------------------------------------------------------------------------
+------------------------------------------------------------------------
 .. automodule:: mira.modeling.amr.regnet
     :members:
     :show-inheritance:
@@ -41,13 +44,13 @@ ODE model generation and simulation (:py:mod:`mira.modeling.ode`)
     :show-inheritance:
 
 ACSets Petri net model generation (:py:mod:`mira.modeling.acsets.petri`)
------------------------------------------------------------------
+------------------------------------------------------------------------
 .. automodule:: mira.modeling.acsets.petri
     :members:
     :show-inheritance:
 
 ACSets Stockflow model generation (:py:mod:`mira.modeling.acsets.stockflow`)
------------------------------------------------------------------
+----------------------------------------------------------------------------
 .. automodule:: mira.modeling.acsets.stockflow
     :members:
     :show-inheritance:

docs/source/sources.rst

@@ -5,32 +5,32 @@ Sources of model content
     :show-inheritance:
 
 ASKEM AMR (:py:mod:`mira.sources.amr`)
-------------------------------------------
+--------------------------------------
 .. automodule:: mira.sources.amr
     :members:
     :show-inheritance:
 
 ASKEM AMR Petri nets (:py:mod:`mira.sources.amr.petrinet`)
---------------------------------------------------------------
+----------------------------------------------------------
 .. automodule:: mira.sources.amr.petrinet
     :members:
     :show-inheritance:
 
 ASKEM AMR Stockflow (:py:mod:`mira.sources.amr.stockflow`)
---------------------------------------------------------------
+----------------------------------------------------------
 .. automodule:: mira.sources.amr.stockflow
     :members:
     :show-inheritance:
 
 
 ASKEM AMR Regulatory nets (:py:mod:`mira.sources.amr.regnet`)
------------------------------------------------------------------
+-------------------------------------------------------------
 .. automodule:: mira.sources.amr.regnet
     :members:
-    :show-inherita
+    :show-inheritance:
 
 Reconstruct ODE semantics (:py:mod:`mira.sources.amr.flux_span`)
---------------------------------------------------------------------
+----------------------------------------------------------------
 .. automodule:: mira.sources.amr.flux_span
     :members:
     :show-inheritance:
@@ -45,6 +45,7 @@ BioModels client (:py:mod:`mira.sources.biomodels`)
 ---------------------------------------------------
 .. automodule:: mira.sources.biomodels
     :members:
+    :exclude-members: main
     :show-inheritance:
 
 Bilayer extraction (:py:mod:`mira.sources.bilayer`)
@@ -54,13 +55,31 @@ Bilayer extraction (:py:mod:`mira.sources.bilayer`)
     :show-inheritance:
 
 ACSets Petri Net extraction (:py:mod:`mira.sources.acsets.petri`)
-----------------------------------------------------------
+-----------------------------------------------------------------
 .. automodule:: mira.sources.acsets.petri
     :members:
     :show-inheritance:
 
 ACSets Stockflow extraction (:py:mod:`mira.sources.acsets.stockflow`)
-----------------------------------------------------------
+---------------------------------------------------------------------
 .. automodule:: mira.sources.acsets.stockflow
     :members:
     :show-inheritance:
+
+ACSets Decapodes extraction (:py:mod:`mira.sources.acsets.decapodes.decapodes`)
+-------------------------------------------------------------------------------
+.. automodule:: mira.sources.acsets.decapodes.decapodes
+    :members:
+    :show-inheritance:
+
+ACSets DecaExpr extraction (:py:mod:`mira.sources.acsets.decapodes.deca_expr`)
+------------------------------------------------------------------------------
+.. automodule:: mira.sources.acsets.decapodes.deca_expr
+    :members:
+    :show-inheritance:
+
+Utility Methods (:py:mod:`mira.sources.util`)
+---------------------------------------------
+.. automodule:: mira.sources.util
+    :members:
+    :show-inheritance:

mira/dkg/api.py

@@ -158,7 +158,6 @@ def get_transitive_closure(
     relation_types: List[str] = Query(
         ...,
         description="A list of relation types to get a transitive closure for",
-        title="This is a title",
         example=DKG_REFINER_RELS,
     ),
 ):
@@ -332,11 +331,17 @@ def get_relations(
 class IsOntChildResult(BaseModel):
     """Result of a query to /is_ontological_child"""
 
-    child_curie: str = Field(..., description="The child CURIE")
-    parent_curie: str = Field(..., description="The parent CURIE")
-    is_child: bool = Field(..., description="True if the child CURIE is an "
-                                            "ontological child of the parent "
-                                            "CURIE")
+    child_curie: str = Field(...,
+                             example="vo:0001113",
+                             description="The child CURIE")
+    parent_curie: str = Field(...,
+                              example="obi:0000047",
+                              description="The parent CURIE")
+    is_child: bool = Field(
+        ...,
+        description="True if the child CURIE is an ontological child of the "
+                    "parent CURIE"
+    )
 
 
 class IsOntChildQuery(BaseModel):
@@ -379,7 +384,7 @@ def is_ontological_child(
 )
 def search(
     request: Request,
-    q: str = Query(..., example="infect"),
+    q: str = Query(..., example="infect", description="The search query"),
     limit: int = 25,
     offset: int = 0,
     prefixes: Optional[str] = Query(
@@ -463,6 +468,7 @@ def entity_similarity(
     request: Request,
     sources: List[str] = Body(
         ...,
+        description="A list of CURIEs to use as sources",
         title="source CURIEs",
         examples=[["ido:0000511", "ido:0000592", "ido:0000597", "ido:0000514"]],
     ),

mira/dkg/model.py

@@ -21,7 +21,7 @@
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field
 
-from mira.examples.sir import sir_bilayer, sir, sir_parameterized_init
+from mira.examples.sir import sir_bilayer, sir, sir_parameterized_init, sir_2_city
 from mira.metamodel import (
     NaturalConversion, Template, ControlledConversion,
     stratify, Concept, ModelComparisonGraphdata, TemplateModelDelta,
@@ -90,6 +90,7 @@
 #: PetriNetModel json example
 petrinet_json = PetriNetModel(Model(sir)).to_pydantic()
 amr_petrinet_json = AMRPetriNetModel(Model(sir)).to_pydantic()
+amr_petrinet_json_2_city = AMRPetriNetModel(Model(sir_2_city)).to_pydantic()
 amr_petrinet_json_units_values = AMRPetriNetModel(
     Model(sir_parameterized_init)
 ).to_pydantic()
@@ -101,9 +102,9 @@
     tags=["modeling"],
     description=dedent("""\
         This endpoint consumes a JSON representation of a MIRA template model and converts
-        it into the ACSet standard for petri nets (implicitly defined `here <https://github.com/\
-        AlgebraicJulia/py-acsets/blob/main/src/acsets/petris.py>_), which can be used with the
-        Algebraic Julia ecosystem.
+        it into the ACSet standard for petri nets (implicitly defined 
+        [here](https://github.com/AlgebraicJulia/py-acsets/blob/main/src/acsets/petris.py)),
+        which can be used with the Algebraic Julia ecosystem.
         
         Note, this endpoint used to be called "/api/to_petrinet" but has been renamed as the ASKEM
         standard now uses that endpoint.
@@ -123,9 +124,10 @@ def model_to_petri(template_model: Dict[str, Any] = Body(..., example=template_m
     tags=["modeling"],
     response_model=TemplateModel,
     description=dedent("""\
-        This endpoint consumes a JSON representation of an `ACSet petri net <https://github.com/\
-        AlgebraicJulia/py-acsets/blob/main/src/acsets/petris.py>_ and produces a JSON representation
-        of a MIRA template model, which can be directly used with the MIRA ecosystem to do model
+        This endpoint consumes a JSON representation of an
+        [ACSet petri net](https://github.com/AlgebraicJulia/py-acsets/blob/main/src/acsets/petris.py)
+        and produces a JSON representation of a MIRA template model, 
+        which can be directly used with the MIRA ecosystem to do model
         extension, stratification, and comparison.
 
         Note, this endpoint used to be called "/api/from_petrinet" but has been renamed as the ASKEM
@@ -143,9 +145,10 @@ def petri_to_model(petri_json: Dict[str, Any] = Body(..., example=petrinet_json)
     tags=["modeling"],
     description=dedent("""\
         This endpoint consumes a JSON representation of a MIRA template model and converts
-        it into the `ASKEM standard for petri nets <https://github.com/DARPA-ASKEM/Model-\
-        Representations/blob/main/petrinet/petrinet_schema.json>_, which can be directly
-        consumed by other project members that implement this standard.
+        it into the
+        [ASKEM standard for petri nets](https://github.com/DARPA-ASKEM/Model-Representations/blob/main/petrinet/petrinet_schema.json),
+        which can be directly consumed by other project members that 
+        implement this standard.
     """.rstrip()),
 )
 def model_to_amr(template_model: Dict[str, Any] = Body(..., example=template_model_example)):
@@ -161,10 +164,11 @@ def model_to_amr(template_model: Dict[str, Any] = Body(..., example=template_mod
     tags=["modeling"],
     response_model=TemplateModel,
     description=dedent("""\
-        This endpoint consumes a JSON representation of an `ASKEM petri net <https://github.\
-        com/DARPA-ASKEM/Model-Representations/blob/main/petrinet/petrinet_schema.json>_ and
-        produces a JSON representation of a MIRA template model, which can be directly used
-        with the MIRA ecosystem to do model extension, stratification, and comparison. 
+        This endpoint consumes a JSON representation of an
+        [ASKEM petri net](https://github.com/DARPA-ASKEM/Model-Representations/blob/main/petrinet/petrinet_schema.json)
+        and produces a JSON representation of a MIRA template model, 
+        which can be directly used with the MIRA ecosystem to do model 
+        extension, stratification, and comparison.
     """.rstrip()),
 )
 def amr_to_model(amr_json: Dict[str, Any] = Body(..., example=amr_petrinet_json)):
@@ -638,9 +642,10 @@ def add_transition(
         ...,
         example={
             "template_model": template_model_example,
-            "subject_concept": "<Add concept example>",
-            "object_concept": "<Add concept example>",
-            "parameter": "<Add parameter example>",
+            "subject_concept": {"name": "infected population",
+                                "identifiers": {"ido": "0000511"}},
+            "outcome_concept": {"name": "dead",
+                                "identifiers": {"ncit": "C28554"}},
         },
     )
 ):
@@ -695,9 +700,7 @@ def model_comparison(
 
 class AMRComparisonQuery(BaseModel):
     petrinet_models: List[Dict[str, Any]] = Field(
-        ..., example=[  # fixme: create more examples
-            amr_petrinet_json,
-        ]
+        ..., example=[amr_petrinet_json, amr_petrinet_json_2_city]
     )
 
 

mira/dkg/wsgi.py

@@ -69,7 +69,7 @@
     ),
     contact={
         "name": "Benjamin M. Gyori",
-        "email": "[email protected].edu",
+        "email": "b.gyori@northeastern.edu",
     },
     license_info={
         "name": "BSD-2-Clause license",

mira/examples/chime.py

@@ -1,4 +1,4 @@
-"""CHIME SVIIvR."""
+"""CHIME SVIIvR epi model."""
 
 from mira.metamodel import NaturalConversion, ControlledConversion, \
     TemplateModel