SHIVIR (Susceptible, Hospitalized, Infected, Ventilator, ICU, Recovered, Immune)

Quick start

1. Pick a starting point. Use Load preset (top of the left panel). The Reference preset reproduces the 2020 Telangana configuration of the paper; the two examples show how to compare policy packages and vaccination.
2. Describe the population. In the left panel open Population. Either generate a synthetic district (number of people, density, household sizes, age shares) or upload your own synthetic population files.
3. Set the interventions. Open the Interventions & scenarios tab. Add as many interventions as you need, each with its own type, start date, end date, effect and coverage. Tick which interventions belong to each scenario.
4. Run. Press Run simulation (or Ctrl+Enter). A progress bar shows the replicate and scenario being simulated; Stop keeps whatever has finished.
5. Read and download. Use the Charts, Compare scenarios and Summary tabs. Every chart has PNG and Excel buttons; Templates & downloads exports everything (all results, all charts as images) into one Excel workbook.

Every input has an i button. Click it (or hover) to see what the value means and how it is used.

The screen

• Left panel: model settings (run, population, contacts, transmission, disease and care, seeding, hospital capacity). Drag the thin divider to make it wider or narrower; double-click the divider to reset it; Hide panel gives the charts the full width.
• Charts can be made taller or shorter by dragging their bottom-right corner. Hover over a chart to read exact values for any day.
• Tiles at the top summarise the scenario selected in the Charts tab.
• Your settings are remembered in this browser. Reset all values (bottom of the left panel) restores the reference configuration.

Interventions

Each intervention is active from its start date to its end date (both included; leave the end date blank to keep it on until the end of the run). Interventions can overlap: their effects multiply.

Applies to chooses close contacts (the person's regular circle, including the household), community contacts (random people in the district) or both. Age group limits an intervention to one age band; for contact reductions it then also reduces contacts with that age group, which is how shielding protects older adults.

A scenario is a set of interventions plus a post-recovery immunity period. In the scenario table, tick the interventions each scenario includes. The optional protection coverage column overrides the coverage of every protective measure in that scenario, which makes it easy to compare adoption levels.

Reading the results

• Health states: how many people are in each state on each day. Asymptomatic (undetected) and Symptomatic are the infectious states.
• Hospital occupancy: ward beds = people admitted; ICU beds = people in ICU plus people ventilated; ventilators = people ventilated. Dashed red lines are the capacities you entered.
• Daily incidence: new events per day; tick Cumulative for running totals.
• Bands: when several replicates are run, the shaded band covers the middle 95% of replicates (2.5th to 97.5th percentile). Wide bands mean chance matters a lot.
• Observed data (if uploaded) appear as dots, and the Summary tab shows how closely each scenario fits them (MAPE, RMSE).
• Summary: attack rate, totals, peaks and their dates, days over capacity, bed-days and the infection fatality ratio for each scenario. Each row has an i with its definition.

Watching the simulation live

• Speed: the slider under Run simulation (and at the top of the Live view tab) sets how many simulated days pass per second, from 1 to 100, or Fastest. You can change it while a run is going. Speed never changes the results: the same seeds give the same numbers at any speed.
• Pause, Resume and Step: pause at the end of the current day, then step one day at a time to follow what happens.
• With a speed slower than Fastest, pressing Run opens the Live view tab. By default only the first run (replicate 1 of the first scenario) goes at the chosen speed and the rest finish at full speed; untick Chosen speed for the first run only to watch every run.
• Flow between health states: each box shows how many people are in that state now; arrows show the moves between states, with the number moving per day and moving dots for the flow. The arc on top is waning immunity.
• Agents and their contacts: every simulated person is a dot at their home, coloured by health state. New infections are drawn as lines from the infecting person (solid = close contact, dashed = community contact).
• Follow one person: click a dot to select that person. The panel shows their household, health state, close contacts and whether they comply with each intervention. On the map, grey lines join them to their close contacts, blue lines show the contacts made in the latest simulated days, and red lines show infections.
• Current run: the curve of the run in progress, with bars showing when each intervention of the scenario is active, and chips listing the interventions active on the day shown.

Checking interventions

• The Intervention check card (Interventions & scenarios tab) checks every intervention as you type. Errors (✕, red outline) stop the run, for example an end date before the start date, a missing effect, or a coverage above 100%. Warnings (⚠, amber outline) are worth a look: an intervention that is never active within the simulated period, starts before day 0 or ends after the last day, has 0% effect or coverage, removes every contact, overlaps another intervention of the same kind (their effects multiply; the combined effect is shown), vaccination campaigns that add up to more than 100% of an age group, or periods in which almost no contacts are left.
• For the scenario you choose, the table shows each intervention's protection offered (the entered effect and its average over everyone it can reach), the population intervened (how many people, or which contacts) and the duration (dates, days and the part that falls inside the simulation).
• After a run, achieved columns show what happened in the simulation: people who complied or were vaccinated, the share of contacts that were protected, and the days on which each intervention was in force. A second table compares, period by period, the contact levels and protection implied by the interventions with those of the simulated infectious people. The Contacts and protection chart in the Charts tab shows the same check day by day.

Household sizes

Under Population, household sizes can be drawn from a frequency table (for example a census table of households with 1, 2, 3, … members) or from a distribution: a fixed size, uniform between a minimum and a maximum, Poisson or negative binomial (set by the mean size), or normal, lognormal or gamma (set by the mean and standard deviation, rounded to whole people). A bar chart shows the resulting share of households of each size and the mean, and the Network & analytics tab reports the sizes in the population that was built.

Age groups

Open Age groups in the left panel to define your own groups. Each group is set by its youngest age (the first group starts at 0) and has a proportion of the population. Use + Add group, the × button or a standard set (for example 0–17, 18–59, 60+, or ten-year bands). The probabilities for each group (undetected share, ICU, ventilation and death) are set under Disease progression and care, and the contact distributions under Contacts and network; both tables get one column or row per group. Age-targeted interventions choose from the same groups, and the Summary tab reports infections, admissions, ICU, ventilation and deaths for each group. When you change the groups, shares are spread by years and each new group starts with the values of the old group containing its youngest age, so check them afterwards.

Size of the studied area

Under Population, Size of the studied area can be set from the population density (area = people simulated ÷ density), as an area in km² (a square district) or as a width and height in km (a rectangle). The line below shows the area and the number of people per km². Settlements and households are spread over this area, the live map keeps its shape and shows a scale bar, and the density used by the contact helper is the population represented divided by the area.

Zooming the map

In the Live view, zoom the Agents and their contacts map with the mouse wheel, a two-finger pinch on a touch screen, a double-click (Shift + double-click zooms out) or the + and − buttons; drag to move around and press Fit to see the whole area again. A click without dragging selects a person. The map can also be drawn as a heat map of the share of people who are infectious now, or who have been infected.

Templates and your own data

• Input template (Excel): download it from Templates & downloads. It is pre-filled with the current settings and has sheets for parameters, age-specific values, interventions, scenarios and observed data, with drop-down lists for the allowed choices. Edit it in Excel and upload it back to load everything at once.
• Observed data: daily reported cases, hospital occupancy and deaths, in the template's Observed_data sheet or as a CSV file with the same columns.
• Population files: CSV templates for households (hh_id, latitude, longitude) and people (per_id, hh_id, age). Select Upload synthetic population files under Population.
• Dates may be Excel date cells or text in the form YYYY-MM-DD (or DD-MM-YYYY).

Randomness and reproducibility

Every chance event (who meets whom, whether a contact transmits, who becomes symptomatic, how long each stay lasts) is drawn from a seeded random-number generator. The same settings and seeds always give identical results, so a saved configuration reproduces a run exactly. Change the simulation seed, or tick New random seed every run, to see other realisations. Use several replicates to see how much results vary by chance.

Tips

• Start with 20,000–50,000 agents and 3 replicates while exploring; increase both for final results.
• To represent a large district with a sample, set Population represented; all counts are scaled up.
• The Network & analytics tab shows the implied care fractions, the effect of each intervention period and an approximate R₀, with a helper to calibrate it.
• Results are model outputs that depend on the inputs; calibrate parameters to local data before using them for decisions.

The model

SHIVIR represents each person as an agent with an age band, a household, a location and a district. Each agent receives a contact quota drawn from an age-specific distribution and multiplied by the contact-scaling constant. Its close-contact list holds all household members, then nearby agents accepted with probability 1 − d/dmax until the quota is filled; links are reciprocal.

Each day, every infectious agent makes R(f₀ · |C| · mclose) contacts from its close-contact list (sampled without replacement) and R((1 − f₀) · |C| · mcommunity) contacts with random agents in the district. Here R is unbiased stochastic rounding, f₀ is the baseline close share, and m combines the active contact-reduction and isolation interventions. A contact with a susceptible agent transmits with a per-contact probability. That probability is reduced by each protective measure covering the contact and by vaccination of the susceptible agent. New infections take effect at the end of the day (synchronous updating).

Infected agents become undetected (asymptomatic) or symptomatic. Symptomatic agents are admitted and isolated after a delay. Admitted agents may move to ICU, then to mechanical ventilation, and may die or recover. Recovered agents are immune for the scenario's immunity period, then become susceptible again. An optional latent period makes agents non-infectious for a few days after infection.

Random seeding

All randomness comes from a seeded generator (sfc32, seeded through splitmix32). Separate streams are derived for the population, for each replicate's contact network, for each scenario within each replicate, and for each intervention's compliance and vaccination order. The same configuration and seeds reproduce identical results.

Durations

Duration fields accept a fixed number of days (14), a triangular distribution (tri(7,8,9) = minimum, mode, maximum), a uniform distribution (uni(3,7)) or a gamma distribution (gam(shape,scale)), rounded to whole days.

Limits

The browser holds every agent in memory: up to about 300,000 agents runs comfortably on a typical laptop. Results are model outputs, not forecasts; calibrate parameters to local data before outputs inform decisions.

SHIVIR (Susceptible, Hospitalized, Infected, Ventilator, ICU, Recovered, Immune), simulator version 2.0 (model logic v1.1 with flexible interventions).