-
Notifications
You must be signed in to change notification settings - Fork 6
LASER pip package structure
This is the plan of record for how LASER code (and supporting files) will be decomposed across packages.
This package will contain code, mostly utilities and container classes, which are useful for all LASER models. You should never need to install it directly. It will be a listed dependency of laser-measles, laser-cholera, etc. As of this writing, it's about to be made available as a dev release. laser-core will be released, and be usable on its own, and there will be a LASER-GPT (AI Assistant) to help users write working models against it, but it will not be the "start here" point for modelers. It will be more of a foundational technology showcase. There will almost certainly be no disease model components in laser-core because the only expected property in LASER is node_id and almost any working component (except maybe migration) will presume the existence of one or more actual properties.
This package will build on laser-core and mostly consist of working examples of SI, SIS, SIR, SEIR, SEIS, SEIW models. It will be publicly released and well documented and have its own AI Assistant. It will consist of some components like intrahost_progression, transmission, immunity_progression, fertility, natural mortality and migration. There will be single node and spatial examples. laser-generic will be the primary base "start here" installable for LASER modelers. There will be nothing about specific actual diseases in laser-generic.
This package will contain code to build and run a measles LASER model. Note that there will (probably) never be any such thing as the measles LASER model. (The only property that will ever be truly required for all models will be node_id.) It will have a dependency on laser-core. You will be able to install it directly. You will be able to run
python -m laser_measles.get_examples
And working runnable demos will be placed in your current working directory or a directory of your choice. This will include one or more notebooks.
There will be a working measles model using Washington State (with county patches) as the default geography/demographics.
There will also be example scenarios of the classic England and Wales mid-1940's through mid-1960's and an IDM contributed scenario of northern Nigeria at admin 2 level.
The laser-measles package will include a set of components, such as:
- fertility
- natural mortality
- contact transmission
- intrahost (incubation progression, infection progression, and acquired immunity)
- vaccination (RI and SIA)
A component in LASER is a standalone sub-module that performs a specific epidemiological or demographic function on 1-2 properties every timestep, such as simulating contact transmission or mortality. Components are generally implemented as classes with initialization, a per-timestep function, and two optional functions: on_birth() to initialize properties of new agents and plot() to visualize the effects of the component (recommended). Normally a component will be responsible for adding properties which it modifies, but that's not always possible as some properties are shared across components. (That last part, shared ownership of properties across components, is a design TBD.)
Some of the laser-measles components may not be truly measles-specific and may make their way into laser-core. As of this time, there are no components in laser-core.
If you develop new components that are measles-specific and might be useful to others, you can contribute them to laser-measles.
E.g., laser-measles-geomed-nnigeria-2024-kr
If you're developing your own new (LASER) measles model for a given geography, for a particular project, you will probably want to create a new repo. It is not a requirement to turn this into a pip installable package, but it is recommended. You'll want a requirements.txt file or [project] dependencies= entry in pyproject.toml which specifies laser-measles~=1.x, if laser-measles is at major version 1 at the time you work on this project. This way you'll be able to pick up new compatible versions of laser-measles but if we push out a laser-measles 2.0, you won't accidentally pick that up.
laser-cholera will be analogous to laser-measles, but will likely not have any cross-dependency on laser-measles, just laser-core. It seems likely that we end up with a common fertility and mortality component in laser-core which is used by laser-measles, laser-cholera, etc.
Note: The laser-cholera repo is not yet where the laser-cholera code is housed. laser-cholera was started as a branch in laser-core and is still being developed there for the time being. package-wise, however, laser-cholera is as described above.
Analogous to laser-measles-project-place-time-abc but for cholera.
A package demonstrating using laser-core components and LASER architecture for metapopulation modeling where each patch has its own compartmental model of disease along with spatial connectivity between patches.
Semantic versioning (semver) is a versioning strategy that provides both stability and flexibility by clearly signaling compatibility and the scope of changes in software packages. When using semver in a system with three levels of dependence—an application layer, a middle modeling layer, and a core layer—each layer can evolve independently while minimizing disruptions across the stack. In semver, version numbers follow a pattern of MAJOR.MINOR.PATCH, where changes in the PATCH version indicate bug fixes or minor improvements, MINOR updates add backward-compatible features, and MAJOR increments signal breaking changes. By adhering to this scheme, the core layer can introduce optimizations or new functions with PATCH or MINOR changes without affecting the higher layers, ensuring that application developers relying on the middle layer experience minimal disruptions. Meanwhile, the application layer can confidently build on top of the middle modeling layer, knowing that only MAJOR updates to the core or modeling layers will require adjustments for compatibility. This structure allows for robust, predictable software growth across each layer, with the stability required for production use and the flexibility to incorporate enhancements as the underlying packages evolve.