Skip to content

Epistemix Community Library

The Epistemix Community Library is a resource that is freely available to all users of the Epistemix Platform. It contains FRED models applicable to various use cases from population health and policy analysis to infrastructure planning. The FRED code for all models in the library is available for you to review, modify, and reuse in your own projects. Additionally, each model is accompanied by documentation that introduces the modeling problem that it addresses, relevant parameters, and interesting scenarios to try out within the Epistemix Platform. The Community Library provides practical examples of how FRED can be used to solve real modeling problems.

Once you've been working with FRED for a while, you may have a model that you would like to share with the community for feedback and collaboration. If that's the case then we would love to hear from you! Below we provide detailed guidance on how you can submit your model for inclusion in the Community Library.

Accessing the Community Library

The Community Library can be accessed directly within the Platform IDE. Start the Launcher by clicking the + button in the top left-hand corner of the File Browser navigation bar

Screenshot

From within the Launcher click the 'Model Library' button to open the Community Library.

Screenshot

Screenshot

From here you can browse for models of interest either by filtering by category or by searching for keywords. Currently all models in the library are automatically installed in the Platform IDE by default. Once you've found a model you'd like to explore in more detail using the Community Library interface, head over to the Community-Library directory in your Plaform IDE home directory to review its code and documentation.

Screenshot

Library Submission Guidelines

Here we describe the process for submitting your own model to be added to the Community Library. All submissions are reviewed by the Epistemix team to verify that they correspond to the same basic structure. This is to ensure consistency across models in the library so that members of the community can quickly pick up and understand new models. If you are have any questions about how to get a model into the format described below, please get in touch with us in the Community Forum or by emailing learning@epistemix.com.

Directory structure

The following is a minimal set of files required for a submission, in this case using the Simple Flu model as an example:

.
├── fred.toml
├── README.md
├── simple-flu.ipynb
└── model/
    └── main.fred

The .fred files that make up the model should live in the model/ directory. If additional input files are required to run the model, they should be placed in a data/ folder:

└── model/
    └── main.fred
└── data/
    └── flu-vaccination-rates.csv

FRED metadata file (fred.toml)

The fred.toml file contains the information that will appear on the model's description page in the Community Library, as well as additional information used by epx-server.

The fred.toml file should follow this structure:

[metadata]
name = "Simple Flu"
description = """
A model that represents the spread of influenza throughout a population, characterized with a compartmental Symptomatic-Exposed-Infectious-Recovered (SEIR) model. Agents can either be symptomatic or asymptomatic when infectious."""
categories = [
    "Epidemiology"
]
authors = [
    "Claire Dickey <claire.dickey@epistemix.com>"
]
version = "0.1.0"
fred_versions = [
">=8.4",
"<9"
]

[run_options]
src_dir = "model/"
entrypoint = "main.fred"

The metadata.name, metadata.description, and metadata.categories fields will be used by the Community Model Marketplace UI.

Ideally, metadata.name should be <=50 characters, and metadata.description should be <= 300 characters. This helps to ensure that key descriptive metadata for your model displays nicely in the Community Library UI. You can always include more detail about your model in its README.md file (see below).

metadata.categories are optional, and we currently allow models to be tagged as pertaining to any of the following:

  • Population Health
  • Policy Analysis
  • Social Science
  • Product Adoption
  • Infrastructure

If you feel that an important category is missing from these options, please reach out to learning@epistemix.com.

README.md

Required information:

  • Title
  • Authors
  • High level verbal description of what model represents
  • List of conditions and description of what each condition does
  • What are key variables (global and personal), how are they used, and where are they defined?
  • Key outputs: are there csvs generated? Which global variables/ state occupancy counts are of interest?
  • Optional: Things to try section
    • Interesting locations to run the model on
    • Parameter ranges of interest

Example .ipynb notebook

The .ipynb notebook included in the model submission should demonstrate that the model runs and showcase simulation results for a user.

Code blocks should be included that successfully return an epx-job and load relevant outputs. Additionally, the notebook should include at least one visualization that highlights the output from the simulation (e.g., case counts as a function of time or disease exposures mapped to locations).

The notebook name should match the metadata.name field, with spaces replaced by hyphens and upper case with lower case (i.e., Simple Flu -> simple-flu.ipynb).

License

Please include a LICENSE file with your submission specifying a permissive software license (e.g. MIT or BSD). Inclusion of a license is important to communicate to others how they can reuse your code, and a permissive license ensures that others have as much flexibility as possible. If you don't include a license file, we will add an MIT license before inclusion in the Community Library.

Send it to Epistemix for review

Finally, please create a zip file containing your model code and email it to learning@epistemix.com. We will aim to review your work and get back to you with any queries within 48 hours before adding it to the Community Library!