Better names for public-facing API

[cdc-mitzimorris]

Goal

We need an accessible API based on the builder patter that allows the user to completely specify a multi-signal model (in 100 lines of code or less). Class, method, and method argument names should be semantically meaningful to epidemiologists.

• Names should align with the epidemiological terminology for the model components and data characteristics.

• Functional patterns on the public API should make subclasses look mechanically similar even if their internals differ.

• We should anticipate adding further components to PyRenew in order to fully express the models currently implemented in PyRenew-HEW

To date, the components used by PyrenewBuilder were added to PyRenew in successive PRs each of which added a component and accompanying tutorial explaining that component. This example-driven development was based on relatively simple models compared to PyRenew-HEW, and the focus was on model structure, not epidemiological role.

Latent infection process names

• HierarchicalInfections - latent infections consiting of a population-level baseline trajectory and subpopulation-level deviations; example, population-level hospitalizations and subpopulation-level wasterwater measurments.

• SharedInfections - a single latent infection trajectory at the population-level; example: hospitalizations and ED visits.

Proposed solution(s)

Rename HierarchicalInfections and SharedInfections. Possibilities:
- SubpopulationInfections / PopulationInfections
- BaselineSubpopulationInfections / PopulationInfections
- MultilevelInfections / SingleTrajectoryInfections

Latent infection process arg

• initial_log_rt_rv (argument to the constructor for HierarchicalInfections and SharedInfections) - should be log_rt_time_0_rv (or similar).

Observation process names

The base class is BaseObservationProcess from which base classes for counts and measurements inherit, which should be named: CountObservation and MeasurementObservation (currently CountBase and Measurements)

The concrete observation classes need to distinguish between population/subpopulation and temporal aggregation:

• PopulationCounts
• SubpopulationCounts

and similarly for Measurements.

The temporal aggregation should be handled by a parameter to the constructor observation_format.
Here is an example of what this would look like:

PopulationCounts(
    name="deaths",
    observation_format="daily",
    ...
)

PopulationCounts(
    name="hospital_admissions",
    observation_format="aggregated",
    aggregation_period=7,
    ...
)

SubpopulationCounts(
    name="ed_visits",
    observation_format="daily",
    ...
)

[dylanhmorris]

One proposal

• remove observation_format, replace with a flag for dense/spare regular/irregular spacing of observations (exact name TBD)
• handle temporal aggregation relative to the fundamental time unit only via the aggregation_period parameter, which defaults to 1 (no aggregation)

[dylanhmorris]

@cdc-mitzimorris suggestsreporting_schedule = {"regular", "irregular"} which I like. cc @damonbayer