epimodelstudio 0.11.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- epimodelstudio/__init__.py +7 -0
- epimodelstudio/__main__.py +38 -0
- epimodelstudio/advisor.py +214 -0
- epimodelstudio/analysis.py +528 -0
- epimodelstudio/backward.py +102 -0
- epimodelstudio/bundle.py +70 -0
- epimodelstudio/categories.py +51 -0
- epimodelstudio/cite.py +84 -0
- epimodelstudio/diagram.py +216 -0
- epimodelstudio/evidence.py +549 -0
- epimodelstudio/glossary.py +184 -0
- epimodelstudio/latex.py +239 -0
- epimodelstudio/layout_editor.py +116 -0
- epimodelstudio/literature.py +179 -0
- epimodelstudio/lyapunov.py +57 -0
- epimodelstudio/metrics.py +291 -0
- epimodelstudio/model.py +125 -0
- epimodelstudio/plain.py +276 -0
- epimodelstudio/report.py +477 -0
- epimodelstudio/repro.py +220 -0
- epimodelstudio/results.py +38 -0
- epimodelstudio/safeparse.py +135 -0
- epimodelstudio/settings.py +21 -0
- epimodelstudio/summary.py +67 -0
- epimodelstudio/templates.py +672 -0
- epimodelstudio/units.py +405 -0
- epimodelstudio/validate.py +178 -0
- epimodelstudio/verify.py +226 -0
- epimodelstudio-0.11.0.dist-info/METADATA +125 -0
- epimodelstudio-0.11.0.dist-info/RECORD +38 -0
- epimodelstudio-0.11.0.dist-info/WHEEL +5 -0
- epimodelstudio-0.11.0.dist-info/licenses/LICENSE.txt +22 -0
- epimodelstudio-0.11.0.dist-info/top_level.txt +2 -0
- epimodelstudio_api/__init__.py +6 -0
- epimodelstudio_api/__main__.py +29 -0
- epimodelstudio_api/app.py +250 -0
- epimodelstudio_api/config.py +30 -0
- epimodelstudio_api/jobs.py +255 -0
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
from .model import Model, Flow
|
|
2
|
+
from .templates import TEMPLATES
|
|
3
|
+
from .report import run, analyse
|
|
4
|
+
from .layout_editor import export_editor, apply_layout
|
|
5
|
+
from .validate import ModelError
|
|
6
|
+
from .repro import save_model, load_model, model_hash
|
|
7
|
+
from .settings import ENGINE_VERSION
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Command line: python -m epimodelstudio <command> ...
|
|
2
|
+
templates list the built-in models
|
|
3
|
+
template NAME [file.json] write a built-in model to a model file (default NAME.json)
|
|
4
|
+
run model.json [outdir] analyse a model file and write the report (HTML, LaTeX, PDF, model.json, run_record.json)
|
|
5
|
+
reproduce <run folder> rerun the analysis stored in a run folder and compare it with its run record
|
|
6
|
+
"""
|
|
7
|
+
import sys
|
|
8
|
+
from . import TEMPLATES, load_model, save_model, run, ModelError
|
|
9
|
+
from .repro import reproduce
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def main(argv):
|
|
13
|
+
for stream in (sys.stdout, sys.stderr): # Windows consoles often default to a legacy code page that cannot print the maths symbols
|
|
14
|
+
if hasattr(stream, "reconfigure"):
|
|
15
|
+
stream.reconfigure(encoding="utf-8", errors="replace")
|
|
16
|
+
if not argv or argv[0] in ("-h", "--help"):
|
|
17
|
+
print(__doc__); return 0
|
|
18
|
+
cmd, args = argv[0], argv[1:]
|
|
19
|
+
try:
|
|
20
|
+
if cmd == "templates":
|
|
21
|
+
print("\n".join(sorted(TEMPLATES))); return 0
|
|
22
|
+
if cmd == "template" and args:
|
|
23
|
+
if args[0] not in TEMPLATES: print(f"unknown template {args[0]!r}; try: python -m epimodelstudio templates"); return 2
|
|
24
|
+
print("wrote", save_model(TEMPLATES[args[0]](), args[1] if len(args) > 1 else args[0] + ".json")); return 0
|
|
25
|
+
if cmd == "run" and args:
|
|
26
|
+
m = load_model(args[0]); out = args[1] if len(args) > 1 else "out"
|
|
27
|
+
r = run(m, out); print(f"report written to {out}/ (PDF {'ok' if r['pdf_ok'] else 'not built'})"); return 0
|
|
28
|
+
if cmd == "reproduce" and args:
|
|
29
|
+
res = reproduce(args[0]); print(res["status"])
|
|
30
|
+
for d in res["differences"]: print(" -", d)
|
|
31
|
+
return 0 if res["status"] == "REPRODUCED" else 1
|
|
32
|
+
except ModelError as e:
|
|
33
|
+
print("Model error:", e); return 2
|
|
34
|
+
print(__doc__); return 2
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
if __name__ == "__main__":
|
|
38
|
+
sys.exit(main(sys.argv[1:]))
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
"""Questionnaire advisor: from a few plain questions to two or three starting models from the library.
|
|
2
|
+
|
|
3
|
+
Library-only by design: it never invents a model. Each library model has a profile (what it assumes); the answers are compared
|
|
4
|
+
with the profiles by a transparent rules table, and every suggestion says what matched and what differs, so the researcher
|
|
5
|
+
knows what to edit. The suggestion is a starting point, never a verdict about the disease.
|
|
6
|
+
"""
|
|
7
|
+
from . import evidence as EV
|
|
8
|
+
from . import templates as T
|
|
9
|
+
from . import glossary as G
|
|
10
|
+
|
|
11
|
+
# ---------------------------------------------------------------- questions (id, text, options, glossary terms shown with it)
|
|
12
|
+
QUESTIONS = [
|
|
13
|
+
dict(id="pathway", text="How does the infection mainly spread?", terms=["force_of_infection", "vector_host"],
|
|
14
|
+
options=[("direct", "From person to person (contact, air, droplets)"),
|
|
15
|
+
("vector", "Through a carrier species such as a mosquito (a vector)"),
|
|
16
|
+
("environment", "From the environment: water, soil, spores or carcasses"),
|
|
17
|
+
("both", "Both person to person and through the environment (for example water)")]),
|
|
18
|
+
dict(id="latent", text="Is there a delay between catching the infection and being able to pass it on?", terms=["infected_compartment"],
|
|
19
|
+
options=[("none", "No, or the delay is negligible"),
|
|
20
|
+
("short", "Yes, one exposed (latent) period"),
|
|
21
|
+
("staged", "Yes, and the delay is not exponential: it is better described in several stages")]),
|
|
22
|
+
dict(id="immunity", text="What happens after recovery?", terms=["compartment"],
|
|
23
|
+
options=[("lifelong", "Lasting immunity"),
|
|
24
|
+
("temporary", "Immunity that fades, so people become susceptible again"),
|
|
25
|
+
("partial", "Partial immunity: reinfection is possible but less likely"),
|
|
26
|
+
("none", "No immunity: people are susceptible again at once")]),
|
|
27
|
+
dict(id="vaccine", text="Do you need to include vaccination that is imperfect (it does not always protect)?", terms=["compartment"],
|
|
28
|
+
options=[("no", "No"), ("yes", "Yes")]),
|
|
29
|
+
dict(id="population", text="Over what time span do you want to study it?", terms=["open_closed", "demography"],
|
|
30
|
+
options=[("closed", "One outbreak, short enough to ignore births and deaths"),
|
|
31
|
+
("open", "Long term, so births and deaths matter")]),
|
|
32
|
+
dict(id="features", text="Does your question involve any of these (choose any)?", multi=True, terms=["incidence", "bifurcation"],
|
|
33
|
+
options=[("disease_death", "Deaths caused by the disease"),
|
|
34
|
+
("saturation", "Transmission that levels off at high infection (crowding, behaviour change)"),
|
|
35
|
+
("reinfection", "Reinfection of people who already had the disease"),
|
|
36
|
+
("oscillation", "Repeated waves or cycles (periodic behaviour)"),
|
|
37
|
+
("backward", "Whether control must push R0 well below 1 (backward bifurcation)"),
|
|
38
|
+
("quarantine", "Isolation or quarantine of some infected people")]),
|
|
39
|
+
]
|
|
40
|
+
_Q = {q["id"]: q for q in QUESTIONS}
|
|
41
|
+
_VALUES = {q["id"]: {o[0] for o in q["options"]} for q in QUESTIONS}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def questions():
|
|
45
|
+
"""The questionnaire as served to the client (options as objects, glossary ids to show beside each question)."""
|
|
46
|
+
return [dict(id=q["id"], text=q["text"], multi=bool(q.get("multi")), terms=q["terms"],
|
|
47
|
+
options=[dict(value=v, label=l) for v, l in q["options"]]) for q in QUESTIONS]
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
# ---------------------------------------------------------------- what each library model assumes
|
|
51
|
+
def _p(pathway, latent, immunity, population, vaccine=False, features=(), source=""):
|
|
52
|
+
return dict(pathway=set(pathway), latent=latent, immunity=immunity, population=population, vaccine=vaccine,
|
|
53
|
+
features=set(features), source=source)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
_HZS = "Hethcote, Zhien & Shengbing (2002), Math. Biosci. 180:141-160"
|
|
57
|
+
PROFILES = dict(
|
|
58
|
+
sir_closed=_p({"direct"}, "none", "lifelong", "closed", source="Kermack & McKendrick (1927)"),
|
|
59
|
+
sir_demography=_p({"direct"}, "none", "lifelong", "open", source="Hethcote (2000), The mathematics of infectious diseases"),
|
|
60
|
+
seir_demography=_p({"direct"}, "short", "lifelong", "open", source="Hethcote (2000), The mathematics of infectious diseases"),
|
|
61
|
+
erlang_seir=_p({"direct"}, "staged", "lifelong", "open", source="Wearing, Rohani & Keeling (2005), PLoS Med 2:e174"),
|
|
62
|
+
sis_vaccination=_p({"direct"}, "none", "none", "open", vaccine=True, features={"backward"},
|
|
63
|
+
source="Kribs-Zaleta & Velasco-Hernandez (2000); Arino et al. (2004)"),
|
|
64
|
+
tb_feng_exogenous=_p({"direct"}, "staged", "partial", "open", features={"reinfection", "disease_death", "backward"},
|
|
65
|
+
source="Feng, Castillo-Chavez & Capurro, Theor. Popul. Biol. 57 (2000)"),
|
|
66
|
+
tb_reinfection=_p({"direct"}, "staged", "partial", "open", features={"reinfection", "disease_death", "backward"},
|
|
67
|
+
source="Wangari & Stone, PLoS ONE 13(3):e0194256 (2018)"),
|
|
68
|
+
sirs_diff_mortality=_p({"direct"}, "none", "temporary", "open", features={"disease_death"}, source="arXiv:1112.2662"),
|
|
69
|
+
sirs_saturated_incidence=_p({"direct"}, "none", "temporary", "open", features={"saturation", "disease_death"},
|
|
70
|
+
source="Nonlinear Analysis paper, system (1)"),
|
|
71
|
+
sirs_nonlinear_hopf=_p({"direct"}, "none", "temporary", "open", features={"saturation", "oscillation"},
|
|
72
|
+
source="Tang, Huang, Ruan & Zhang, SIAM J. Appl. Math. 69 (2008)"),
|
|
73
|
+
cholera_tien_earn=_p({"direct", "environment"}, "none", "lifelong", "open", source="Tien & Earn (2010), Bull. Math. Biol. 72:1506-1533"),
|
|
74
|
+
cholera_two_pathways=_p({"direct", "environment"}, "none", "lifelong", "open", source="Tien & Earn (2010); van den Driessche (2017)"),
|
|
75
|
+
anthrax=_p({"environment"}, "none", "none", "open", features={"disease_death"}, source="van den Driessche (2017), Sec. 7"),
|
|
76
|
+
ross_macdonald=_p({"vector"}, "none", "none", "open", source="Iiyambo (2017)"),
|
|
77
|
+
malaria_sirs_tilahun=_p({"vector"}, "none", "temporary", "open", features={"disease_death", "backward"},
|
|
78
|
+
source="Tilahun, arXiv:1707.00924"),
|
|
79
|
+
malaria_partial_immunity=_p({"vector"}, "none", "partial", "open", features={"backward"}, source="Partial-immunity malaria model, standard incidence"),
|
|
80
|
+
malaria_partial_immunity_mass_action=_p({"vector"}, "none", "partial", "open", features={"backward"},
|
|
81
|
+
source="Partial-immunity malaria model, mass action"),
|
|
82
|
+
cholera_codeco=_p({"environment"}, "none", "lifelong", "open", source="Codeco (2001), BMC Infect. Dis. 1:1"),
|
|
83
|
+
dengue_esteva_vargas=_p({"vector"}, "none", "lifelong", "open", source="Esteva & Vargas (1998), Math. Biosci. 150:131-151"),
|
|
84
|
+
hiv_anderson=_p({"direct"}, "none", "none", "open", features={"disease_death"},
|
|
85
|
+
source="Anderson, Medley, May & Johnson (1986), IMA J. Math. Appl. Med. Biol. 3:229-263"),
|
|
86
|
+
sepia_gatto=_p({"direct"}, "short", "lifelong", "closed", features={"disease_death", "quarantine"},
|
|
87
|
+
source="Gatto et al. (2020), PNAS 117:10484-10491 (one-community version)"),
|
|
88
|
+
sidarthe=_p({"direct"}, "none", "lifelong", "closed", features={"disease_death"},
|
|
89
|
+
source="Giordano et al. (2020), Nature Medicine 26:855-860"),
|
|
90
|
+
ebola_legrand=_p({"direct"}, "short", "lifelong", "closed", features={"disease_death"},
|
|
91
|
+
source="Legrand, Grais, Boelle, Valleron & Flahault (2007), Epidemiol. Infect. 135:610-621"),
|
|
92
|
+
malaria_chitnis=_p({"vector"}, "short", "temporary", "open", features={"disease_death", "backward"}, source="Chitnis (thesis, 2005)"),
|
|
93
|
+
malaria_chitnis_2006=_p({"vector"}, "short", "temporary", "open", features={"disease_death", "backward"}, source="Chitnis, Cushing & Hyman (2006), SIAM J. Appl. Math. 67:24-45"),
|
|
94
|
+
siqs_mass_action=_p({"direct"}, "none", "none", "open", features={"quarantine"}, source=_HZS),
|
|
95
|
+
siqs_standard=_p({"direct"}, "none", "none", "open", features={"quarantine"}, source=_HZS),
|
|
96
|
+
siqs_adjusted=_p({"direct"}, "none", "none", "open", features={"quarantine"}, source=_HZS),
|
|
97
|
+
siqr_mass_action=_p({"direct"}, "none", "lifelong", "open", features={"quarantine"}, source=_HZS),
|
|
98
|
+
siqr_standard=_p({"direct"}, "none", "lifelong", "open", features={"quarantine"}, source=_HZS),
|
|
99
|
+
siqr_adjusted=_p({"direct"}, "none", "lifelong", "open", features={"quarantine", "oscillation"}, source=_HZS),
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
_PATHWAY_WORDS = {"direct": "person-to-person spread", "vector": "spread through a vector", "environment": "spread through the environment"}
|
|
103
|
+
_ANSWER_PATHWAY = {"direct": {"direct"}, "vector": {"vector"}, "environment": {"environment"}, "both": {"direct", "environment"}}
|
|
104
|
+
_FEATURE_WORDS = {"disease_death": "deaths caused by the disease", "saturation": "transmission that levels off",
|
|
105
|
+
"reinfection": "reinfection", "oscillation": "repeated waves", "backward": "backward bifurcation",
|
|
106
|
+
"quarantine": "isolation or quarantine of infected people"}
|
|
107
|
+
_FEATURE_TERMS = {"saturation": ("incidence",), "oscillation": ("hopf",), "backward": ("backward_bifurcation",)}
|
|
108
|
+
_IMMUNITY_WORDS = {"lifelong": "lasting immunity", "temporary": "immunity that fades", "partial": "partial immunity", "none": "no immunity"}
|
|
109
|
+
_LATENT_WORDS = {"none": "no delay before infectiousness", "short": "one latent period", "staged": "a latent period in several stages"}
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def check_answers(answers):
|
|
113
|
+
"""Validate the answers (ValueError with a readable message). Returns a clean dict; a missing or 'skip' answer is simply not used."""
|
|
114
|
+
if not isinstance(answers, dict):
|
|
115
|
+
raise ValueError("The answers must be an object of question -> answer.")
|
|
116
|
+
clean = {}
|
|
117
|
+
for k, v in answers.items():
|
|
118
|
+
if k not in _Q:
|
|
119
|
+
raise ValueError(f"Unknown question '{str(k)[:40]}'.")
|
|
120
|
+
if v in (None, "", "skip", []):
|
|
121
|
+
continue
|
|
122
|
+
if _Q[k].get("multi"):
|
|
123
|
+
if not isinstance(v, list) or not all(isinstance(x, str) for x in v) or not set(v) <= _VALUES[k]:
|
|
124
|
+
raise ValueError(f"Question '{k}' needs a list of listed options.")
|
|
125
|
+
clean[k] = sorted(set(v))
|
|
126
|
+
else:
|
|
127
|
+
if not isinstance(v, str) or v not in _VALUES[k]:
|
|
128
|
+
raise ValueError(f"Question '{k}' needs one of its listed options.")
|
|
129
|
+
clean[k] = v
|
|
130
|
+
return clean
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _score(profile, a):
|
|
134
|
+
"""Rules table. Returns (points, asked, matched, matches, differences, terms)."""
|
|
135
|
+
pts, asked, matched, matches, diffs, terms = 0, 0, 0, [], [], []
|
|
136
|
+
def hit(points, text, *t):
|
|
137
|
+
nonlocal pts, matched
|
|
138
|
+
pts += points; matched += 1; matches.append(text); terms.extend(t)
|
|
139
|
+
def miss(points, text, *t):
|
|
140
|
+
nonlocal pts
|
|
141
|
+
pts += points; diffs.append(text); terms.extend(t)
|
|
142
|
+
|
|
143
|
+
if "pathway" in a:
|
|
144
|
+
asked += 1
|
|
145
|
+
want, have = _ANSWER_PATHWAY[a["pathway"]], profile["pathway"]
|
|
146
|
+
if want == have:
|
|
147
|
+
hit(4, f"It models {_PATHWAY_WORDS[next(iter(have))] if len(have) == 1 else 'both person-to-person and environmental spread'}, as you described.", "vector_host" if "vector" in have else "force_of_infection")
|
|
148
|
+
elif want & have:
|
|
149
|
+
miss(1, "It also includes a second route of spread that you did not mention; remove it by setting its rate to zero or deleting that flow.", "force_of_infection")
|
|
150
|
+
else:
|
|
151
|
+
miss(-6, f"It models {' and '.join(sorted(_PATHWAY_WORDS[x] for x in have))}, not what you described.", "vector_host")
|
|
152
|
+
if "latent" in a:
|
|
153
|
+
asked += 1
|
|
154
|
+
if a["latent"] == profile["latent"]:
|
|
155
|
+
hit(3, f"It has {_LATENT_WORDS[a['latent']]}, as you described.", "infected_compartment")
|
|
156
|
+
else:
|
|
157
|
+
near = {a["latent"], profile["latent"]} == {"short", "staged"}
|
|
158
|
+
miss(-1 if near else -2, f"It has {_LATENT_WORDS[profile['latent']]}; you described {_LATENT_WORDS[a['latent']]}. You can add or remove exposed compartments on the canvas.", "infected_compartment")
|
|
159
|
+
if "immunity" in a:
|
|
160
|
+
asked += 1
|
|
161
|
+
if a["immunity"] == profile["immunity"]:
|
|
162
|
+
hit(3, f"It assumes {_IMMUNITY_WORDS[a['immunity']]} after recovery, as you described.", "compartment")
|
|
163
|
+
else:
|
|
164
|
+
miss(-2, f"It assumes {_IMMUNITY_WORDS[profile['immunity']]}; you described {_IMMUNITY_WORDS[a['immunity']]}.", "compartment")
|
|
165
|
+
if "vaccine" in a:
|
|
166
|
+
if a["vaccine"] == "yes":
|
|
167
|
+
asked += 1
|
|
168
|
+
if profile["vaccine"]:
|
|
169
|
+
hit(4, "It includes imperfect vaccination.")
|
|
170
|
+
else:
|
|
171
|
+
miss(-1, "It has no vaccination; you would add a vaccinated compartment yourself.")
|
|
172
|
+
elif profile["vaccine"]:
|
|
173
|
+
miss(-2, "It includes vaccination, which you did not ask for; set the vaccination rate to zero to remove its effect.")
|
|
174
|
+
if "population" in a:
|
|
175
|
+
asked += 1
|
|
176
|
+
if a["population"] == profile["population"]:
|
|
177
|
+
hit(2, "It treats births and deaths as you described." if a["population"] == "open" else "It ignores births and deaths, as you described.", "open_closed")
|
|
178
|
+
else:
|
|
179
|
+
miss(-2, "It includes births and deaths; you wanted a single outbreak." if a["population"] == "closed" else "It ignores births and deaths; you wanted a long-term view.", "demography")
|
|
180
|
+
for f in a.get("features", []):
|
|
181
|
+
asked += 1
|
|
182
|
+
if f in profile["features"]:
|
|
183
|
+
hit(2, f"It includes {_FEATURE_WORDS[f]}, which your question involves.", *_FEATURE_TERMS.get(f, ()))
|
|
184
|
+
else:
|
|
185
|
+
miss(-1, f"It does not include {_FEATURE_WORDS[f]}.")
|
|
186
|
+
if "quarantine" in profile["features"] and "quarantine" not in a.get("features", []):
|
|
187
|
+
miss(-1, "It includes quarantine of infected people, which you did not ask for; set the quarantine rate delta to zero to remove its effect.")
|
|
188
|
+
seen, uniq = set(), []
|
|
189
|
+
for t in terms:
|
|
190
|
+
if t not in seen and t in G.BY_ID:
|
|
191
|
+
seen.add(t); uniq.append(t)
|
|
192
|
+
return pts, asked, matched, matches, diffs, uniq
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def recommend(answers, limit=3):
|
|
196
|
+
"""Rank the library models for the answers. Returns dict(asked, suggestions=[...], note)."""
|
|
197
|
+
a = check_answers(answers)
|
|
198
|
+
out = []
|
|
199
|
+
for name, prof in PROFILES.items():
|
|
200
|
+
pts, asked, matched, matches, diffs, terms = _score(prof, a)
|
|
201
|
+
if asked and pts > 0:
|
|
202
|
+
m = T.TEMPLATES[name]()
|
|
203
|
+
out.append(dict(name=name, title=m.name, compartments=list(m.compartments), points=pts, asked=asked, matched=matched,
|
|
204
|
+
matches=matches, differences=diffs, terms=terms, source=prof["source"],
|
|
205
|
+
evidence=EV.record(name)))
|
|
206
|
+
out.sort(key=lambda r: (-r["points"], r["evidence"]["evidence"] == "thesis", len(r["compartments"]), r["name"])) # on equal scores a thesis version ranks after the journal paper
|
|
207
|
+
from . import categories as C
|
|
208
|
+
for r in out:
|
|
209
|
+
r["category_title"] = C.info(r["name"])["category_title"]
|
|
210
|
+
del r["points"] # the ranking is the output; the raw score is not meaningful to a researcher
|
|
211
|
+
note = ("Answer at least one question to see suggestions." if not a else
|
|
212
|
+
"No library model fits these answers. Start from the simplest SIR template and edit it on the canvas." if not out else
|
|
213
|
+
"These are starting points from the library, not a judgement about your disease. Check every assumption against your own knowledge and sources.")
|
|
214
|
+
return dict(asked=len(a), suggestions=out[:limit], note=note)
|