Cost calculator project

[gvegayon]

The cost calculator app will provide a straightforward way for non-expert users to investigate the potential cost of an outbreak or disease burden from an economic perspective. The project already has a version up and running, and now that we have received some feedback from public health partners, we need to enter the next development stage. This document highlights the project's requirements and provides technical details on the implementation.

User stories

User stories are brief descriptions of what users would like to do with the software. Originating in the agile world, these provide simple bits of information that developers can use to inform the design of the software. As a minimum, each story should have a role, the action, and the expected benefit out of it. The baseline is: "As a [persona], I want [action] so that [benefit]". Here are some user stories

• As an epidemiologist, I would like to be able to select a disease so that all relevant costs are already available.

• As an epi, I would like to specify how many breaks are included in the model, so that it provides multiple points of comparison.

• Like any user, I would like the app to allow me to save the current state of the model, so that I could share it and reuse it whenever I need.

• As a developer, I would like this to be modular, allowing me to extend it easily to other diseases.

• As a public health official, I would like this to allow me to generate a report with a summary, so I can share this directly with the lawmakers/general public/epis.

• Like any user, I would like to be able to read the assumptions behind the model (possibly a longer description), so that I can justify the numbers.

• As an epi, I would like the app to include some guardrails to avoid generating misleading information. In the worst-case scenario, this should feature a warning.

Technical specs

Here are some technical specs that the app should have:

1. In an ideal world, the models should be built using a simple yaml file that contains parameters, ways to compute the data, references, and text information.

2. Since most of the models will generate the same type of outcome, we should standardize the reports, simplifying the process of extending the program. For instance, we can have yaml entries that specify: title, description, authors, and introduction as free text.

3. The yaml should include a separate entry for the parameters with the following fields per parameter: name (text), description (for a tool tip), default value (numeric), min value (numeric), max value (numeric), references (free text), unit label (e.g, usd, people, hours, days, etc.), and if it is integer or double (essentially, show decimals or not).

4. The yaml should also include an entry for named equations, which will provide the data that will go in the table. These should be in the form of: name/label (text), equation (Python code, essentially), unit label (e.g., usd, people, hours, etc.), output type (integer or double). Here is an example:

Equations: 
  - Eq1: 
    label: “Contact tracing cost” 
    equation: “cost_per_case * cost_per_hour” 
    unit-label: “USD” 
    output-type: double 

  - Eq2: 
    label: “Hospitalizations” 

Finally, the yaml with the table description in the following way: column label (Python code, possibly taking values from the output/input), and then a list with individual entries for each output, including: label (for the table) and value (pointing to which value from the equation).

  Table:
    - name: “Contact tracing” 
      value: Eq1 
    - name: “Hospitalization cost” 
      value: Eq1 

Using the data from the description of parameters, we can automatically add a table that describes them, including to links, if available, to references. The benefit of especifying the contents for a single column is that we can allow the user to then specify what values they want to use, so if they want to use 1, 2, or 10 columns, it is up to them.

Expected outcome from the discussion

• Have a flow diagram that shows how the program reads the yaml files.
• Have a template page that will be used for populating using the yaml file.
• Have a timeline for the implementation of the project.
• Have more user stories, and eventually map them to specific features of the app.

[gvegayon]

Here is an example workflow:

flowchart LR
  yaml --> readin
  readin --> validate
  validate --> Error{Is error?}
  Error -->|Yes|endError((The file is wrong))
  Error -->|No|Continue

Loading

You can learn more about it here: https://mermaid.ai/open-source/.

[EddW1219]

flowchart TD

    subgraph Refactor[Refactoring]
        direction LR
        A[Hard-coded .py model Scripts] --> B[YAML files]
        B --> C[YAML Loader]
        C --> D[Dynamic UI/Scenarios]
        D --> E[Equation Engine]
        E --> F[Guardrails]
        F --> G[App]
    end

    subgraph Architecture["Structure"]
        direction TB
        App[app.py: Main Entry] -->
        Engine[engine.py: Parser & Eval Calculations] -->
        Models -->
        Utils[utils.py: Rounding & Formats]
        
        subgraph Models["/models/"]
            TB[tb_isolation.yaml]
            Measles[measles.yaml]
        end
        
    end

Loading

[EddW1219]

gantt
    title Implementation Timeline
    dateFormat  YYYY-MM-DD

    section Development
    Week 1 - The Template     :w1, 2026-02-23, 7d
    Week 2 - The UI Engine    :w2, after w1, 7d
    Week 3 - Dynamic Logic    :w3, after w2, 7d
    Week 4 - Reporting        :w4, after w3, 7d

    section Tasks
    Create model YAML & engine.py   :2026-02-23, 7d
    Auto-generate st.sidebar and dark/light mode  :2026-03-02, 7d
    Eval engine & Scenarios   :2026-03-09, 7d
    Export & Assumptions pdf :2026-03-16, 7d

Loading

[gvegayon]

I appreciate you adding this, @EddW1219! But I think we need a bit more detail. For reference, discussions on GitHub should look a bit more like this (or at least, that is what I was expecting). Writing is a great skill to have, so it is not just coding. Would love to read your thoughts about how to implement this. Things that I am still missing a bit:

• What will be the structure of the yaml files?
• What would you propose for the reports?

I think this workflow is a good start:

flowchart TD

    subgraph Architecture["Structure"]
        direction TB
        App[app.py: Main Entry] -->
        Engine[engine.py: Parser & Eval Calculations] -->
        Models -->
        Utils[utils.py: Rounding & Formats]
        
        subgraph Models["/models/"]
            TB[tb_isolation.yaml]
            Measles[measles.yaml]
        end
        
    end

Loading

We can chat more about this today.

[olivia-banks]

Hi! Sorry that I've been absent, I didn't realize that this discussion was going on yet. Give me a while to catch myself up and then I'll hop in.

[JakeWags]

It may be beneficial to consider including some sort of visual interface for .yaml creation rather than expecting users to provide pre-made files. This would aid non-programmers in using the tool while still allowing for more granular programmatic control for advanced users.

[olivia-banks]

I agree, I think text (i.e. YAML) would likely be best for as a serialization format, rather than an authorship format, at least for non-programmers.

[gvegayon]

Great points! We could add that as another feature of the software. Initially, I wouldn't expect STLTs to dive into creating their own models, so at the beginning, it would mostly be folks from the U and other researchers who would be doing that. That said, a simple GUI for creating a valid YAML should be easy to build.

[gvegayon]

I asked copilot, and this is what it created for me: https://github.com/EpiForeSITE/epiworldPythonStreamlit/blob/5aee265b4970871a787887b9c939c7727d8494aa/docs/design-proposal.md

[olivia-banks]

@gvegayon This seems valuable. A couple thoughts:

• Should equations have an output_type? I would think this would be inferred from the input parameters or always be a double.
• I'm always a little weary of encoding something program-shaped in a YAML file (or similar). Arbitrary equation code is sorta drifting into the domain of a programming language instead of a data format, which I think is worth thinking about.

With the current problem description (i.e. authorship by those with some technical skill and STLT consumers), I wonder if writing things in Javascript wouldn't be a better approach; then we wouldn't be trying to encode arbitrary logic into formula strings. The YAML layer could then exist as a layer on top that simply calls into the JS API. The browser can already load this arbitrarily, so this wouldn't present a large technical challenge I don't believe.

The main benefit there is that we’d stop trying to reinvent a constrained expression language inside a serialization format. If the logic is genuinely logic, we should probably let it live in an actual programming language instead of smuggling it through strings and then writing an interpreter for it.

Right now, once we allow "arbitrary equations," we’re implicitly committing to defining the grammar of those equations, validating them, evaluating them safely, deciding how types propagate, handling edge cases and errors, and so on and so forth. My thinking is, that that's already the shape of a language runtime. At that point YAML is just acting as a transport for code, which feels like the wrong abstraction boundary.

If the primary authors are technically capable, at least initially, I don’t think optimizing for "no-code" authoring should dominate the design. A small JS module that exports well-defined functions is straightforward to write, test, and version. Consumers can import it directly in the browser (i.e. from the local file system, or even from a remote resource URL). We'd get native tooling, stack traces, and type checking if we want it.

For non-technical authors, YAML can sit pretty easily on top. Using the same aforementioned JS API, we could A) deserialize the YAML, B) loop over the data and call the respective JS functions to set up internal state. In other words, instead of stretching YAML toward a programming language, I propose we let it stay a data language and put behavior where behavior naturally belongs. That separation feels cleaner and easier to maintain over time to me, although I'm not the non-technical audience this might eventually get targeted toward.

Thoughts @EddW1219 @JakeWags?

[gvegayon]

Wouldn't JS be harder to read? About the equations, my thought was to have Python code there, most likely basic math (multiplication, sums, subtraction, etc.). Doesn't Python have a way to call code directly? R has!

[olivia-banks]

Oh, yes, with eval! I thought Copilot was suggesting we build a small DSL inside the YAML. Although, since (correct me if I'm wrong), all the Python is running on the server, security might be a concern. Allowing clients to submit arbitrary Python code to be eval'd doesn't seem good from a security standpoint, and it's notoriously hard to sandbox Python (unless we were to modify some of the IPSD code I wrote a little over a year ago, which might work). I guess we could match the code against a regex or something, or compile it and then a check to make sure the only VM instructions generated are those that manipulate the stack and do arithmetic operations; this could work, but seems like it might be a bit of work to implement.

My rationale with Javascript was that it could provide a safe, browser-native way to leverage arbitrary logic without a DSL and without putting the server in peril. As on the hard to read front, I don't particularly think so. I might envision something like this:

export default defineModel({
  metadata: {
    title: "Measles Outbreak Cost Calculator",
    description: "Estimates the economic cost of a measles outbreak across three outbreak-size scenarios.",
    authors: [
      { name: "Jane Doe", email: "jane@example.org" },
      { name: "John Smith" }
    ],
    introduction: `
## Background
Measles is a highly contagious viral disease ...

## Assumptions
All wage figures are in 2024 USD and are taken
from the Bureau of Labor Statistics.
`
  },

  parameters: {
    cost_hosp: integer({
      label: "Cost of measles hospitalization",
      description: "Average direct medical cost per hospitalised measles case (USD).",
      default: 31168,
      min: 0,
      max: 500000,
      unit: "USD",
      references: [
        "Ortega-Sanchez et al. (2014). Vaccine, 32(34)."
      ]
    }),

    prop_hosp: number({
      label: "Proportion of cases hospitalised",
      description: "Fraction of confirmed cases requiring hospital admission.",
      default: 0.20,
      min: 0,
      max: 1,
      unit: "proportion",
      references: [
        "CDC Measles surveillance data 2019."
      ]
    }),

    /* ... */

  equations: {
    eq_hosp: equation({
      label: "Hospitalisation cost",
      unit: "USD",
      output: "integer",
      compute: ({ n_cases, prop_hosp, cost_hosp }) =>
          n_cases * prop_hosp * cost_hosp
    }),

    /* ... */
  },

  table: table({
    scenarios: [
      { id: "s_22", label: "22 Cases", vars: { n_cases: 22 } },
      { id: "s_100", label: "100 Cases", vars: { n_cases: 100 } },
      { id: "s_803", label: "803 Cases", vars: { n_cases: 803 } }
    ],

    rows: [
      { label: "Hospitalisation cost", value: "eq_hosp" },
      { label: "Lost productivity", value: "eq_lost_prod" },
      { label: "Contact tracing cost", value: "eq_tracing" },
      { label: "TOTAL", value: "eq_total", emphasis: "strong" }
    ]
  })
});

Or even maybe equations this, if it isn''t too terse:

equation("Hospitalisation cost", $ =>
  $.n_cases * $.prop_hosp * $.cost_hosp
)

We could really be quite flexible here, while still being safe and relatively easy to author. Since these are mostly dictionaries anyways, YAML support would more or less be a direct serialization/deserialization with an intermediate step for equations.

[olivia-banks]

Now that I think about it, we wouldn't have to do anything with the Python VM. We could use Python’s ast module to parse expressions, allow only safe node types, and reject anything else. This gives us:

• A constrained expression language
• No arbitrary code execution (as far as I can see)
• No need for a JS layer
• No reinvention of a full DSL

It is some work, but far less than designing a coherent way of transferring data between JS and Python that isn't just promising to keep JSON schemas in check. There's still the issue of separating code from data, but I think it's lessened enough in this scenario to be OK.

[EddW1219]

Hi Olivia, I agree with your point. It is what we wanted from the meeting with George. Coincidentally, I’ve been modifying the program in this way since last weekend. I will create another branch for the new version this weekend to see how it goes. The only issue that might arise would be with the math equations; I’m unsure whether Streamlit.io can parse them correctly.

[olivia-banks]

Hi Olivia, I agree with your point. It is what we wanted from the meeting with George. Coincidentally, I’ve been modifying the program in this way since last weekend. I will create another branch for the new version this weekend to see how it goes. The only issue that might arise would be with the math equations; I’m unsure whether Streamlit.io can parse them correctly.

If I'm correct in saying that Streamlit is running the Python you wrote, it should be as simple as a compile call directly on the equation text after interpolating it inside a function, and then a brief scan over the AST for security, before chucking it into an importlib object and loading it on the fly. As far as I can tell, this wouldn't require anything extra from Streamlit, and as a bonus it uses only what's already included in CPython's stdlib and would probably only be a hundred of lines of code or so.

Let me know your thoughts on this. I can put together a short demo of the interpolation and security code if you're curious. Out of curiosity, would you ping me when the branch is pushed? I'm curious as to your implementation strategy.

Hope you're having a good day!