# ============================================================================
# POL 213 — Week 7: Ordered & Multinomial Logit
# ============================================================================
#
# Two new outcome types in this script:
#   1. Ordered Y (1 < 2 < 3 < 4) — Afrobarometer support for one-party rule
#   2. Nominal Y (D / I / R)     — GSS party identification
#
# Both follow the same workflow:
#   stacked binary logits → unified MLE → predicted probabilities → assumption test

# ---- Setup ----

library(tidyverse)
library(juanr)
library(broom)
library(modelsummary)
library(marginaleffects)
library(MASS, exclude = "select")   # polr() — load BEFORE tidyverse functions
library(nnet)                        # multinom()
library(brant)                       # Brant test for proportional odds
library(mlogit)                      # Hausman-McFadden test for IIA
library(socviz)                      # gss_sm


# ============================================================================
# PART 1: ORDERED LOGIT
# ============================================================================
#
# Data: juanr::afrobarometer (Ethiopia Round 7, ~2,300 respondents)
# Outcome `opr`: support for one-party rule (4-point ordered scale)
# Focal predictor: education (4 buckets, coded numerically 1..4)


# ---- Data prep ----

afro = juanr::afrobarometer |>
  filter(one_party_rule %in% c(1, 2, 4, 5)) |>     # drop the "neither" category
  mutate(
    opr = factor(
      case_when(
        one_party_rule == 1 ~ 1L,
        one_party_rule == 2 ~ 2L,
        one_party_rule == 4 ~ 3L,
        one_party_rule == 5 ~ 4L),
      levels = 1:4,
      labels = c("Strongly disapprove", "Disapprove",
                 "Approve", "Strongly approve"),
      ordered = TRUE),
    opr_num = as.numeric(opr),
    # collapse education into 4 ordered buckets, then code numerically
    edu_num = as.numeric(factor(
      case_when(
        education %in% c("none", "informal") ~ "None / informal",
        education %in% c("some primary", "primary") ~ "Primary",
        education %in% c("some secondary", "secondary") ~ "Secondary",
        education %in% c("post-secondary", "some university",
                          "university", "post-graduate") ~ "Post-secondary"),
      levels = c("None / informal", "Primary", "Secondary", "Post-secondary"),
      ordered = TRUE))) |>
  drop_na(opr, age, gender, urban, edu_num)


# ---- Look at the outcome ----

# 4 categories with a clear shape: most people disapprove, smaller approve tail
afro |>
  count(opr) |>
  mutate(pct = n / sum(n))


# ============================================================================
# Section 1: Why not OLS on a 1–4 coded outcome?
# ============================================================================

# OLS treats Y = 1, 2, 3, 4 as if it had real spacing. Three problems:
#   1. The integer codes (1..4) are arbitrary
#   2. The slope on education inherits that arbitrary scale
#   3. OLS returns ONE number per respondent, not a probability over categories

mod_ols = lm(opr_num ~ age + gender + urban + edu_num, data = afro)
tidy(mod_ols)

# OLS predictions cluster narrowly in [1.6, 2.0], even though Y spans 1..4 —
# the conditional mean squashes the gradient
augment(mod_ols) |>
  ggplot(aes(x = .fitted, y = opr_num)) +
  geom_jitter(width = 0, height = 0.15, alpha = 0.25, color = "#022851") +
  scale_x_continuous(limits = c(1, 4), breaks = 1:4) +
  scale_y_continuous(breaks = 1:4)


# ============================================================================
# Section 2: Stacked binary logits — the build-up to polr
# ============================================================================
#
# Strategy: re-express the ordered problem as J - 1 = 3 binary logits, one per
# cumulative cut (Y >= 2, Y >= 3, Y >= 4). Each is a Week 3 binary logit.

mod_b1 = glm(opr_num >= 2 ~ edu_num + age + gender + urban,
             data = afro, family = binomial())
mod_b2 = glm(opr_num >= 3 ~ edu_num + age + gender + urban,
             data = afro, family = binomial())
mod_b3 = glm(opr_num >= 4 ~ edu_num + age + gender + urban,
             data = afro, family = binomial())

# Compare the three slopes on edu_num — similar in sign + magnitude?
tibble(
  cut = c("Y ≥ Disapprove", "Y ≥ Approve", "Y = Strongly approve"),
  slope_edu_num = c(coef(mod_b1)["edu_num"],
                    coef(mod_b2)["edu_num"],
                    coef(mod_b3)["edu_num"]),
  intercept     = c(coef(mod_b1)[1],
                    coef(mod_b2)[1],
                    coef(mod_b3)[1]))

# If proportional odds holds, these three slopes differ only by chance.
# Pooling them into ONE shared β is what ordered logit does.


# ============================================================================
# Section 3: Fit ordered logit with MASS::polr()
# ============================================================================

mod_ord = polr(opr ~ edu_num + age + gender + urban,
               data   = afro,
               method = "logistic",
               Hess   = TRUE)         # Hess = TRUE → store covariance for SEs

# polr returns:
#   coef(mod_ord) — slope on each covariate (one shared β across cuts)
#   mod_ord$zeta — three cutpoints τ₁ < τ₂ < τ₃ on the latent scale
coef(mod_ord)
mod_ord$zeta

# Compare polr's single β on edu_num against the three stacked-logit slopes
tibble(
  source = c("polr (ordered)",
             "glm: Y ≥ Disapprove",
             "glm: Y ≥ Approve",
             "glm: Y = Strongly approve"),
  slope_edu_num = c(coef(mod_ord)["edu_num"],
                    coef(mod_b1)["edu_num"],
                    coef(mod_b2)["edu_num"],
                    coef(mod_b3)["edu_num"]))


# ---- Coefficient scale: log cumulative-odds ----

# β is on the log-odds scale, just like Week 3 — but it's the log of
# CUMULATIVE odds: exp(β) = odds ratio of being in a higher category vs.
# at-or-below, applied identically at every cut (that's proportional odds)
exp(coef(mod_ord)["edu_num"])   # multiplicative shift in cumulative odds


# ============================================================================
# Section 4: Compute the log-likelihood by hand
# ============================================================================
#
# Goal: verify polr is just running MLE on the ordered-logit likelihood.
# To keep it readable, fit a bivariate version (opr ~ edu_num only) so the
# linear predictor is just β × edu_num, no matrices.

m_simple = polr(opr ~ edu_num, data = afro)

# Write the log-lik as a function of (β, τ_1, τ_2, τ_3)
log_lik = function(b, t1, t2, t3) {
  # pad with ±Inf so τ_0 and τ_J are explicit:
  # tau = [-Inf, τ_1, τ_2, τ_3, +Inf]   in positions 1..5
  tau = c(-Inf, t1, t2, t3, Inf)
  eta = b * X                              # linear predictor (scalar × vector)
  # plogis(z) is R's name for σ(z) = 1 / (1 + exp(-z))
  #
  # For respondent i in category Y_i:
  #   upper cut = tau[Y_i + 1]  (the +1 offset comes from -Inf in slot 1)
  #   lower cut = tau[Y_i]
  # e.g. Y_i = 2 (Disapprove) → tau[3] = τ_2 (upper), tau[2] = τ_1 (lower)
  p = plogis(tau[Y + 1] - eta) - plogis(tau[Y] - eta)
  sum(log(p))
}

# Plug in polr's estimates and compare to logLik(m_simple)
X     = afro$edu_num
Y     = as.integer(afro$opr)
b_hat = coef(m_simple)
tau   = m_simple$zeta

c(by_hand = log_lik(b_hat, tau[1], tau[2], tau[3]),
  polr    = as.numeric(logLik(m_simple)))   # should match to machine precision


# ============================================================================
# Section 5: Predicted probabilities by hand — one category
# ============================================================================
#
# Compute Pr(Approve) at each education level using mod_ord. "Approve" is a
# middle category, so the formula uses BOTH cutpoints (the σ-difference is
# doing real work):
#   Pr(Y = Approve) = σ(τ_3 - Xβ) - σ(τ_2 - Xβ)

b = coef(mod_ord)
t = mod_ord$zeta

# Linear predictor for a "typical" respondent at edu = 1, 2, 3, 4:
# mean age, female (baseline), rural (baseline) → those dummies are all 0
xb = b["edu_num"] * 1:4 + b["age"] * mean(afro$age)

pr_approve = plogis(t[3] - xb) - plogis(t[2] - xb)
round(pr_approve, 3)

# Verify against marginaleffects::predictions()
predictions(
  mod_ord,
  newdata = data.frame(edu_num = 1:4,
                       age     = mean(afro$age),
                       gender  = "female",
                       urban   = "rural"),
  type = "probs") |>
  as_tibble() |>
  dplyr::filter(group == "Approve") |>
  dplyr::select(edu_num, estimate)


# ============================================================================
# Section 6: Predicted probabilities across education — all four categories
# ============================================================================

preds = predictions(mod_ord,
                    newdata = datagrid(edu_num = 1:4),
                    type    = "probs") |>
  as_tibble() |>
  dplyr::select(edu_num, category = group,
                prob = estimate, conf.low, conf.high)

preds |>
  mutate(category = factor(category,
                           levels = c("Strongly disapprove", "Disapprove",
                                      "Approve", "Strongly approve"))) |>
  ggplot(aes(x = edu_num, y = prob, color = category, fill = category)) +
  geom_ribbon(aes(ymin = conf.low, ymax = conf.high),
              alpha = 0.18, color = NA) +
  geom_line(linewidth = 1.1) +
  geom_point(size = 2.6) +
  scale_y_continuous(labels = scales::percent, limits = c(0, NA)) +
  labs(x = "education (1 = none, 4 = post-secondary)",
       y = "Pr(Y = j | X)")
# Shaded bands are 95% CIs from the delta method (requires Hess = TRUE in polr)


# ============================================================================
# Section 7: Average marginal effects per category
# ============================================================================
#
# The marginal effect of X on Pr(Y = j) is the derivative of the σ-difference:
#   ∂Pr(Y = j)/∂X = -β · [σ(τ_j - Xβ)(1 - σ(τ_j - Xβ))
#                         - σ(τ_{j-1} - Xβ)(1 - σ(τ_{j-1} - Xβ))]
# AME averages this across the sample. avg_slopes() does it for us:

ame_edu = avg_slopes(mod_ord, variables = "edu_num", type = "probs")
ame_edu

# Each row says: averaging across the sample, a one-step increase in education
# changes the probability of category j by this much. The four numbers sum to
# zero (probability has to come from somewhere)


# ============================================================================
# Section 8: Testing proportional odds — Brant test
# ============================================================================
#
# Restricted model: polr's single β per covariate (proportional odds imposed)
# Unrestricted model: J - 1 separate β's per covariate (one per cut)
# H_0: all J - 1 slopes are equal across cuts → if we can't reject, pooling
# is defensible

brant_test = brant::brant(mod_ord)
brant_test

# Per-covariate rows test whether THAT variable's slope differs across cuts.
# Omnibus row tests whether ANY covariate violates prop odds.
# Read the p-values: small → violation; large → defensible to pool.



# ============================================================================
# PART 2: MULTINOMIAL LOGIT
# ============================================================================
#
# Data: socviz::gss_sm (GSS 2016, ~2,800 respondents)
# Outcome `partyid3`: Democrat / Independent / Republican (NOMINAL — no order)
# Focal predictor: education (3 buckets, coded numerically 1..3)


# ---- Data prep ----

gss = socviz::gss_sm |>
  filter(!is.na(partyid), partyid != "Other Party") |>
  mutate(
    partyid3 = factor(
      case_when(
        partyid %in% c("Strong Democrat", "Not Str Democrat", "Ind,near Dem") ~ "Democrat",
        partyid == "Independent"                                              ~ "Independent",
        partyid %in% c("Ind,near Rep", "Not Str Republican", "Strong Republican") ~ "Republican"),
      levels = c("Independent", "Democrat", "Republican")),
    religion4 = factor(
      case_when(
        religion %in% c("Protestant") ~ "Protestant",
        religion %in% c("Catholic")   ~ "Catholic",
        religion %in% c("None")       ~ "None",
        TRUE                          ~ "Other"),
      levels = c("Protestant", "Catholic", "None", "Other")),
    educ3 = factor(
      case_when(
        degree %in% c("Lt High School", "High School") ~ "HS or less",
        degree %in% c("Junior College")                ~ "Some college",
        degree %in% c("Bachelor", "Graduate")          ~ "BA or higher"),
      levels = c("HS or less", "Some college", "BA or higher")),
    educ_num = as.numeric(educ3)) |>
  drop_na(partyid3, age, sex, race, educ3, religion4)


# ============================================================================
# Section 9: Stacked binary logits — the build-up to multinomial
# ============================================================================
#
# Pick Independent as the baseline. Fit K - 1 = 2 binary logits:
#   Dem vs. Ind   (drop Republicans)
#   Rep vs. Ind   (drop Democrats)

mod_di = glm(I(partyid3 == "Democrat") ~ educ_num + age + sex + race + religion4,
             data   = filter(gss, partyid3 != "Republican"),
             family = binomial)

mod_ri = glm(I(partyid3 == "Republican") ~ educ_num + age + sex + race + religion4,
             data   = filter(gss, partyid3 != "Democrat"),
             family = binomial)

# Compare slopes on edu_num — unlike ordered logit, no reason to expect them
# to be equal: each contrast has its own effect
tibble(
  contrast      = c("Dem vs. Ind", "Rep vs. Ind"),
  slope_edu_num = c(coef(mod_di)["educ_num"],
                    coef(mod_ri)["educ_num"]),
  intercept     = c(coef(mod_di)[1],
                    coef(mod_ri)[1]))

# Two limitations of stacked binary logits:
#   1. Each contrast uses a different subsample (throws away information)
#   2. The probabilities don't have to sum to 1
# A unified model fixes both — fit all contrasts jointly on everyone, and
# normalize so probabilities sum to 1


# ============================================================================
# Section 10: Fit multinomial logit with nnet::multinom()
# ============================================================================

mod_mn = multinom(partyid3 ~ educ_num + age + sex + race + religion4,
                  data  = gss,
                  trace = FALSE)

# Two sets of coefficients — one for "Dem vs. Ind", one for "Rep vs. Ind".
# Coefficients are LOG RELATIVE-RISK RATIOS (log of cumulative-odds equivalent
# for the multinomial), not directly interpretable. Reach for predicted
# probabilities and AMEs.
coef(mod_mn)

# exp(β) = odds ratio of that category vs. baseline per one-unit X change
exp(coef(mod_mn)[, "educ_num"])


# ---- How similar is multinom to the stacked binary logits? ----

# multinom uses everyone (full sample); the binary glms drop the third
# category. Dem-vs-Ind should match closely; Rep-vs-Ind may drift more.
tibble(
  contrast      = c("Dem vs. Ind", "Rep vs. Ind"),
  glm_slope     = c(coef(mod_di)["educ_num"],   coef(mod_ri)["educ_num"]),
  multinom_slope = c(coef(mod_mn)["Democrat",   "educ_num"],
                     coef(mod_mn)["Republican", "educ_num"]))


# ============================================================================
# Section 11: Compute the multinomial log-likelihood by hand
# ============================================================================
#
# As before, use a bivariate model to keep it readable:
#   partyid3 ~ educ_num
# Two non-baseline categories (Dem, Rep) → four parameters total.

m_simple_mn = multinom(partyid3 ~ educ_num, data = gss, trace = FALSE)

# Log-likelihood as a function of the four parameters
log_lik_mn = function(b0_d, b1_d, b0_r, b1_r) {
  eta_d = b0_d + b1_d * X                  # linear predictor for Dem
  eta_r = b0_r + b1_r * X                  # linear predictor for Rep
  # softmax denominator: Ind contributes exp(0) = 1 (it's the baseline)
  denom = 1 + exp(eta_d) + exp(eta_r)
  # probability of each respondent's observed category
  p = ifelse(Y == 1, 1          / denom,   # Y = Ind   → numerator = 1
      ifelse(Y == 2, exp(eta_d) / denom,   # Y = Dem   → numerator = exp(η_d)
                     exp(eta_r) / denom))  # Y = Rep   → numerator = exp(η_r)
  sum(log(p))
}

X = gss$educ_num
Y = as.integer(gss$partyid3)               # 1 = Ind, 2 = Dem, 3 = Rep
b = coef(m_simple_mn)

c(by_hand  = log_lik_mn(b["Democrat",   "(Intercept)"],
                        b["Democrat",   "educ_num"],
                        b["Republican", "(Intercept)"],
                        b["Republican", "educ_num"]),
  multinom = as.numeric(logLik(m_simple_mn)))


# ============================================================================
# Section 12: Predicted probabilities by hand — one category
# ============================================================================
#
# Compute Pr(Democrat) at each education level. Softmax with baseline = Ind
# (so exp(0) = 1 in the denominator):
#   Pr(Dem) = exp(Xβ_Dem) / [1 + exp(Xβ_Dem) + exp(Xβ_Rep)]

b = coef(mod_mn)            # 2 × 10 matrix
edus = 1:3                  # HS or less / Some college / BA+

# Linear predictor at each education level, with age at mean and other
# covariates at baseline (Male, White, Protestant → dummies = 0)
eta_dem = b["Democrat",   "(Intercept)"] +
          b["Democrat",   "educ_num"] * edus +
          b["Democrat",   "age"] * mean(gss$age)
eta_rep = b["Republican", "(Intercept)"] +
          b["Republican", "educ_num"] * edus +
          b["Republican", "age"] * mean(gss$age)

denom = 1 + exp(eta_dem) + exp(eta_rep)

pr_dem = exp(eta_dem) / denom
round(pr_dem, 3)

# Verify against marginaleffects
predictions(
  mod_mn,
  newdata = data.frame(
    educ_num  = edus,
    age       = mean(gss$age),
    sex       = "Male",
    race      = "White",
    religion4 = "Protestant"),
  type = "probs") |>
  as_tibble() |>
  dplyr::filter(group == "Democrat") |>
  dplyr::select(educ_num, estimate)


# ============================================================================
# Section 13: Predicted shares across education — all three categories
# ============================================================================

preds_mn = predictions(mod_mn,
                       newdata = datagrid(educ_num = 1:3),
                       type    = "probs") |>
  as_tibble() |>
  dplyr::rename(category = group, prob = estimate)

preds_mn |>
  mutate(category = factor(category,
                           levels = c("Democrat", "Independent", "Republican"))) |>
  ggplot(aes(x = educ_num, y = prob,
             color = category, fill = category)) +
  geom_ribbon(aes(ymin = conf.low, ymax = conf.high),
              alpha = 0.18, color = NA) +
  geom_line(linewidth = 1.2) +
  geom_point(size = 2.6) +
  scale_y_continuous(labels = scales::percent, limits = c(0, NA)) +
  labs(x = "education (1 = HS, 2 = Some college, 3 = BA+)",
       y = "Pr(party-ID = k | X)")


# ============================================================================
# Section 14: Average marginal effects per category
# ============================================================================

ame_educ = avg_slopes(mod_mn, variables = "educ_num", type = "probs")
ame_educ

# Each row says: averaging across the sample, a one-step increase in
# education changes the probability of identifying with party k by this
# much. The three numbers sum to zero.


# ============================================================================
# Section 15: Testing IIA — Hausman-McFadden test
# ============================================================================
#
# IIA (Independence of Irrelevant Alternatives): the ratio Pr(k)/Pr(ℓ) depends
# only on β_k and β_ℓ, not on which other categories are in the model.
# Test: if IIA holds, dropping a category and refitting should give the SAME
# coefficients for the remaining contrasts.

# mlogit needs data in "long" format (one row per respondent × alternative)
gss_ml = mlogit.data(gss, choice = "partyid3", shape = "wide")

m_full = mlogit(partyid3 ~ 0 | educ_num + age + sex + race + religion4,
                data = gss_ml, reflevel = "Republican")

# Restricted model: drop Independents
m_red  = mlogit(partyid3 ~ 0 | educ_num + age + sex + race + religion4,
                data = gss_ml, reflevel = "Republican",
                alt.subset = c("Republican", "Democrat"))

hmftest(m_full, m_red)

# Small p-value → reject IIA → softmax is misspecified for this data.
# Large p-value → can't reject → softmax is a defensible fit.



# ============================================================================
# Bonus: simulate IIA failure
# ============================================================================
#
# Build a DGP where IIA is known to fail (correlated utilities between Dem
# and Ind), then run the Hausman test and confirm it rejects.

set.seed(213)
n_sim = 5000
X_sim = rnorm(n_sim)

# Correlated normal errors → softmax can't represent the shared structure
Sigma_sim = matrix(c(1.0, 0.8, 0.0,
                     0.8, 1.0, 0.0,
                     0.0, 0.0, 1.0), 3, 3)
e_sim = MASS::mvrnorm(n_sim, c(0, 0, 0), Sigma_sim)
U_sim = cbind(Dem = 1 * X_sim, Ind = 0 * X_sim, Rep = -1 * X_sim) + e_sim
y_sim = factor(c("Dem", "Ind", "Rep")[apply(U_sim, 1, which.max)],
               levels = c("Rep", "Dem", "Ind"))

sim    = data.frame(id = 1:n_sim, X = X_sim, partyid = y_sim)
sim_ml = mlogit.data(sim, choice = "partyid", shape = "wide")
m_sim_full = mlogit(partyid ~ 0 | X, data = sim_ml, reflevel = "Rep")
m_sim_red  = mlogit(partyid ~ 0 | X, data = sim_ml, reflevel = "Rep",
                    alt.subset = c("Rep", "Dem"))

hmftest(m_sim_full, m_sim_red)
# χ² is huge, p ≈ 0 → cleanly rejects IIA, as expected by construction


# ============================================================================
# Wrap-up
# ============================================================================
#
# Toolkit summary:
#   Continuous Y                       → lm()
#   Binary Y ∈ {0, 1}                  → glm(family = binomial)
#   Counts Y ∈ {0, 1, 2, ...}          → glm(family = poisson) / MASS::glm.nb()
#   Time to event T ≥ 0, censored      → survival::coxph()
#   Ordered Y ∈ {1, ..., J}            → MASS::polr()
#   Nominal Y ∈ {1, ..., K}            → nnet::multinom()
#
# Common engine in every case: MLE on a likelihood that depends on the
# outcome's structure. Different likelihoods → different models.
