Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/report-cliffs-from-simulation-runs.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`/v2/reports` reads a report run's cliff impact from its two simulation runs' cliff results, never from the report run's own cliff columns, and each economy report read gives `cliffs`: how far each side's cliff calculation has got. `POST /v2/reports/{report_id}/runs` takes `include_cliffs`, which a household report or budget window refuses with 422.
4 changes: 4 additions & 0 deletions policyengine_api/fastapi_routes/resource_service_protocols.py
Original file line number Diff line number Diff line change
Expand Up @@ -285,11 +285,15 @@ def rerun_report(
country_id: str,
report_id: UUID,
force: bool,
include_cliffs: bool = False,
requester: AccountPrincipal | None = None,
) -> StoredReportRead:
"""Run the country's report again; return it with the run the request ended on.

That is the run the simulation service named, created or joined.
With ``include_cliffs``, it also starts the cliff calculations an
economy report run's simulation runs lack; ``CliffsNotAvailableError``
is raised, before anything is asked, for any other kind.
With a ``requester``, the request is recorded for its user once the
simulation service has answered, and
``StandardUserRequiresSignInError`` is raised, before anything is
Expand Down
48 changes: 47 additions & 1 deletion policyengine_api/fastapi_routes/v2/reports/response_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -140,14 +140,60 @@ def from_summary(cls, read: ReportSummaryRead) -> ReportSummaryItem:
return cls.model_validate(read)


# How far a side's cliff calculation has got.
CliffCalculationStatus = Literal[
"not_calculated", "pending", "running", "succeeded", "failed"
]


class CliffCalculationItem(StrictReportAPIModel):
"""How far one side's cliff calculation of its simulation run has got.

``status`` is ``not_calculated`` while the simulation run has no cliff
calculation, ``pending`` or ``running`` while one is under way,
``succeeded`` once it has its result, and ``failed`` once its newest
calculation failed and none is under way; ``error_message`` then says
why, and is null otherwise.
"""

status: CliffCalculationStatus
error_message: str | None


class ReportCliffsItem(StrictReportAPIModel):
"""How far the cliff calculations of the run read's two simulation runs have got.

A simulation run's cliffs are calculated apart from it, once, when a
create or re-run asks with ``include_cliffs``, and every report naming
the run shares them. ``status`` is ``succeeded`` once both sides are;
otherwise ``failed`` when either side is, else ``not_calculated`` when
either side is, else ``running`` when either side is, else ``pending``.
Running the report again with ``include_cliffs`` on the current versions
starts a new calculation for each side that is ``not_calculated`` or
``failed``, and joins one under way; a run on older versions is not run
again, so its re-run answers another run, with that run's ``cliffs``. A
report naming one simulation run on both sides gives its calculation for
each.
"""

status: CliffCalculationStatus
baseline: CliffCalculationItem
reform: CliffCalculationItem


class ReportItem(ReportSummaryItem):
"""An economy report with its run's result.

``result`` is the single-year economy result, in the format the app reads
today, once the run read has succeeded, and null otherwise.
today, once the run read has succeeded, and null otherwise. Its
``cliff_impact`` is the two simulation runs' cliff results once ``cliffs``
is ``succeeded``, and null otherwise. ``cliffs`` says how far their cliff
calculations have got, whatever the run's status, and is null for a
report with no run.
"""

result: EconomyResult | None
cliffs: ReportCliffsItem | None

@classmethod
def from_read(cls, read: ReportRead) -> ReportItem:
Expand Down
32 changes: 24 additions & 8 deletions policyengine_api/fastapi_routes/v2/reports/routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@
HouseholdResultUnreadableError,
)
from policyengine_api.services.v2.stored_reports.validators import (
CliffsNotAvailableError,
CreatedReportUnreadableError,
ForcedRerunRequiresAdminError,
ForcedRerunRequiresSignInError,
Expand Down Expand Up @@ -131,11 +132,13 @@
StoredReportNotFoundError,
ReportRunNotFoundError,
ForcedRerunRequiresAdminError,
CliffsNotAvailableError,
*SUBMISSION_REFUSALS,
)
REPORT_ERROR_MAPPINGS = (
V2ErrorMapping((StoredReportNotFoundError, ReportRunNotFoundError), 404),
V2ErrorMapping((ForcedRerunRequiresAdminError,), 403),
V2ErrorMapping((CliffsNotAvailableError,), 422),
*SUBMISSION_ERROR_MAPPINGS,
V2ErrorMapping(
(
Expand Down Expand Up @@ -321,10 +324,10 @@ def _rerun_report(
*,
country_id: str,
report_id: UUID,
force: bool,
body: ReportRerunRequest,
requester: AccountPrincipal | None,
) -> ReportDetailResponse | JSONResponse:
"""Run the report again and answer it with the run the request ended on.
"""Run the report again, as ``body`` asks; answer it with the run it ended on.

The simulation service's refusal to run it again now answers 409 with
the run it names; a report that cannot be read back once its run started
Expand All @@ -339,7 +342,8 @@ def _rerun_report(
report = service.rerun_report(
country_id=country_id,
report_id=report_id,
force=force,
force=body.force,
include_cliffs=body.include_cliffs,
requester=requester,
)
except (StandardUserRequiresSignInError, ForcedRerunRequiresSignInError) as error:
Expand Down Expand Up @@ -390,7 +394,12 @@ def _add_report_run_routes(
"side reuses a run of its own simulation that succeeded on those "
"versions; with force, both simulations are calculated again. A "
"household report's sides are always calculated again, so force "
"changes nothing for it. A budget window's new run is a "
"changes nothing for it. With include_cliffs, the simulation "
"service also starts a cliff calculation for each of an economy "
"report run's simulation runs that has none, or whose newest one "
"failed, and the answer's cliffs says how far they have got; a "
"household report or budget window asking for cliffs answers 422 "
"before anything is asked. A budget window's new run is a "
"budget-window run with a report run for each year, and "
"with force each year calculates its simulations again. Answers the "
"report as stored, with the run the simulation service named (a "
Expand All @@ -416,7 +425,7 @@ def rerun() -> ReportDetailResponse | JSONResponse:
service_factory(),
country_id=query.country_id,
report_id=report_id,
force=body.force,
body=body,
requester=requester,
)

Expand Down Expand Up @@ -475,8 +484,12 @@ def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter:
"local authority's impact and the codes of those withheld; the "
"simulation service takes it for uk and its four nations only, on a "
"release that gives local areas a dataset of their own, and the "
"Public API answers its refusal with 422. A household report (kind "
"household) "
"Public API answers its refusal with 422. With include_cliffs, the "
"simulation service also starts a cliff calculation for each of an "
"economy report's two simulation runs that has none, or whose newest "
"one failed, and joins one under way; a simulation service that "
"doesn't calculate cliffs per simulation run yet refuses it with 422. "
"A household report (kind household) "
"is checked the same way, except that the country must have "
"household calculations instead (a household-only country does), "
"and the household it names must be stored in the country, with a "
Expand Down Expand Up @@ -564,7 +577,10 @@ def read() -> ReportListResponse | JSONResponse:
"its result. Its label and description are the requesting user's "
"saved report's name and description, null without a user "
"credential or a saved report. An economy report's run is one report "
"run and its result today's economy result. A household report's "
"run and its result today's economy result; its cliffs say how far "
"the cliff calculations of the run's two simulation runs have got, "
"whatever the run's status, and the result's cliff_impact holds them "
"once both have succeeded. A household report's "
"result is each simulation's calculated household, as "
"/v2/household-calculations answers one, and a failed run gives each "
"side's error. A budget window's run is a budget-window run with a "
Expand Down
13 changes: 11 additions & 2 deletions policyengine_api/fastapi_routes/v2/reports/run_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,17 @@ class ReportRerunRequest(StrictSubmissionModel):
Without ``force`` (``{}``), each side reuses a run of its own simulation
that succeeded on those versions; with it, both simulations are
calculated again. A household report's sides are always calculated
again. The new run is kept beside every earlier one.
again. The new run is kept beside every earlier one. ``include_cliffs``
also starts a cliff calculation for each of the run's two simulation
runs that has none, or whose newest one failed, and joins one under way;
the report's ``cliffs`` then says how far they have got. Only an
economy report has cliffs: a household report or budget window asking
for them is refused with 422, and so is any request with it while the
simulation service doesn't calculate cliffs per simulation run yet.
"""

force: StrictBool = False
include_cliffs: StrictBool = False


class ReportRunListResult(StrictReportAPIModel):
Expand Down Expand Up @@ -178,7 +185,9 @@ class RerunReportUnreadableResponse(V2ErrorResponse):
422: {
"model": V2MissingParametersErrorResponse | V2ErrorResponse,
"description": (
"The request does not match the schema; the country has no economy "
"The request does not match the schema; a household report or "
"budget window asks for cliffs (include_cliffs), which only an "
"economy report has; the country has no economy "
"reports, or no household calculations for a household report; a "
"policy of the report's simulations sets "
"parameters the running catalog version does not have (code "
Expand Down
20 changes: 16 additions & 4 deletions policyengine_api/libs/simulation_report_reruns.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,14 @@
``start_report_rerun`` is what ``SimulationServiceReportClient.rerun_report``
does: it posts ``{"force": …}`` to the Cloud Run simulation service's
``POST /reports/{report_id}/runs``, through the same HTTP client as the
service's other v2 routes (``policyengine_api.libs.simulation_reports``).
The service creates the stored report's new run on its default worker's
service's other v2 routes (``policyengine_api.libs.simulation_reports``),
with ``"include_cliffs": true`` when the re-run asks for cliffs. The
service creates the stored report's new run on its default worker's
versions and starts it, keeping every earlier run. Without ``force``, each
side reuses a run of its own simulation that succeeded on those versions.
With ``include_cliffs``, it also starts a cliff calculation for each side's
simulation run that has none; until it calculates cliffs per simulation
run, it refuses the field with 422, which is passed on as any 422 is.

The Public API reads the report in its country before asking, so it never
asks about a report it does not have. The simulation service answers:
Expand Down Expand Up @@ -132,8 +136,16 @@ def report_runs_path(report_id: UUID) -> str:


def report_rerun_request(rerun: ReportRerunInput) -> dict[str, Any]:
"""Return the simulation service's request body for the re-run."""
return {"force": rerun.force}
"""Return the simulation service's request body for the re-run.

``include_cliffs`` is sent only when true: a simulation service from
before cliffs were calculated per simulation run refuses the field, so a
re-run that doesn't ask for cliffs still runs there.
"""
body: dict[str, Any] = {"force": rerun.force}
if rerun.include_cliffs:
body["include_cliffs"] = True
return body


def post_report_rerun(
Expand Down
22 changes: 15 additions & 7 deletions policyengine_api/services/v2/simulation_service/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -258,12 +258,17 @@ def require_spm_object(cls, value: object) -> object:
class EconomyReportFields(ReportDefinitionFields):
"""An economy report: a baseline and a reform simulation of one region's data.

``include_cliffs`` also calculates the baseline's and reform's cliff
impact. ``data_source`` ``local_area_dataset`` calculates both
simulations on the dataset the catalog version gives local areas
instead of the region's, so the result also has each constituency's and
local authority's impact and the codes of those disclosure control
withheld; omit it, rather than sending null, for the region's dataset.
``include_cliffs`` also starts a cliff calculation for each of the two
simulation runs that has none, or whose newest one failed, and joins one
under way: a simulation run's cliffs are calculated once, apart from it,
and every report naming the run shares them. It is never stored. The
report's ``cliffs`` says how far they have got, and its result's
``cliff_impact`` holds them once both have succeeded.
``data_source`` ``local_area_dataset`` calculates both simulations on
the dataset the catalog version gives local areas instead of the
region's, so the result also has each constituency's and local
authority's impact and the codes of those disclosure control withheld;
omit it, rather than sending null, for the region's dataset.
The simulation service takes it only for ``uk`` and the four
``country/*`` nations, on a release that gives local areas a dataset of
their own, and refuses it with 422 otherwise: the Public API checks only
Expand Down Expand Up @@ -427,14 +432,17 @@ class ReportRerunInput:
economy calculations. ``policy_ids`` are the policies of the report's
simulations, baseline first, None for current law, a report of the
baseline alone or a simulation that is gone, for the checks before the
simulation service is asked.
simulation service is asked. ``include_cliffs``, only for an economy
report, also starts a cliff calculation for each side's simulation run
that has none, or whose newest one failed; it is sent only when true.
"""

country_id: str
report_id: UUID
kind: ReportRerunKind
force: bool
policy_ids: tuple[UUID | None, ...]
include_cliffs: bool = False


class SimulationServiceClient(Protocol):
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@

from typing import TYPE_CHECKING

from sqlalchemy import case
from sqlmodel import col, select

from policyengine_api.data.v2.models import (
BudgetSummary,
CliffImpact,
CongressionalDistrictImpact,
ConstituencyImpact,
DecileImpact,
Expand All @@ -18,10 +20,12 @@
LocalAuthorityImpact,
Poverty,
ProgramStatistics,
SimulationStatus,
WithheldAreaCode,
)
from policyengine_api.services.v2.stored_reports.economy_results.types import (
EconomyResultRows,
ReportRunCliffRows,
ReportRunResultColumns,
)

Expand All @@ -33,20 +37,67 @@
from policyengine_api.data.v2.models import ReportRun


def read_economy_result_rows(
def _side_cliff_calculation(
session: Session, simulation_run_id: UUID
) -> CliffImpact | None:
"""Return the run's unfailed cliff calculation, else its newest failed one.

A run has at most one calculation that hasn't failed
(``uq_cliff_impacts_unfailed``), so ordering failed ones last reads it
first; among failed ones, the newest is read, the larger ID breaking a
tie in creation time.
"""
return session.exec(
select(CliffImpact)
.where(CliffImpact.simulation_run_id == simulation_run_id)
.order_by(
case((col(CliffImpact.status) == SimulationStatus.FAILED, 1), else_=0),
col(CliffImpact.created_at).desc(),
col(CliffImpact.id).desc(),
)
.limit(1)
).first()


def read_cliff_calculations(
session: Session,
*,
baseline_simulation_run_id: UUID,
reform_simulation_run_id: UUID,
) -> ReportRunCliffRows:
"""Return each side's cliff calculation of its simulation run, or None.

It is the run's calculation that hasn't failed, else its newest failed
one: one query per distinct run, so a report run naming one simulation
run on both sides reads it once, for both.
"""
baseline = _side_cliff_calculation(session, baseline_simulation_run_id)
reform = (
baseline
if reform_simulation_run_id == baseline_simulation_run_id
else _side_cliff_calculation(session, reform_simulation_run_id)
)
return ReportRunCliffRows(baseline=baseline, reform=reform)


def read_economy_result_rows( # noqa: PLR0913 # the session, then each part of the run the read needs
session: Session,
*,
country_id: str,
report_run: ReportRun,
reform_simulation_run_id: UUID,
on_local_area_dataset: bool,
cliff_calculations: ReportRunCliffRows,
) -> EconomyResultRows:
"""Return every result row of ``report_run``, one query per result table.

The comparison tables' rows are the report run's; the poverty and
inequality rows are those of its baseline and reform simulation runs.
The withheld area codes are read only for a local-area report's run
(``on_local_area_dataset``), whose writer records them.
``cliff_calculations`` are its simulation runs' cliff calculations, as
``read_cliff_calculations`` read them. The report run's own four cliff
columns are not read.
"""
report_run_id = report_run.id
simulation_run_ids = (
Expand All @@ -59,10 +110,6 @@ def read_economy_result_rows(
country_package_version=report_run.country_package_version,
data_version=report_run.data_version,
spm_provenance=report_run.spm_provenance,
baseline_cliff_gap=report_run.baseline_cliff_gap,
baseline_cliff_share=report_run.baseline_cliff_share,
reform_cliff_gap=report_run.reform_cliff_gap,
reform_cliff_share=report_run.reform_cliff_share,
),
baseline_simulation_run_id=report_run.baseline_simulation_run_id,
reform_simulation_run_id=reform_simulation_run_id,
Expand Down Expand Up @@ -141,6 +188,7 @@ def read_economy_result_rows(
)
)
),
cliff_calculations=cliff_calculations,
on_local_area_dataset=on_local_area_dataset,
withheld_area_codes=(
tuple(
Expand Down
Loading
Loading