Why Documenting GLM Decisions Matters
A generalized linear model (GLM) is not fully described by a coefficient table. A reviewer also needs to know what each row represents, how the response was defined, what probability model and link were used, how exposure entered the model, and exactly how each predictor was coded. These choices determine what the fitted values mean and whether another analyst can reproduce them.
The purpose of this record is narrower than a broad model summary: it preserves the technical specification and the reasoning behind it. It should identify consequential decisions, their alternatives where relevant, and known limits on interpretation or application. Documentation does not itself establish that a model is adequate; it makes the modeled quantity and the choices behind it transparent.
What the Specification Must Say
Start by naming the response in operational terms, not merely calling it “loss” or “frequency.” State the unit of observation, measurement units, time basis, and any inclusion or exclusion rules that define the data used. For example, a claim-count response per policy-year is different from a binary indicator that a policy had at least one claim. A severity response based on individual reported claims is different from total loss divided by policy exposure.
Next, identify the conditional distribution and link. For a Poisson count model with conditional mean \(\mu_i\), the response has variance \(\mu_i\), and the log link states that \(\log(\mu_i)\) is linear in the model terms. For a Gamma severity model with mean \(\mu_i\), a common variance specification is \(\operatorname{Var}(Y_i\mid x_i)=\phi\mu_i^2\), where \(\phi>0\) is a dispersion parameter. A documentation record should not imply that choosing a distribution proves its assumptions hold; it should state the assumed mean-variance relationship.
For each offset, give its definition, units, and role. In a frequency model, exposure \(e_i\) often enters as \(\log(e_i)\) with its coefficient fixed at one. List predictors with coding details: category levels and reference level, continuous-variable units, transformations and centering constants, and any interactions. Record the fitted terms or parameter estimates when the purpose is to preserve a particular model version. A name such as “territory” is not enough if the precise groupings are not stated.
State the response, row unit, time basis, monetary basis if applicable, and data rules that determine which outcomes are included.
Name the distribution, conditional mean and variance assumptions, link, offset, and all predictor terms.
Give factor levels, reference categories, units, transformation formulas, interaction definitions, and any basis or grouping rules.
Identify assumptions, known limitations, intended prediction scope, and conditions under which the specification should not be interpreted or applied without further consideration.
Why Exposure Is an Offset
For a Poisson frequency model, suppose \(N_i\) is the number of claims for observation \(i\), \(e_i>0\) is its exposure in policy-years, and \(\lambda_i\) is the expected claim count per policy-year. If the count is proportional to exposure, then \(\mu_i=E[N_i\mid x_i]=e_i\lambda_i\). Suppose the log of the annual rate is modeled as \(\log(\lambda_i)=x_i^\mathsf{T}\beta\). Substitution gives:
Thus \(\log(e_i)\) enters with coefficient fixed at one: it converts an annual rate into an expected count for the actual exposure. This is an offset, not an estimated predictor. The argument depends on the stated proportional-exposure assumption; if exposure does not represent time at risk in a meaningful way, or the assumed proportionality is unsuitable, this model form needs reconsideration rather than automatic use.
Worked Example: Recording a Poisson Frequency Specification
A hypothetical insurer models claim counts for policy records. Each row represents one policy’s experience during a stated observation period. A record has \(e=2.00\) policy-years of earned exposure, vehicle class “B,” and territory “Coastal.” The fitted hypothetical model uses \(N\sim\operatorname{Poisson}(\mu)\), a log link, and annual claim rate \(\log(\lambda)=\beta_0+\beta_B I_B+\beta_C I_C\). The fitted coefficients are \(\beta_0=\log(0.10)\), \(\beta_B=\log(1.50)\), and \(\beta_C=\log(1.20)\). Class A and Inland are the reference levels. Document the specification and calculate the record’s expected count.
Method and response. The response is the number of claims per policy record, not the claim rate itself. The count is modeled as Poisson conditional on the predictors, with conditional mean and variance both \(\mu\). The link is the natural logarithm.
Offset and predictors. The offset is \(\log(e)\), where \(e\) is earned exposure measured in policy-years, and its coefficient is fixed at one. The predictors are two indicator variables: \(I_B=1\) for vehicle class B and \(I_C=1\) for Coastal territory. Class A and Inland are the stated reference levels. No interaction is included.
Calculation. For this record, \(I_B=1\), \(I_C=1\), and \(e=2.00\). The annual rate is \(\lambda=\exp(\log(0.10)+\log(1.50)+\log(1.20))=0.10(1.50)(1.20)=0.18\) claims per policy-year. Therefore, \(\mu=e\lambda=2.00(0.18)=0.36\) expected claims.
Limitation to record. This specification assumes counts are conditionally Poisson and expected count is proportional to policy-year exposure. It describes the assumed model, not evidence that those assumptions are adequate in every application.
Common mistake avoided. Calling \(0.18\) the expected count for this two-year record omits exposure. It is the modeled annual rate; the expected count is \(2.00(0.18)=0.36\).
Documenting Severity and Predictor Construction
The response definition is especially important when the model is conditional on a claim having occurred. State whether severity is measured gross or net of specified adjustments, the currency and valuation basis, and whether each row is one claim or some aggregated unit. A severity model fitted to reported claims does not, by itself, describe the probability of a claim occurring.
Predictor descriptions should be equally specific. For a transformed continuous variable, write the transformation formula and its input units. For an interaction, state which terms are multiplied and how to interpret the resulting conditional effect. A limitation should be concrete: for example, a specified variable is measured coarsely, certain combinations have little representation in the modeled data, or the intended application is restricted to a defined population. Avoid vague statements such as “results may vary” that do not tell a reader what to be cautious about.
Worked Example: Documenting a Gamma Severity Model
A hypothetical model uses individual claim severities \(Y_i\), measured in dollars, for claims in a defined coverage and valuation basis. The assumed conditional distribution is Gamma, with mean \(\mu_i\) and variance \(\phi\mu_i^2\), where \(\phi\) is a positive dispersion parameter. The log-mean model is \(\log(\mu_i)=\beta_0+\beta_H I_H\). The fitted intercept is \(\log(800)\), and the coefficient for high-use category H is \(\log(1.25)\). The reference category is standard use. State the record and calculate the predicted mean for a high-use claim.
Method and response. The response is the dollar severity of one claim, conditional on a claim being present in the modeled data. The assumed distribution is Gamma; its specified conditional mean is \(\mu_i\), and its variance is \(\phi\mu_i^2\). The link is logarithmic.
Predictor definition. \(I_H\) is a binary indicator equal to one for high-use and zero for standard-use claims. Standard use is the reference category. There is no exposure offset because the response is severity per claim rather than a count over policy exposure.
Calculation. For high use, \(I_H=1\), so \(\log(\mu)=\log(800)+\log(1.25)=\log(800\times1.25)=\log(1{,}000)\). Consequently, the predicted mean severity is \(\mu=\$1{,}000.00\), reported to the cent.
Limitation to record. The model concerns severity conditional on an included claim and does not provide a claim frequency estimate. The record should also identify the coverage and valuation rules used to define the dollar response; changing those rules changes the modeled quantity.
Common mistake avoided. Treating this severity model as if its prediction were a policy-level expected loss would omit claim frequency. The calculated \(\$1{,}000.00\) is a conditional mean per claim under the specified model, not a pure premium per policy.
Interactions, Transformations, and Interpretability
An interaction allows the association for one predictor to depend on another predictor. In a log-link model, an interaction coefficient changes the log-scale slope or contrast; it should not be described as a constant dollar change. A reproducible specification names the interacting variables and gives their coding. If a continuous predictor is transformed, retaining only the label “log mileage” is insufficient: the log base, units, and any scaling constant affect the coefficient interpretation and must be recorded.
The next example illustrates a rate model with an explicitly defined transformation and interaction. All data and parameter values are hypothetical. The calculation shows why a coefficient for a category can have a different multiplicative interpretation at different values of a continuous predictor.
Worked Example: Recording a Transformed Predictor and Interaction
A hypothetical Poisson model predicts claim counts using policy-year exposure \(e\). Define \(z=\log(M/10{,}000)\), where \(M\) is annual mileage measured in miles, and let \(R=1\) for the North region and \(R=0\) for the South reference region. The rate model is \(\log(\lambda)=\beta_0+0.20z+0.30R-0.10(Rz)\), with \(\beta_0=\log(0.04)\). For a North-region record with \(M=20{,}000\) miles and \(e=1.50\) policy-years, document the terms and calculate the expected count.
Method and specification. The response is a claim count per policy record, assumed Poisson conditional on the modeled terms. The link is log, and the offset is \(\log(e)\) with fixed coefficient one. The mileage transformation is the natural logarithm of annual miles divided by 10,000; the reference mileage is therefore 10,000 miles, for which \(z=0\). The region indicator uses South as the reference. The interaction is the product \(Rz\).
Calculate the transformed value. Here \(z=\log(20{,}000/10{,}000)=\log(2)=0.693147\). With \(R=1\), the rate’s log is \(\log(0.04)+0.20(0.693147)+0.30-0.10(0.693147)\) \(=\log(0.04)+0.30+0.10(0.693147)=\log(0.04)+0.369315\).
Calculate rate and expected count. The annual rate is \(\lambda=0.04\exp(0.369315)\approx0.0579\) claims per policy-year. For \(e=1.50\), the expected count is \(\mu=1.50(0.0578697)\approx0.0868\) claims. Final rates and counts are rounded to four decimal places.
Interpret the interaction. At this mileage, the North-to-South rate ratio is \(\exp(0.30-0.10\log(2))=\exp(0.230685)\approx1.2594\). The regional multiplicative contrast is therefore conditional on mileage; it is not always \(\exp(0.30)\).
Limitation and common mistake avoided. The record should note that the specification imposes a linear relationship in log mileage and a particular region-by-mileage interaction. Reporting \(\exp(0.30)\) as the North-to-South rate ratio at every mileage ignores the interaction and gives the wrong interpretation.
Limitations Belong Beside the Specification
A useful limitation statement distinguishes three things. First are model assumptions, such as a chosen conditional distribution, link form, or proportional relationship with exposure. Second are data and coding boundaries, such as the population, time period, coverage definition, reference categories, or ranges represented by the predictor construction. Third are interpretive limits: a predictive association is not automatically a causal effect, and an estimate should not be presented as applying beyond the population or conditions for which it was specified.
Documentation should not conceal a decision inside software defaults. If categories were combined, a continuous variable was capped, or an interaction was deliberately omitted, record the rule and its rationale in clear terms. If a limitation is not resolved, state that it remains unresolved rather than implying that the model specification has removed it.
A common documentation failure is to list predictor names and coefficients while leaving the response basis, exposure unit, or reference levels unstated. Such a record can be numerically detailed but still fail to define what the predictions represent. Another failure is to treat a limitation paragraph as a substitute for the actual model formula. The strongest record provides both: a reconstructable specification and appropriately bounded interpretation.
Check Your Understanding
For each hypothetical specification, identify the key modeling detail and check the calculation.
- A Poisson count model has annual rate \(0.06\) for a listed risk class, with a multiplicative zone factor of \(1.4\). The policy has \(3.00\) policy-years of exposure. What is its expected claim count, and what exposure term should be documented? (Answer: Expected count \(=3.00(0.06)(1.4)=0.252\); document offset \(\log(e)\), with \(e\) in policy-years and coefficient fixed at one.)
- A Gamma log-link severity model has baseline mean \(\$1{,}200\) and a fitted log-scale coefficient \(\log(1.10)\) for a category. What is the category’s predicted mean, and what does it represent? (Answer: \(\$1{,}200(1.10)=\$1{,}320.00\), the conditional mean severity per claim under the stated model.)
- A Poisson frequency model has annual rate \(0.08\exp(0.25)\) for a particular indicator value and exposure \(0.50\) policy-years. Calculate expected count to four decimals. (Answer: \(0.50(0.08)\exp(0.25)=0.0514\) expected claims.)
- A log-rate model includes \(0.20R+0.30z-0.15Rz\), where \(R\) is a binary region indicator and \(z=\log(M/10{,}000)\). At \(M=40{,}000\), calculate the rate ratio for \(R=1\) versus \(R=0\). (Answer: \(\exp(0.20-0.15\log(4))\approx0.9921\); the interaction makes the ratio depend on mileage.)
- A count model uses a Poisson distribution, log link, and offset \(\log(e)\). Explain why documenting “exposure” without its unit and coefficient treatment is incomplete. (Answer: The exposure unit determines the basis of the offset, and the offset coefficient must be fixed at one under the proportional-exposure model; without those details, the modeled count and rate basis cannot be reconstructed unambiguously.)