teqo-backup/src/utilities/municipalityTerritorialClass.ts
Francisco Ignácio Fontoura Solla 0ef4ddac1d E10 /simplify: remove superficie morta, unifica o parser de enum repetivel e reusa o ranking A11
- campoVotes (sem leitor) e classification.fieldHeadroom (duplicava o fator field) removidos
- formatTerritorialClassWhy passa a ser mesmo a fonte unica do slice(0,2) e do fallback
  "sem serie", eliminando o sentinela de string vazia nas duas superficies de detalhe
- classe territorial vira um so componente com layout table|card, como os vizinhos
- parseExhaustiveEnumParam em campaignListUrl cobre trend e class (o includes era morto:
  allParamValues ja deduplica)
- bloco central caminha o computeVoteRankByYear memoizado do A11 em vez de reordenar
  os 435 slugs por conta propria
- comentarios corrigidos onde afirmavam o contrario do codigo (CampaignCellTooltip e a
  regra do sem_base por superficie)
2026-07-25 22:33:16 -03:00

234 lines
9.1 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

import {
federalBaselineMunicipalitySlugs,
getMunicipalityFederalBaseline,
getStatewideFederalTotals,
type MunicipalityFederalBaseline,
} from '@/lib/bahiaElectionAggregates'
import { ELECTION_YEAR_2022 } from '@/lib/electionResults'
import { computeVoteRankByYear } from '@/lib/municipalityVoteRank'
import { captureRate, ownVotes2022, projectedFieldCeiling } from '@/utilities/municipalityPotential'
/**
* E10 "classificação territorial relativa" — the operational class of one
* município, read from the committed `bahia-federal-baseline.json` artifact
* alone (pure functions, no DB, no `campaignGoals`, no user).
*
* Why relative anchors: the class the campaign inherited from the majoritarian
* era used absolute shares of local valid votes (35/20/10). In a federal-deputy
* race the candidate's local share is typically 1–5%, so every município in the
* state collapsed into the worst class. The research report (§6, "limiares
* 35/20/10 degeneram em DF") prescribes anchoring on multiples of the
* candidate's OWN statewide share (a location quotient) and reading more than
* one axis: dominance + how much of his own vote lives here + how much field
* vote is still uncaptured.
*/
/** Reference year: the field ceiling is 2022-only in the artifact by design. */
const TERRITORIAL_CLASS_YEAR = ELECTION_YEAR_2022
export const TERRITORIAL_CLASSES = [
'reduto',
'expansao',
'manutencao',
'marginal',
'sem_base',
] as const
export type MunicipalityTerritorialClass = (typeof TERRITORIAL_CLASSES)[number]
/**
* Cuts are ILLUSTRATIVE, not calibrated: the research report gives the shape
* (LQ > 2–3 = reduto, ~1 = padrão, < 0,5 = fraqueza) and says the exact
* numbers can only come from a backtest against 2014–2022 — that is **E15**.
* They live here, named and versioned, so recalibration is a one-line diff
* with a test to prove what moved.
*/
export const TERRITORIAL_CLASS_ANCHORS = {
/** LQ at or above this = performing at least 2× his own statewide standard. */
strongLq: 2,
/** LQ below this = performing at less than half his own standard. */
weakLq: 0.5,
/** Municípios that together hold this share of his statewide vote are the "core block". */
coreCumulativeShare: 0.5,
} as const
/** The axes behind a class — the UI always shows the "por quê", never the label alone. */
type TerritorialFactorId = 'dominance' | 'ownShare' | 'field' | 'capture'
export type TerritorialFactor = {
id: TerritorialFactorId
/**
* `dominance` = LQ (ratio); `ownShare` = share of his statewide vote (0..1);
* `field` = uncaptured field votes (absolute); `capture` = capture rate (0..1).
*/
value: number
}
export type MunicipalityTerritorialClassification = {
class: MunicipalityTerritorialClass
/** Ordered by relevance to the class — surfaces show the first two. */
factors: TerritorialFactor[]
/** Location quotient vs. his own statewide share; null without a local electorate. */
lq: number | null
/** Share of his statewide vote that comes from here (the mesa's own anchor, A11). */
ownShare: number
/** True when the município belongs to the block holding `coreCumulativeShare` of his vote. */
inCoreBlock: boolean
}
export type TerritorialClassInput = {
ownVotes: number
validVotes: number
stateOwnVotes: number
stateValidVotes: number
/** Projected field ceiling minus own votes (E8), floored at 0. */
fieldHeadroom: number
/** Median `fieldHeadroom` across the catalog — the relative "big field" cut. */
medianFieldHeadroom: number
captureRate: number | null
inCoreBlock: boolean
}
const UNCLASSIFIED: MunicipalityTerritorialClassification = {
class: 'sem_base',
factors: [],
lq: null,
ownShare: 0,
inCoreBlock: false,
}
/**
* Pure classifier over explicit inputs (the artifact-backed wrapper below
* fills them in). Order of the rules is the reading order of the mesa:
* dominance first, then — only for the weak half — whether there is field
* left to win.
*/
export const classifyMunicipalityTerritory = (
input: TerritorialClassInput,
): MunicipalityTerritorialClassification => {
const { ownVotes, validVotes, stateOwnVotes, stateValidVotes } = input
if (validVotes <= 0 || stateValidVotes <= 0 || stateOwnVotes <= 0) return UNCLASSIFIED
const stateShare = stateOwnVotes / stateValidVotes
const lq = ownVotes / validVotes / stateShare
const ownShare = ownVotes / stateOwnVotes
const shared = { lq, ownShare, inCoreBlock: input.inCoreBlock }
const dominance: TerritorialFactor = { id: 'dominance', value: lq }
const ownShareFactor: TerritorialFactor = { id: 'ownShare', value: ownShare }
const fieldFactor: TerritorialFactor = { id: 'field', value: input.fieldHeadroom }
const captureFactor: TerritorialFactor[] =
input.captureRate === null ? [] : [{ id: 'capture', value: input.captureRate }]
if (lq >= TERRITORIAL_CLASS_ANCHORS.strongLq) {
// Reduto de conta vs. reduto simbólico is the `ownShare` factor's job
// (P10: the trophy município must not eat the agenda of the ones that
// close the quotient), not a fifth class.
return { ...shared, class: 'reduto', factors: [dominance, ownShareFactor, ...captureFactor] }
}
if (lq < TERRITORIAL_CLASS_ANCHORS.weakLq) {
// A município inside the core block carries real votes even while
// under-performing, so it can never read as "marginal" — the honest label
// there is expansão (big base, low penetration).
const hasFieldLeft = input.fieldHeadroom >= input.medianFieldHeadroom || input.inCoreBlock
return hasFieldLeft
? { ...shared, class: 'expansao', factors: [fieldFactor, dominance, ...captureFactor] }
: { ...shared, class: 'marginal', factors: [dominance, fieldFactor] }
}
return { ...shared, class: 'manutencao', factors: [dominance, ownShareFactor, ...captureFactor] }
}
/** Uncaptured field votes: projected 2022 field ceiling minus his own vote. */
const fieldHeadroomOf = (baseline: MunicipalityFederalBaseline): number =>
Math.max(0, projectedFieldCeiling(baseline) - ownVotes2022(baseline))
const median = (values: number[]): number => {
if (values.length === 0) return 0
const sorted = [...values].sort((a, b) => a - b)
const middle = Math.floor(sorted.length / 2)
return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle]
}
type CatalogContext = {
medianFieldHeadroom: number
coreBlockSlugs: ReadonlySet<string>
}
let catalogContext: CatalogContext | null = null
/**
* Catalog-wide reference values, computed once per process (the artifact is
* immutable): the median field headroom — a relative cut, so no magic vote
* count ages — and the set of municípios that, sorted by his own vote,
* accumulate `coreCumulativeShare` of his statewide total.
*/
const getCatalogContext = (): CatalogContext => {
if (catalogContext) return catalogContext
// Slugs whose majoritarian cell is missing would drag the median to zero and
// make every weak município read as "expansão".
const medianFieldHeadroom = median(
federalBaselineMunicipalitySlugs()
.map(getMunicipalityFederalBaseline)
.filter((baseline) => projectedFieldCeiling(baseline) > 0)
.map(fieldHeadroomOf),
)
// A11 already ranks every slug by own vote, descending, and memoizes it —
// walking that map is the same order this used to re-sort for itself.
const coreVoteTarget =
getStatewideFederalTotals(TERRITORIAL_CLASS_YEAR).ownVotes *
TERRITORIAL_CLASS_ANCHORS.coreCumulativeShare
const coreBlockSlugs = new Set<string>()
let accumulated = 0
for (const [slug, entry] of computeVoteRankByYear(TERRITORIAL_CLASS_YEAR)) {
if (accumulated >= coreVoteTarget) break
coreBlockSlugs.add(slug)
accumulated += entry.votes
}
catalogContext = { medianFieldHeadroom, coreBlockSlugs }
return catalogContext
}
const classificationBySlug = new Map<string, MunicipalityTerritorialClassification>()
/** Classification for one catalog slug — memoized, pure over the artifact. */
export const computeMunicipalityTerritorialClass = (
slug: string,
): MunicipalityTerritorialClassification => {
const cached = classificationBySlug.get(slug)
if (cached) return cached
const baseline = getMunicipalityFederalBaseline(slug)
const totals = getStatewideFederalTotals(TERRITORIAL_CLASS_YEAR)
const { medianFieldHeadroom, coreBlockSlugs } = getCatalogContext()
const classification = classifyMunicipalityTerritory({
ownVotes: ownVotes2022(baseline),
validVotes: baseline.validVotesByYear[String(TERRITORIAL_CLASS_YEAR)] ?? 0,
stateOwnVotes: totals.ownVotes,
stateValidVotes: totals.validVotes,
fieldHeadroom: fieldHeadroomOf(baseline),
medianFieldHeadroom,
captureRate: captureRate(baseline),
inCoreBlock: coreBlockSlugs.has(slug),
})
classificationBySlug.set(slug, classification)
return classification
}
/**
* Sort weight for the list's `classe` ordering: descending puts the
* municípios that carry the campaign (reduto) first and the ones without a
* baseline last, in either direction.
*/
export const territorialClassSortWeight: Record<MunicipalityTerritorialClass, number | null> = {
reduto: 4,
expansao: 3,
manutencao: 2,
marginal: 1,
sem_base: null,
}