From 6447e38682ece84be555f21469055fe7a5886568 Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 15:32:28 -0700 Subject: [PATCH 01/20] WIP add dkg module to docs --- docs/source/dkg.rst | 41 +++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/source/dkg.rst diff --git a/docs/source/dkg.rst b/docs/source/dkg.rst new file mode 100644 index 000000000..18f0356c8 --- /dev/null +++ b/docs/source/dkg.rst @@ -0,0 +1,41 @@ +Domain Knowledge Graph +====================== +.. automodule:: mira.dkg + :members: + :show-inheritance: + +Client (:py:mod:`mira.dkg.client`) +---------------------------------- +.. automodule:: mira.dkg.client + :members: + :show-inheritance: + +Construct (:py:mod:`mira.dkg.construct`) +---------------------------------------- +.. automodule:: mira.dkg.construct + :members: + :show-inheritance: + +API (:py:mod:`mira.dkg.construct_registry`) +------------------------------------------- +.. automodule:: mira.dkg.construct_registry + :members: + :show-inheritance: + +API (:py:mod:`mira.dkg.models`) +------------------------------- +.. automodule:: mira.dkg.models + :members: + :show-inheritance: + +API (:py:mod:`mira.dkg.utils`) +------------------------------ +.. automodule:: mira.dkg.utils + :members: + :show-inheritance: + +API (:py:mod:`mira.dkg.web_client`) +----------------------------------- +.. automodule:: mira.dkg.web_client + :members: + :show-inheritance: diff --git a/docs/source/index.rst b/docs/source/index.rst index c12d42c4b..38cbdbef0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,6 +8,7 @@ Table of Contents overview metamodel modeling + dkg Indices and Tables ------------------ From e290222f07e46c21e279e2c1d6aa26a7b7c1fdf4 Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 15:33:00 -0700 Subject: [PATCH 02/20] Add web_client to all so it appears in docs --- mira/dkg/web_client.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mira/dkg/web_client.py b/mira/dkg/web_client.py index 1d913a551..b78851ab8 100644 --- a/mira/dkg/web_client.py +++ b/mira/dkg/web_client.py @@ -8,6 +8,7 @@ from mira.dkg.utils import DKG_REFINER_RELS __all__ = [ + "web_client", "get_relations_web", "get_entity_web", "get_lexical_web", From b105102b8257f166c3918083f768535be65a103a Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 15:33:52 -0700 Subject: [PATCH 03/20] Add constant comment in utils.py --- mira/dkg/utils.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mira/dkg/utils.py b/mira/dkg/utils.py index bcec4f214..3b14b6e3a 100644 --- a/mira/dkg/utils.py +++ b/mira/dkg/utils.py @@ -21,6 +21,7 @@ class MiraState: grounder: Grounder +#: A list of all prefixes used in MIRA PREFIXES = [ # meta "oboinowl", From 7e8033fc507ca377b6a3cfc98598934ded6712cc Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 15:41:37 -0700 Subject: [PATCH 04/20] Set proper titles --- docs/source/dkg.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/dkg.rst b/docs/source/dkg.rst index 18f0356c8..54a62cc99 100644 --- a/docs/source/dkg.rst +++ b/docs/source/dkg.rst @@ -16,26 +16,26 @@ Construct (:py:mod:`mira.dkg.construct`) :members: :show-inheritance: -API (:py:mod:`mira.dkg.construct_registry`) -------------------------------------------- +Constructing Registry (:py:mod:`mira.dkg.construct_registry`) +------------------------------------------------------------- .. automodule:: mira.dkg.construct_registry :members: :show-inheritance: -API (:py:mod:`mira.dkg.models`) -------------------------------- +Configuarition Models (:py:mod:`mira.dkg.models`) +------------------------------------------------- .. automodule:: mira.dkg.models :members: :show-inheritance: -API (:py:mod:`mira.dkg.utils`) ------------------------------- +App Utilities(:py:mod:`mira.dkg.utils`) +--------------------------------------- .. automodule:: mira.dkg.utils :members: :show-inheritance: -API (:py:mod:`mira.dkg.web_client`) ------------------------------------ +Web Client (:py:mod:`mira.dkg.web_client`) +------------------------------------------ .. automodule:: mira.dkg.web_client :members: :show-inheritance: From 98d528b5b38ec6d06f433d5f63c74ebf150a1893 Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 15:49:21 -0700 Subject: [PATCH 05/20] Add metaregistry submodule --- docs/source/index.rst | 1 + docs/source/metaregistry.rst | 11 +++++++++++ 2 files changed, 12 insertions(+) create mode 100644 docs/source/metaregistry.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 38cbdbef0..edb7dc708 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,6 +9,7 @@ Table of Contents metamodel modeling dkg + metaregistry Indices and Tables ------------------ diff --git a/docs/source/metaregistry.rst b/docs/source/metaregistry.rst new file mode 100644 index 000000000..0d00a6fe6 --- /dev/null +++ b/docs/source/metaregistry.rst @@ -0,0 +1,11 @@ +Metaregistry +============ +.. automodule:: mira.dkg.metaregistry + :members: + :show-inheritance: + +Metaregistry Utils (:py:mod:`mira.dkg.metaregistry.utils`) +---------------------------------------------------------- +.. automodule:: mira.dkg.metaregistry.utils + :members: + :show-inheritance: From 6c3bbbe2c858257d7103cdd4d1761a9c207dab6c Mon Sep 17 00:00:00 2001 From: kkaris Date: Wed, 21 Sep 2022 16:05:38 -0700 Subject: [PATCH 06/20] Add docstrings in templates.py --- mira/metamodel/templates.py | 58 +++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/mira/metamodel/templates.py b/mira/metamodel/templates.py index 49f4a6672..993bc184d 100644 --- a/mira/metamodel/templates.py +++ b/mira/metamodel/templates.py @@ -126,8 +126,7 @@ def refinement_of( refinement_func : A function that given a source/more detailed entity and a target/less detailed entity checks if they are in a child-parent and - returns a boolean. If not provided, the default - ``mira.dkg.web_client.is_ontological_child`` is used. + returns a boolean. Returns ------- @@ -169,6 +168,21 @@ def from_json(cls, data) -> "Template": return stmt_cls(**data) def is_equal_to(self, other: "Template", with_context: bool = False) -> bool: + """Check if this template is equal to another template + + Parameters + ---------- + other : + The other template to check for equality with this one with + with_context : + If True, the contexts are taken into account when checking for + equality. Default: False. + + Returns + ------- + : + True if the other Template is equal to this Template + """ if not isinstance(other, Template): return False return templates_equal(self, other, with_context) @@ -179,7 +193,26 @@ def refinement_of( refinement_func: Callable[[str, str], bool], with_context: bool = False, ) -> bool: - """Check if this template is a more detailed version of another""" + """Check if this template is a more detailed version of another + + Parameters + ---------- + other : + The other template to compare with. Is assumed to be less + detailed than this template. + with_context : + If True, also consider the context of Templates' Concepts for the + refinement. + refinement_func : + A function that given a source/more detailed entity and a + target/less detailed entity checks if they are in a child-parent + relationship and returns a boolean. + + Returns + ------- + : + True if this Template is a refinement of the other Template. + """ if not isinstance(other, Template): return False @@ -226,6 +259,7 @@ class ControlledConversion(Template): provenance: List[Provenance] = Field(default_factory=list) def with_context(self, **context) -> "ControlledConversion": + """Return a copy of this template with context added""" return self.__class__( type=self.type, subject=self.subject.with_context(**context), @@ -250,6 +284,7 @@ class NaturalConversion(Template): provenance: List[Provenance] = Field(default_factory=list) def with_context(self, **context) -> "NaturalConversion": + """Return a copy of this template with context added""" return self.__class__( type=self.type, subject=self.subject.with_context(**context), @@ -282,6 +317,23 @@ def get_json_schema(): def templates_equal(templ: Template, other_templ: Template, with_context: bool) -> bool: + """Check if two Template objects are equal + + Parameters + ---------- + templ : + A template to compare. + other_templ : + The other template to compare. + with_context : + If True, also check the contexts of the contained Concepts of the + Template. + + Returns + ------- + : + True if the two Template objects are equal. + """ if templ.type != other_templ.type: return False From cc36ca86fd9997ae05cd36d87118e1a78cc63b0e Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 08:58:50 -0700 Subject: [PATCH 07/20] Set correct code highlighting --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e398244b0..6672d5ebc 100644 --- a/README.md +++ b/README.md @@ -30,13 +30,13 @@ MIRA builds on and generalizes prior work including: The most recent code and data can be installed directly from GitHub with: -```python +```shell python -m pip install git+https://github.com/indralab/mira.git ``` To install in development mode, use the following: -```python +```shell git clone git+https://github.com/indralab/mira.git cd mira python -m pip install -e . From ab139c51f9d7e914a79080d126c4b99cf90db8e9 Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 09:06:57 -0700 Subject: [PATCH 08/20] Add missing notebooks to list --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 6672d5ebc..62a0cb358 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ MIRA is a framework for representing systems using ontology-grounded **meta-mode * Generating an executable model from MIRA Templates and running simulation: [Notebook 2](https://github.com/indralab/mira/blob/main/notebooks/simulation.ipynb) * Stratifying and visualizing MIRA models, and exporting as Petri nets: [Notebook 3](https://github.com/indralab/mira/blob/main/notebooks/viz_strat_petri.ipynb) * Using the MIRA Domain Knowledge Graph REST API: [Notebook 4](https://github.com/indralab/mira/blob/main/notebooks/dkg_api.ipynb) +* Using the Model REST API to perform various model operations: [Notebook 5](https://github.com/indralab/mira/blob/main/notebooks/model_api.ipynb) +* Using the web client in python that connects to the REST API: [Notebook 6](https://github.com/indralab/mira/blob/main/notebooks/web_client.ipynb) + +[//]: # (Gromet Export fixme: uncomment when gromet works again) ## Related work From 7a5dc69486efdcd7e703a89635f71d6b7e7ecb40 Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 09:34:45 -0700 Subject: [PATCH 09/20] Fix spelling --- docs/source/dkg.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/dkg.rst b/docs/source/dkg.rst index 54a62cc99..4e82fcd29 100644 --- a/docs/source/dkg.rst +++ b/docs/source/dkg.rst @@ -22,8 +22,8 @@ Constructing Registry (:py:mod:`mira.dkg.construct_registry`) :members: :show-inheritance: -Configuarition Models (:py:mod:`mira.dkg.models`) -------------------------------------------------- +Configuration Models (:py:mod:`mira.dkg.models`) +------------------------------------------------ .. automodule:: mira.dkg.models :members: :show-inheritance: From aa824f6c3b6c49d75be386bca603670d93d3866b Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 10:15:44 -0700 Subject: [PATCH 10/20] Extend docs environment --- tox.ini | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tox.ini b/tox.ini index 93aebef8c..16b201a78 100644 --- a/tox.ini +++ b/tox.ini @@ -23,6 +23,10 @@ commands = extras = docs ode + dkg-client + dkg-construct + metaregistry + web commands = python -m sphinx -b {posargs:html} -d docs/build/doctrees docs/source docs/build/{posargs:html} From f2c114e3bee14f199218cf33c6db6d320094f233 Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 10:29:59 -0700 Subject: [PATCH 11/20] Temporarily add wget as dependency --- setup.cfg | 2 ++ 1 file changed, 2 insertions(+) diff --git a/setup.cfg b/setup.cfg index ad369d30f..dfc30f278 100644 --- a/setup.cfg +++ b/setup.cfg @@ -72,6 +72,8 @@ docs = autodoc-pydantic m2r2 pygraphviz + wget +; fixme: docs do not build completely without wget, yet it's not made available to the environment by the packages that need it [mypy] plugins = pydantic.mypy From 950ea6283a58c5ff4778e84bc099f4bc2556ffaa Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 11:13:22 -0700 Subject: [PATCH 12/20] Add docstrings to models so they show up in the docs --- mira/metamodel/templates.py | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/mira/metamodel/templates.py b/mira/metamodel/templates.py index 993bc184d..cacf8a2d2 100644 --- a/mira/metamodel/templates.py +++ b/mira/metamodel/templates.py @@ -3,7 +3,16 @@ Regenerate the JSON schema by running ``python -m mira.metamodel.templates``. """ -__all__ = ["Concept", "Template", "Provenance", "ControlledConversion", "NaturalConversion"] +__all__ = [ + "Concept", + "Template", + "Provenance", + "ControlledConversion", + "NaturalConversion", + "get_json_schema", + "templates_equal", + "assert_concept_context_refinement", +] import json import logging @@ -22,6 +31,8 @@ class Config(BaseModel): + """Config determining how keys are generated""" + prefix_priority: List[str] @@ -33,6 +44,10 @@ class Config(BaseModel): class Concept(BaseModel): + """A concept is specified by its identifier(s), name, and - optionally - + its context. + """ + name: str = Field(..., description="The name of the concept.") identifiers: Mapping[str, str] = Field( default_factory=dict, description="A mapping of namespaces to identifiers." @@ -161,6 +176,8 @@ def refinement_of( class Template(BaseModel): + """The Template is a parent class for model processes""" + @classmethod def from_json(cls, data) -> "Template": template_type = data.pop("type") @@ -252,6 +269,9 @@ class Provenance(BaseModel): class ControlledConversion(Template): + """Specifies a process of controlled conversion from subject to outcome, + controlled by the controller""" + type: Literal["ControlledConversion"] = Field("ControlledConversion", const=True) controller: Concept subject: Concept @@ -278,6 +298,8 @@ def get_key(self, config: Optional[Config] = None): class NaturalConversion(Template): + """Specifies a process of natural conversion from subject to outcome""" + type: Literal["NaturalConversion"] = Field("NaturalConversion", const=True) subject: Concept outcome: Concept From 2493bfd61422d461b4c8fa822b0c57349c9de575 Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 11:13:48 -0700 Subject: [PATCH 13/20] Activate autodoc-pydantic --- docs/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2bd6317bd..12c333932 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -67,6 +67,7 @@ "sphinx_autodoc_typehints", "sphinx_automodapi.automodapi", "sphinx_automodapi.smart_resolver", + "sphinxcontrib.autodoc_pydantic", "m2r2", ] From 6cfbb61255c3b8de8706bee42b76ddfc5d67b74e Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 11:14:25 -0700 Subject: [PATCH 14/20] Update meta-model to full documentation --- docs/source/metamodel.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/source/metamodel.rst b/docs/source/metamodel.rst index 125a2dd73..7fc9008ac 100644 --- a/docs/source/metamodel.rst +++ b/docs/source/metamodel.rst @@ -1,4 +1,12 @@ Meta-model ========== +.. automodule:: mira.metamodel + :members: + :show-inheritance: -.. automodapi:: mira.metamodel.templates +Templates (:py:mod:`mira.metamodel.templates`) +---------------------------------------------- +.. automodule:: mira.metamodel.templates + :members: + :exclude-members: Concept, ControlledConversion, NaturalConversion, Provenance, Template + :show-inheritance: From d1dd03d8e7d1b9bdbad514e6a4841c965d77d699 Mon Sep 17 00:00:00 2001 From: Ben Gyori Date: Thu, 22 Sep 2022 15:35:00 -0400 Subject: [PATCH 15/20] Update schema --- mira/metamodel/schema.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mira/metamodel/schema.json b/mira/metamodel/schema.json index 31ef6e235..b99452263 100644 --- a/mira/metamodel/schema.json +++ b/mira/metamodel/schema.json @@ -6,6 +6,7 @@ "definitions": { "Concept": { "title": "Concept", + "description": "A concept is specified by its identifier(s), name, and - optionally -\nits context.", "type": "object", "properties": { "name": { @@ -36,6 +37,7 @@ }, "Template": { "title": "Template", + "description": "The Template is a parent class for model processes", "type": "object", "properties": {} }, @@ -46,6 +48,7 @@ }, "NaturalConversion": { "title": "NaturalConversion", + "description": "Specifies a process of natural conversion from subject to outcome", "type": "object", "properties": { "type": { @@ -78,6 +81,7 @@ }, "ControlledConversion": { "title": "ControlledConversion", + "description": "Specifies a process of controlled conversion from subject to outcome,\ncontrolled by the controller", "type": "object", "properties": { "type": { From 9fb5657d75aef82ff311eb8bd1eeac09bcc9b172 Mon Sep 17 00:00:00 2001 From: Ben Gyori Date: Thu, 22 Sep 2022 15:38:16 -0400 Subject: [PATCH 16/20] Add missing space --- docs/source/dkg.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/dkg.rst b/docs/source/dkg.rst index 4e82fcd29..bbc1308ee 100644 --- a/docs/source/dkg.rst +++ b/docs/source/dkg.rst @@ -28,8 +28,8 @@ Configuration Models (:py:mod:`mira.dkg.models`) :members: :show-inheritance: -App Utilities(:py:mod:`mira.dkg.utils`) ---------------------------------------- +App Utilities (:py:mod:`mira.dkg.utils`) +---------------------------------------- .. automodule:: mira.dkg.utils :members: :show-inheritance: From 885bb1a4c5a92f3d547d12001f90d203cfbbeb6f Mon Sep 17 00:00:00 2001 From: kkaris Date: Thu, 22 Sep 2022 16:29:37 -0700 Subject: [PATCH 17/20] WIP Try to mock some packages --- docs/source/conf.py | 14 ++++++++++++++ setup.cfg | 2 +- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 12c333932..5ad2e4305 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,7 @@ import os import re import sys +import mock from datetime import date sys.path.insert(0, os.path.abspath("../..")) @@ -236,3 +237,16 @@ # Don't sort alphabetically, explained at: # https://stackoverflow.com/questions/37209921/python-how-not-to-sort-sphinx-output-in-alphabetical-order autodoc_member_order = "bysource" + +MOCK_MODULES = [ + "neo4j", + "neo4j.graph", + "bioontologies", + "bioontologies.obograph", + "bioregistry", + "bioregistry.app", + "bioregistry.app.impl", +] + +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = mock.Mock() diff --git a/setup.cfg b/setup.cfg index dfc30f278..151f03a53 100644 --- a/setup.cfg +++ b/setup.cfg @@ -72,8 +72,8 @@ docs = autodoc-pydantic m2r2 pygraphviz + mock wget -; fixme: docs do not build completely without wget, yet it's not made available to the environment by the packages that need it [mypy] plugins = pydantic.mypy From 2cf304e6681afb71db8a9788139503bb9a5aeee6 Mon Sep 17 00:00:00 2001 From: Ben Gyori Date: Thu, 22 Sep 2022 22:21:54 -0400 Subject: [PATCH 18/20] Add extras to readthedocs conf --- .readthedocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 7c0b59382..f6e293031 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -13,3 +13,7 @@ python: extra_requirements: - docs - ode + - dkg-client + - dkg-construct + - metaregistry + - web From c223e5b3ee13d382cf015b124f40808660908086 Mon Sep 17 00:00:00 2001 From: Ben Gyori Date: Thu, 22 Sep 2022 22:25:51 -0400 Subject: [PATCH 19/20] Fix type annotation --- mira/dkg/construct.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mira/dkg/construct.py b/mira/dkg/construct.py index 66840a01e..6cb3f17c2 100644 --- a/mira/dkg/construct.py +++ b/mira/dkg/construct.py @@ -39,7 +39,7 @@ EDGES_PATH = DEMO_MODULE.join(name="edges.tsv.gz") METAREGISTRY_PATH = DEMO_MODULE.join(name="metaregistry.json") OBSOLETE = {"oboinowl:ObsoleteClass", "oboinowl:ObsoleteProperty"} -EDGES_PATHS: dict[str, Path] = { +EDGES_PATHS: Dict[str, Path] = { prefix: DEMO_MODULE.join("sources", name=f"edges_{prefix}.tsv") for prefix in PREFIXES } EDGE_HEADER = ( From c306a5d8759c501104024a46ea00723edd907c7b Mon Sep 17 00:00:00 2001 From: Ben Gyori Date: Thu, 22 Sep 2022 22:36:31 -0400 Subject: [PATCH 20/20] Try installing some dependencies --- docs/source/conf.py | 10 +++++----- setup.cfg | 2 ++ 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5ad2e4305..41bbe9ff3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -241,11 +241,11 @@ MOCK_MODULES = [ "neo4j", "neo4j.graph", - "bioontologies", - "bioontologies.obograph", - "bioregistry", - "bioregistry.app", - "bioregistry.app.impl", + #"bioontologies", + #"bioontologies.obograph", + #"bioregistry", + #"bioregistry.app", + #"bioregistry.app.impl", ] for mod_name in MOCK_MODULES: diff --git a/setup.cfg b/setup.cfg index 151f03a53..9244a95c5 100644 --- a/setup.cfg +++ b/setup.cfg @@ -65,6 +65,8 @@ uvicorn = gunicorn = gunicorn docs = + bioregistry + bioontologies sphinx sphinx-rtd-theme sphinx-autodoc-typehints