# interSAE

`interSAE` implements joint margin-constrained intersectional small area
estimation from complex-survey microdata and aggregate census margins.

The motivating problem is common in official statistics: a survey observes an
outcome and several demographic variables, while published census tables give
precise but overlapping margins rather than a full confidential microdata file.
Direct survey estimates become unstable or unavailable after crossing a small
geographic area with age, sex, residence, or another subgroup.

## What the package does

1. Validates survey weights, strata, primary sampling units, and optional
   replicate weights.
2. Validates overlapping census tables and structural-zero declarations.
3. Reconstructs a coherent latent joint population table with generalized
   iterative proportional fitting.
4. Fits a survey-weighted Gaussian or binomial outcome model.
5. Produces augmented, model-assisted means, proportions, and totals.
6. Diagnoses the rank and nullity of the margin system.
7. Optionally computes linear-programming identification bounds and gamma
   sensitivity envelopes.
8. Refits the entire procedure under multiplier or supplied replicate weights.
9. Benchmarks domain estimates to an official aggregate.

## Installation

```r
install.packages("interSAE_0.1.0.tar.gz", repos = NULL, type = "source")
```

The core package uses only R recommended packages. Install `lpSolve` to compute
identification bounds.

## Minimal example

```r
library(interSAE)

x <- inter_example()

design <- inter_design(
  x$survey,
  weights = "weight",
  area = "area",
  strata = "strata",
  psu = "psu"
)

margins <- census_margins(x$margins)

fit <- fit_inter_sae(
  unemployed ~ sex + age + residence + area,
  design = design,
  margins = margins,
  family = "binomial",
  domain = c("area", "sex")
)

inter_estimates(fit)
margin_diagnostics(fit)
check_identifiability(fit)
```

Optional sensitivity analysis:

```r
if (requireNamespace("lpSolve", quietly = TRUE)) {
  inter_sensitivity(
    fit,
    gamma = c(1, 1.25, 1.5, 2, Inf),
    domain = list(area = "A1", sex = "Female")
  )
}
```

## Interpretation

The fitted point estimate depends on the outcome model and on a coherent
population reconstruction seeded by the weighted survey association structure.
When aggregate margins do not identify the full joint table, the package says
so explicitly. Identification bounds vary the latent joint table while holding
published census margins fixed. Bootstrap intervals and identification bounds
answer different questions and should be reported separately.

## Scope of version 0.1.0

This release is a research implementation for categorical census dimensions
and Gaussian or binary survey outcomes. It does not claim that aggregate
margins alone identify a confidential joint population distribution. Applied
work should document the outcome formula, structural zeros, sensitivity values,
survey design, and benchmarking decisions.
