From e397aa2c48ad596b85305aa0dec7b347c686ec35 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 16 Aug 2026 16:51:13 +0000 Subject: [PATCH 1/4] docs: add FIPC ADRs and correct bibliographic citations Record Kim (2006) as the implemented FIPC contract, contrast Stocking-Lord and Haebara as unimplemented alternatives, and replace the misattributed Kim & Kolen 2010 JEM record with Kang & Petersen (2012) and Kim & Kolen (2019). Co-authored-by: Seongho Bae --- ARCHITECTURE.md | 74 ++++++++++- CONTRIBUTING.md | 5 +- README.md | 48 +++++++ docs/adr/0000-template.md | 33 +++++ docs/adr/0001-fipc-linking-contract.md | 117 +++++++++++++++++ docs/adr/0002-mirt-mml-em-engine.md | 81 ++++++++++++ docs/adr/0003-ipd-dif-screening-delegation.md | 74 +++++++++++ docs/adr/README.md | 28 ++++ docs/fixed-parameter-item-calibration.md | 87 +++++++++++-- docs/papers/README.md | 120 +++++++++++++----- 10 files changed, 623 insertions(+), 44 deletions(-) create mode 100644 docs/adr/0000-template.md create mode 100644 docs/adr/0001-fipc-linking-contract.md create mode 100644 docs/adr/0002-mirt-mml-em-engine.md create mode 100644 docs/adr/0003-ipd-dif-screening-delegation.md create mode 100644 docs/adr/README.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3880f15c..cf858e15 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -19,6 +19,9 @@ metadata and CI are wired, and which parts are safe to evolve. - `.github/ISSUE_TEMPLATE/` - structured issue intake templates - `.github/CODEOWNERS` - code ownership map for reviews - `.github/dependabot.yml` - Automated Actions dependency updates +- `docs/adr/` - architecture decision records (FIPC contract, mirt engine) +- `docs/fixed-parameter-item-calibration.md` - Kim (2006) linking contract +- `docs/papers/README.md` - verified bibliographic sources and DOIs - `docs/coderabbit/review-commands.md` - CodeRabbit command quick reference - `docs/operations/maintenance-runbook.md` - recurring maintainer operations checklist - `README.md` - User/developer entrypoint @@ -44,6 +47,8 @@ R objects (data frame/matrix/model), and outputs are returned as an R list. - Apply fixed common-item constraints for test linking - Produce linked model and score/theta artifacts - Key dependency: `mirt` +- Method decision: FIPC (Kim, 2006), not Stocking–Lord (1983) or + Haebara (1980) transformation estimation; see `docs/adr/0001-fipc-linking-contract.md` ### 3.2 Package Metadata and API Surface @@ -100,15 +105,78 @@ package metadata, and CI workflow definitions in Git. - Evaluate migration path from historical `packrat/` to a modern lock workflow. -## 10. Project Identification +## 10. Bibliographic grounding + +`autoFIPC()` orchestrates FIPC (Kim, 2006): anchors keep old-form +values and the new form is calibrated onto that scale. That contract +is an alternative to separate calibration plus Stocking and Lord +(1983) or Haebara (1980) characteristic-curve linking, and to +concurrent calibration (Kolen & Brennan, 2014). This repository does +not implement those transformation estimators. + +Estimation lives in `mirt` MML-EM (Chalmers, 2012; Bock & Aitkin, +1981). Optional IPD screening calls `mirt::multipleGroup` and +`mirt::DIF`; it is not a published invariance claim (see +`docs/adr/0003-ipd-dif-screening-delegation.md`). Score-scale +interpretation is bounded by AERA, APA, and NCME (2014). + +A withdrawn cite attributed "Linking item parameters to a base scale" +to Kim and Kolen (2010) in JEM. That record is not kept. The title is +Kang and Petersen (2012). Kim and Kolen (2019) is a real later FIPC +application paper. + +Full APA 7th records and DOIs: `docs/papers/README.md`. Accepted +method ADRs: `docs/adr/`. + +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + + +Stocking, M. L., & Lord, F. M. (1983). Developing a common metric in +item response theory. *Applied Psychological Measurement, 7*(2), +201–210. + +Haebara, T. (1980). Equating logistic ability scales by a weighted +least squares method. *Japanese Psychological Research, 22*(3), +144–149. + +Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, and +linking: Methods and practices* (3rd ed.). Springer. + + +Kim, S., & Kolen, M. J. (2019). Application of IRT fixed parameter +calibration to multiple-group test data. *Applied Measurement in +Education, 32*(4), 310–324. + + +Kang, T., & Petersen, N. S. (2012). Linking item parameters to a base +scale. *Asia Pacific Education Review, 13*(2), 311–321. + + +Chalmers, R. P. (2012). mirt: A multidimensional item response theory +package for the R environment. *Journal of Statistical Software, +48*(6), 1–29. + +Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood +estimation of item parameters: Application of an EM algorithm. +*Psychometrika, 46*(4), 443–459. + + +American Educational Research Association, American Psychological +Association, & National Council on Measurement in Education. (2014). +*Standards for educational and psychological testing*. American +Educational Research Association. + +## 11. Project Identification - Project Name: aFIPC - Repository URL: `https://github.com/seonghobae/aFIPC` - Primary Contact: Seongho Bae -- Date of Last Update: 2026-02-15 +- Date of Last Update: 2026-08-16 -## 11. Glossary / Acronyms +## 12. Glossary / Acronyms - FIPC: Fixed Item Parameter Calibration - IPD: Item Parameter Drift - IRT: Item Response Theory +- MML-EM: Marginal Maximum Likelihood via the EM algorithm diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfc9dbbe..da361caf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,10 +8,13 @@ over feature velocity. ## Ground Rules 1. Avoid behavior changes in `R/aFIPC.R` unless backed by explicit regression - evidence and maintainer approval. + evidence and maintainer approval. 2. Prefer small, auditable pull requests. 3. Keep CI/security/docs healthy (`.github/workflows/`, `README.md`, `ARCHITECTURE.md`, `AGENTS.md`). +4. Methodological decisions (linking contract, estimation engine) are + recorded in `docs/adr/`. Cite verified sources from + `docs/papers/README.md`; do not invent bibliographic records. ## Development Setup diff --git a/README.md b/README.md index 7e5816f2..ae25ed00 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,58 @@ produce accurate fixed-item linking results. The current maintenance goal is to preserve numerical behavior while modernizing repository operations (documentation, CI, and dependency hygiene). +## Methodological sources + +`autoFIPC()` implements fixed item parameter calibration (FIPC): common +items keep their old-form parameter values while the new form is +calibrated onto that scale (Kim, 2006). That is a different design from +separate calibration plus a Stocking and Lord (1983) or Haebara (1980) +characteristic-curve transformation, and from concurrent calibration +(Kolen & Brennan, 2014). This package does not estimate Stocking–Lord +or Haebara linking constants. + +Estimation is delegated to `mirt` MML-EM (Chalmers, 2012; Bock & +Aitkin, 1981). Linked-score interpretation is bounded by AERA, APA, and +NCME (2014). Full APA records and DOIs are in +`docs/papers/README.md`; method decisions are in `docs/adr/`. + +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + + +Stocking, M. L., & Lord, F. M. (1983). Developing a common metric in +item response theory. *Applied Psychological Measurement, 7*(2), +201–210. + +Haebara, T. (1980). Equating logistic ability scales by a weighted +least squares method. *Japanese Psychological Research, 22*(3), +144–149. + +Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, and +linking: Methods and practices* (3rd ed.). Springer. + + +Chalmers, R. P. (2012). mirt: A multidimensional item response theory +package for the R environment. *Journal of Statistical Software, +48*(6), 1–29. + +Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood +estimation of item parameters: Application of an EM algorithm. +*Psychometrika, 46*(4), 443–459. + + +American Educational Research Association, American Psychological +Association, & National Council on Measurement in Education. (2014). +*Standards for educational and psychological testing*. American +Educational Research Association. + ## What this repository contains - `R/aFIPC.R`: core `autoFIPC()` implementation - `DESCRIPTION`, `NAMESPACE`, `man/`: package metadata and generated docs +- `docs/adr/`: architecture decision records for FIPC and estimation +- `docs/fixed-parameter-item-calibration.md`: linking-contract restatement +- `docs/papers/README.md`: verified source papers and DOIs - `packrat/`: historical dependency lock/vendor directory - `.github/workflows/`: CI/security automation diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md new file mode 100644 index 00000000..0a5bbe63 --- /dev/null +++ b/docs/adr/0000-template.md @@ -0,0 +1,33 @@ +# ADR-NNNN: Short decision title + +- Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNNN +- Date: YYYY-MM-DD +- Deciders: maintainers + +## Context + +What question is being decided, and which constraints apply? Cite verified +sources. Do not invent bibliographic records. + +## Decision + +State the choice as a contract the package will keep. + +## Alternatives considered + +What was rejected and why, with sources when the alternative is a published +method. + +## Consequences + +Positive and negative follow-through for maintainers and callers. + +## Claim boundary + +What this decision does and does not claim. Separate orchestration in this +package from estimation or methodology that lives elsewhere. + +## References + +Use APA 7th. Include a DOI or publisher URL when one exists. Leave no empty +`DOI:` placeholders. diff --git a/docs/adr/0001-fipc-linking-contract.md b/docs/adr/0001-fipc-linking-contract.md new file mode 100644 index 00000000..eaf8e75a --- /dev/null +++ b/docs/adr/0001-fipc-linking-contract.md @@ -0,0 +1,117 @@ +# ADR-0001: FIPC as the linking contract + +- Status: Accepted +- Date: 2026-08-16 +- Deciders: maintainers + +## Context + +`autoFIPC()` places a new IRT form onto an established old-form scale by +declaring common items and calibrating the new form while those anchors +keep their old-form parameter values. The scientific question is which +published linking family that workflow implements. + +Kim (2006) frames fixed item parameter calibration (FIPC): old +operational or anchor parameters are treated as known during new-form +calibration so the new form is estimated directly on the base scale. +Kolen and Brennan (2014) survey the broader equating and linking +toolkit, including separate calibration plus a characteristic-curve +transformation, concurrent calibration, and fixed-parameter approaches. +The *Standards for Educational and Psychological Testing* +(AERA, APA, & NCME, 2014) limit how linked scores may be interpreted. + +A withdrawn repository cite attributed "Linking item parameters to a +base scale" to Kim and Kolen (2010) in the *Journal of Educational +Measurement*. That record is not a real JEM article. The title belongs +to Kang and Petersen (2012). A real Kim and Kolen FIPC paper is their +2019 *Applied Measurement in Education* application to multiple-group +data. + +## Decision + +This package implements FIPC as specified by Kim (2006) and restated in +`docs/fixed-parameter-item-calibration.md`: + +1. For each eligible anchor pair, copy the old-form item parameter + vector onto the matching new-form item. +2. Hold those copied parameters fixed (`est := FALSE`) during the + linked calibration. +3. Estimate only non-anchor new-form parameters on the scale defined by + the fixed anchors. + +`autoFIPC()` orchestrates that contract. It does not estimate a +Stocking–Lord or Haebara transformation. Inspection of `R/aFIPC.R` +shows no characteristic-curve linking objective; the linked call is +`mirt::mirt(..., pars = NewScaleParms)` after the copy-and-fix step. + +## Alternatives considered + +- **Separate calibration + Stocking and Lord (1983).** Calibrate each + form freely, then find a linear transformation that matches test + characteristic curves. Canonical characteristic-curve equating; not + what `autoFIPC()` computes. +- **Separate calibration + Haebara (1980).** Calibrate each form + freely, then match item characteristic curves by weighted least + squares. Also a post-calibration transformation; not implemented + here. +- **Concurrent calibration.** Estimate both forms in one run with + shared parameters for common items. `autoFIPC()` instead calibrates + forms separately and then fixes anchors (Kim, 2006). +- **Kang and Petersen (2012).** Correct source for the title "Linking + item parameters to a base scale." Useful background on placing + parameters onto a base scale; not the FIPC contract this package + implements. +- **Kim and Kolen (2019).** Later FIPC application to multiple-group + test data. Supports FIPC as a published method family; does not + replace Kim (2006) as the contract implemented here. + +## Consequences + +- Maintainers must preserve the copy-and-fix invariant unless a + regression fixture and explicit maintainer intent say otherwise. +- Docs must contrast FIPC with Stocking–Lord and Haebara so readers do + not infer that `autoFIPC()` returns those transformation constants. +- Score-scale claims stay inside AERA/APA/NCME (2014) limits: linking + does not by itself justify interchangeable high-stakes + interpretations. + +## Claim boundary + +This package orchestrates FIPC. Estimation of item-response +probabilities, the MML-EM cycles, and scores lives in `mirt` (see +ADR-0002). Accepting FIPC here is not a claim that Stocking–Lord, +Haebara, or concurrent calibration are inferior; they are different +published designs. It is also not a claim that linked scores meet a +particular testing-program validity argument. + +## References + +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + + +Stocking, M. L., & Lord, F. M. (1983). Developing a common metric in +item response theory. *Applied Psychological Measurement, 7*(2), +201–210. + +Haebara, T. (1980). Equating logistic ability scales by a weighted +least squares method. *Japanese Psychological Research, 22*(3), +144–149. + +Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, and +linking: Methods and practices* (3rd ed.). Springer. + + +Kim, S., & Kolen, M. J. (2019). Application of IRT fixed parameter +calibration to multiple-group test data. *Applied Measurement in +Education, 32*(4), 310–324. + + +Kang, T., & Petersen, N. S. (2012). Linking item parameters to a base +scale. *Asia Pacific Education Review, 13*(2), 311–321. + + +American Educational Research Association, American Psychological +Association, & National Council on Measurement in Education. (2014). +*Standards for educational and psychological testing*. American +Educational Research Association. diff --git a/docs/adr/0002-mirt-mml-em-engine.md b/docs/adr/0002-mirt-mml-em-engine.md new file mode 100644 index 00000000..271cd5c0 --- /dev/null +++ b/docs/adr/0002-mirt-mml-em-engine.md @@ -0,0 +1,81 @@ +# ADR-0002: mirt MML-EM as the estimation engine + +- Status: Accepted +- Date: 2026-08-16 +- Deciders: maintainers + +## Context + +FIPC (ADR-0001) is a linking contract: which parameters are copied from +the old form and held fixed. Someone still has to estimate the free +item parameters and the ability distribution. This package is an R +orchestrator, not a new IRT estimator. + +Chalmers (2012) describes `mirt`, the package `DESCRIPTION` imports. +Bock and Aitkin (1981) give the marginal maximum likelihood EM +(MML-EM) algorithm that `mirt` implements when `method = "EM"`. +`autoFIPC()` uses that path when `tryEM` is true (the default) or when +the item type is nominal. + +## Decision + +Use `mirt` as the estimation engine and MML-EM as the default +calibration method: + +- Separate old-form and new-form fits call `mirt::mirt`. +- The linked fit calls `mirt::mirt` with `pars` after the FIPC + copy-and-fix step. +- Default linked estimation uses `method = "EM"` (Bock & Aitkin, + 1981, as implemented by Chalmers, 2012). +- Scores and expected-score artifacts use `mirt` helpers such as + `fscores` and `expected.test`. + +This package does not reimplement the likelihood, quadrature, or EM +cycles. + +## Alternatives considered + +- **A custom MML-EM implementation in `R/aFIPC.R`.** Would duplicate + a maintained estimator and risk silent numerical drift. Rejected. +- **A different IRT package.** Historical outputs were produced with + `mirt`. Changing engines would be a scientific behavior change, not + a docs fix. +- **`mirt` MHRM (`method = "MHRM"`).** `autoFIPC()` can take this + path when `tryEM` is false and the item type is not nominal. It is + an optional `mirt` method, not the default FIPC engine documented + here. + +## Consequences + +- Numerical changes in `mirt` can change `autoFIPC()` output even when + this repository's R sources are untouched. +- Formula-integrity reviews (see + `docs/fixed-parameter-item-calibration.md`) apply to orchestration + only. Estimation mathematics stay in `mirt`. +- `man/autoFIPC.Rd` remains roxygen-generated from `R/aFIPC.R`. + Method citations belong in these markdown ADRs and + `docs/papers/README.md` unless the roxygen `@references` block is + updated in the same change. + +## Claim boundary + +Choosing `mirt` and MML-EM is an engineering dependency decision. It +is not a claim that this package contributes a new estimation +algorithm, and it is not a claim about the relative accuracy of EM +versus other `mirt` methods. Linking-scale interpretation remains +bounded by ADR-0001 and AERA/APA/NCME (2014). + +## References + +Chalmers, R. P. (2012). mirt: A multidimensional item response theory +package for the R environment. *Journal of Statistical Software, +48*(6), 1–29. + +Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood +estimation of item parameters: Application of an EM algorithm. +*Psychometrika, 46*(4), 443–459. + + +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + diff --git a/docs/adr/0003-ipd-dif-screening-delegation.md b/docs/adr/0003-ipd-dif-screening-delegation.md new file mode 100644 index 00000000..2d905944 --- /dev/null +++ b/docs/adr/0003-ipd-dif-screening-delegation.md @@ -0,0 +1,74 @@ +# ADR-0003: IPD/DIF screening is delegated to mirt + +- Status: Accepted +- Date: 2026-08-16 +- Deciders: maintainers + +## Context + +`autoFIPC()` can optionally screen common items for item parameter +drift (IPD) before the FIPC copy-and-fix step (`checkIPD`, default +true). The implementation builds a two-group response matrix and calls +`mirt::multipleGroup` plus `mirt::DIF`. Items flagged by that screen +may be dropped from the anchor set. + +That workflow is an operational convenience around `mirt`. It is not +itself a published invariance, DIF, or IPD methodology paper, and it +must not be documented as one. + +## Decision + +Treat IPD/DIF screening as delegated `mirt` machinery: + +- When `checkIPD` is true, screening uses `mirt::multipleGroup` and + `mirt::DIF` on the declared common items. +- Items retained after the screen become the anchors for the Kim + (2006) FIPC contract (ADR-0001). +- Documentation may describe the calls and the effect on the anchor + list. It must not present `autoFIPC()` as a new DIF/IPD statistic + or as evidence that anchors are invariant in a testing-program + sense. + +## Alternatives considered + +- **No IPD screen.** Callers can set `checkIPD = FALSE` and supply + anchors they have already reviewed. +- **A package-local DIF/IPD statistic.** Would be a new methodological + claim and a behavior change. Out of scope for documentation work + and not present in `R/aFIPC.R`. +- **Citing a security standard (NIST, OWASP) for this control.** + Those sources apply to security ADRs. IPD screening is a + psychometric operations step, not a security control. + +## Consequences + +- IPD results inherit `mirt` defaults, version behavior, and the + arguments `autoFIPC()` passes through. Changes in `mirt` can change + which anchors survive. +- Reviewers should not treat a clean IPD screen as a published + invariance argument (AERA, APA, & NCME, 2014). +- Tests that pin FIPC (anchors fixed to old-form values) are separate + from any claim about the DIF screen's Type I error or power. + +## Claim boundary + +This ADR records delegation. It does not claim that the `mirt` DIF +screen equals a named published IPD procedure, that surviving anchors +are drift-free, or that linked scores are interchangeable. The linking +contract remains FIPC (ADR-0001); estimation remains `mirt` MML-EM +(ADR-0002). + +## References + +Chalmers, R. P. (2012). mirt: A multidimensional item response theory +package for the R environment. *Journal of Statistical Software, +48*(6), 1–29. + +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + + +American Educational Research Association, American Psychological +Association, & National Council on Measurement in Education. (2014). +*Standards for educational and psychological testing*. American +Educational Research Association. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..be452207 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,28 @@ +# Architecture decision records + +This folder records methodological and estimation decisions for `aFIPC`. +Each ADR states a contract, the alternatives considered, and a claim +boundary so maintainers do not treat orchestration in this package as a +new psychometric method. + +Use `0000-template.md` for new records. Status values are Proposed, +Accepted, Deprecated, or Superseded. Do not invent bibliographic records; +cite verified sources only. + +These ADRs are documentation. They do not change `autoFIPC()` numerical +behavior. + +## Index + +| ID | Title | Status | +| --- | --- | --- | +| [ADR-0001](0001-fipc-linking-contract.md) | FIPC as the linking contract | Accepted | +| [ADR-0002](0002-mirt-mml-em-engine.md) | mirt MML-EM as the estimation engine | Accepted | +| [ADR-0003](0003-ipd-dif-screening-delegation.md) | IPD/DIF screening is delegated to mirt | Accepted | + +## Related documents + +- Linking contract restatement: + [`docs/fixed-parameter-item-calibration.md`](../fixed-parameter-item-calibration.md) +- Source-paper list with DOIs: [`docs/papers/README.md`](../papers/README.md) +- Repository map: [`ARCHITECTURE.md`](../../ARCHITECTURE.md) diff --git a/docs/fixed-parameter-item-calibration.md b/docs/fixed-parameter-item-calibration.md index efad6448..500488c5 100644 --- a/docs/fixed-parameter-item-calibration.md +++ b/docs/fixed-parameter-item-calibration.md @@ -9,7 +9,15 @@ should move onto that base scale. This follows the fixed parameter calibration framing in Kim (2006): old operational or anchor item parameters are treated as known values during the new-form calibration so the new form is calibrated directly on the established -scale. The package test `test-fixed-parameter-calibration.R` reproduces this +scale. FIPC is one published linking design among others. Separate +calibration plus a Stocking and Lord (1983) or Haebara (1980) +characteristic-curve transformation, and concurrent calibration of both +forms, are alternatives surveyed by Kolen and Brennan (2014). +`autoFIPC()` implements FIPC only: it copies old-form anchor values, +holds them fixed, and re-estimates free new-form parameters in `mirt`. +It does not estimate a Stocking–Lord or Haebara linking transformation. + +The package test `test-fixed-parameter-calibration.R` reproduces this contract with generated 2PL data: 1. Generate old-form and new-form responses from known true item parameters. @@ -70,12 +78,75 @@ pinned to hand-computed reference values in contract (anchors fixed to old-form values, non-anchors left free) is pinned in `tests/testthat/test-fixed-parameter-calibration.R`. +## Relation to other linking methods + +Kolen and Brennan (2014) organize common IRT linking designs as: + +- **Separate calibration + characteristic-curve transformation.** + Each form is calibrated freely. A linear transformation is then + chosen to match test characteristic curves (Stocking & Lord, 1983) + or item characteristic curves (Haebara, 1980). +- **Concurrent calibration.** Both forms are estimated in one run with + shared parameters for common items. +- **Fixed item parameter calibration (FIPC).** Anchor parameters from + the old form are treated as known and held fixed while the new form + is calibrated onto that scale (Kim, 2006; see also Kim & Kolen, + 2019, for a later multiple-group FIPC application). + +`R/aFIPC.R` implements the third design. There is no Stocking–Lord or +Haebara objective, and no post-calibration slope/intercept estimator. +A previous draft cited a non-existent Kim and Kolen (2010) *Journal of +Educational Measurement* article titled "Linking item parameters to a +base scale." That record is withdrawn. The title belongs to Kang and +Petersen (2012). + +Linked scores still fall under the interpretation limits in the +*Standards for Educational and Psychological Testing* (AERA, APA, & +NCME, 2014). Estimation of free parameters uses `mirt` MML-EM +(Chalmers, 2012; Bock & Aitkin, 1981). See `docs/adr/` for the +accepted method decisions. + ## References -- Kim, S. (2006). A comparative study of IRT fixed parameter calibration - methods. Journal of Educational Measurement, 43(4), 355-381. -- Chalmers, R. P. `mirt::fixedCalib` documentation. The implementation note - describes fixed-item calibration methods based on Kim (2006) and points to - `multipleGroup` for more flexible anchor-item calibration. -- Kim, S., & Kolen, M. J. (2010). Linking item parameters to a base scale. - Journal of Educational Measurement, 47(2), 164-181. +Kim, S. (2006). A comparative study of IRT fixed parameter calibration +methods. *Journal of Educational Measurement, 43*(4), 355–381. + + +Stocking, M. L., & Lord, F. M. (1983). Developing a common metric in +item response theory. *Applied Psychological Measurement, 7*(2), +201–210. + +Haebara, T. (1980). Equating logistic ability scales by a weighted +least squares method. *Japanese Psychological Research, 22*(3), +144–149. + +Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, and +linking: Methods and practices* (3rd ed.). Springer. + + +Kim, S., & Kolen, M. J. (2019). Application of IRT fixed parameter +calibration to multiple-group test data. *Applied Measurement in +Education, 32*(4), 310–324. + + +Kang, T., & Petersen, N. S. (2012). Linking item parameters to a base +scale. *Asia Pacific Education Review, 13*(2), 311–321. + + +Chalmers, R. P. (2012). mirt: A multidimensional item response theory +package for the R environment. *Journal of Statistical Software, +48*(6), 1–29. + +Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood +estimation of item parameters: Application of an EM algorithm. +*Psychometrika, 46*(4), 443–459. + + +American Educational Research Association, American Psychological +Association, & National Council on Measurement in Education. (2014). +*Standards for educational and psychological testing*. American +Educational Research Association. + +Chalmers, R. P. `mirt::fixedCalib` documentation. The implementation +note describes fixed-item calibration methods based on Kim (2006) and +points to `multipleGroup` for more flexible anchor-item calibration. diff --git a/docs/papers/README.md b/docs/papers/README.md index 75b62728..5f2553ad 100644 --- a/docs/papers/README.md +++ b/docs/papers/README.md @@ -1,46 +1,102 @@ # Source papers for the calibration and linking mathematics -`autoFIPC()` implements the fixed item parameter calibration (FIPC) linking -contract; the underlying IRT estimation is delegated to `mirt`. The canonical -equations this package must match are documented in the sources below. +`autoFIPC()` implements the fixed item parameter calibration (FIPC) +linking contract; the underlying IRT estimation is delegated to `mirt`. +The canonical sources this package must match are listed below. -No PDFs are committed here: the two primary FIPC references (Kim, 2006; Kim & -Kolen, 2010) are published in the *Journal of Educational Measurement* and are -not open access, so they are cited by DOI rather than redistributed, to respect -copyright. The `mirt` reference is open access. +No PDFs are committed here. Copyrighted articles are cited by DOI +rather than redistributed. The `mirt` reference is open access. + +A previous draft listed Kim and Kolen (2010), "Linking item parameters +to a base scale," *Journal of Educational Measurement, 47*(2), +164–181. That bibliographic record is not a real JEM article and is +not kept. The title belongs to Kang and Petersen (2012). A real Kim +and Kolen FIPC paper is Kim and Kolen (2019). ## Primary source — the FIPC linking contract -- **Kim, S. (2006). A comparative study of IRT fixed parameter calibration - methods.** *Journal of Educational Measurement, 43*(4), 355-381. +- **Kim, S. (2006). A comparative study of IRT fixed parameter + calibration methods.** *Journal of Educational Measurement, 43*(4), + 355–381. DOI: - - Canonical rule implemented: old-form (anchor) item parameters are treated as - known and held fixed while the new form is calibrated directly onto the - established base scale. + - Canonical rule implemented: old-form (anchor) item parameters are + treated as known and held fixed while the new form is calibrated + directly onto the established base scale. + +- **Kim, S., & Kolen, M. J. (2019). Application of IRT fixed parameter + calibration to multiple-group test data.** *Applied Measurement in + Education, 32*(4), 310–324. + DOI: + - Later FIPC application to multiple-group data. Supports FIPC as a + published method family; does not replace Kim (2006) as the + contract `autoFIPC()` implements. + +## Characteristic-curve equating (not implemented here) + +`autoFIPC()` implements FIPC, not a Stocking–Lord or Haebara +transformation estimator. These papers are the canonical +characteristic-curve methods that FIPC is an alternative to (separate +calibration plus a linking transformation, versus concurrent +calibration, versus FIPC). + +- **Stocking, M. L., & Lord, F. M. (1983). Developing a common metric + in item response theory.** *Applied Psychological Measurement, + 7*(2), 201–210. + DOI: + - Test characteristic-curve linking after separate calibration. -- **Kim, S., & Kolen, M. J. (2010). Linking item parameters to a base scale.** - *Journal of Educational Measurement, 47*(2), 164-181. - DOI: - - Basis for treating the old-form scale as the fixed base onto which new-form - parameters are placed. +- **Haebara, T. (1980). Equating logistic ability scales by a weighted + least squares method.** *Japanese Psychological Research, 22*(3), + 144–149. + DOI: + - Item characteristic-curve linking by weighted least squares after + separate calibration. + +## Equating and linking handbook + +- **Kolen, M. J., & Brennan, R. L. (2014). *Test equating, scaling, + and linking: Methods and practices* (3rd ed.).** Springer. + DOI: + - Handbook survey of equating, scaling, and linking designs, + including the families contrasted above. + +## Correct source for the withdrawn title + +- **Kang, T., & Petersen, N. S. (2012). Linking item parameters to a + base scale.** *Asia Pacific Education Review, 13*(2), 311–321. + DOI: + - Real paper with this title (also circulated as ACT Research Report + 2009-2). Not the FIPC contract implemented here. ## Estimation engine (open access) -- **Chalmers, R. P. (2012). mirt: A Multidimensional Item Response Theory - Package for the R Environment.** *Journal of Statistical Software, 48*(6), - 1-29. DOI: (open access) - - Provides the MML-EM estimation, `fscores` (MAP), `expected.test`, and the - `multipleGroup`/`DIF` machinery used for item parameter drift screening. - - `?mirt::fixedCalib` documents fixed-item calibration methods based on - Kim (2006). +- **Chalmers, R. P. (2012). mirt: A multidimensional item response + theory package for the R environment.** *Journal of Statistical + Software, 48*(6), 1–29. + DOI: (open access) + - Provides the MML-EM estimation, `fscores` (MAP), `expected.test`, + and the `multipleGroup`/`DIF` machinery used for item parameter + drift screening. + - `?mirt::fixedCalib` documents fixed-item calibration methods based + on Kim (2006). + +- **Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood + estimation of item parameters: Application of an EM algorithm.** + *Psychometrika, 46*(4), 443–459. + DOI: + - The MML-EM algorithm underlying `mirt`'s `method = "EM"` + estimation. -## Supporting reference +## Score-scale interpretation limits -- **Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood estimation of - item parameters: Application of an EM algorithm.** *Psychometrika, 46*(4), - 443-459. DOI: - - The MML-EM algorithm underlying `mirt`'s `method = "EM"` estimation. +- **American Educational Research Association, American Psychological + Association, & National Council on Measurement in Education. + (2014). *Standards for educational and psychological testing*.** + American Educational Research Association. + - Limits on how linked scores and scales may be interpreted. No DOI + is used here; none was verified for this edition. -See `../fixed-parameter-item-calibration.md` for the equation restatement, the -formula-integrity audit of the performance refactors, and the tests that pin -these formulas to reference values. +See `../fixed-parameter-item-calibration.md` for the equation +restatement, the formula-integrity audit of the performance refactors, +and the tests that pin these formulas to reference values. Method +decisions are recorded in `../adr/`. From 7451510b79801a25dd2b747f22ed49f77a813bc3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 17 Aug 2026 15:54:28 +0000 Subject: [PATCH 2/4] docs: point agent guides at ADRs and verified citations Link AGENTS.md and CLAUDE.md to docs/adr/ and docs/papers/README.md so the FIPC contract, mirt engine boundary, and withdrawn 2010 JEM record stay discoverable to agents. Co-authored-by: Seongho Bae --- AGENTS.md | 12 ++++++++++++ CLAUDE.md | 7 +++++-- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b60b03df..ff8bd391 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,4 +106,16 @@ Applies to every agent (Claude, Codex, Cursor, opencode, ...) working in this re - For substantive calibration/linking changes, cite the relevant IRT and psychometrics literature. Commit paper PDFs only when redistribution is permitted; otherwise cite, link, and summarize. +- Method decisions are recorded in `docs/adr/`. Verified APA 7th records + and DOIs are in `docs/papers/README.md`. Do not invent bibliographic + records or leave empty `DOI:` placeholders. +- The implemented linking contract is FIPC (Kim, 2006): anchors keep + old-form values. `autoFIPC()` does not estimate a Stocking–Lord (1983) + or Haebara (1980) transformation (ADR-0001). Estimation is `mirt` + MML-EM (ADR-0002). IPD/DIF screening is delegated to `mirt` and is + not a published invariance claim (ADR-0003). +- Do not restore Kim and Kolen (2010), "Linking item parameters to a + base scale," *Journal of Educational Measurement*. That record is not + a real JEM article. The title is Kang and Petersen (2012). A real + Kim and Kolen FIPC paper is Kim and Kolen (2019). diff --git a/CLAUDE.md b/CLAUDE.md index 264efb15..23119f0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,8 +86,9 @@ score/theta outputs, returned as an R list. The linking contract (Kim, 2006): anchor items keep their old-form parameter values fixed during new-form calibration so the new form is calibrated -directly onto the established scale. It is documented in -`docs/fixed-parameter-item-calibration.md` and enforced by +directly onto the established scale. That is FIPC, not a Stocking–Lord or +Haebara transformation. It is documented in +`docs/fixed-parameter-item-calibration.md` and `docs/adr/`, and enforced by `tests/testthat/test-fixed-parameter-calibration.R`. ## Key conventions @@ -123,3 +124,5 @@ Summarized from `AGENTS.md` and `CONTRIBUTING.md`; read those for detail. - `CONTRIBUTING.md` — contribution process and verification baseline - `docs/operations/maintenance-runbook.md` — recurring maintainer operations - `docs/fixed-parameter-item-calibration.md` — calibration/linking basis +- `docs/adr/` — FIPC, mirt MML-EM, and IPD/DIF decision records +- `docs/papers/README.md` — verified source papers and DOIs From 2ea4d91c182ad6f90e4ac6d04639d1e3914bd92b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 17 Aug 2026 17:23:46 +0000 Subject: [PATCH 3/4] ci: retrigger Strix and Noema after GitHub API flake Org required workflows failed before scanning this PR: Strix could not resolve repo visibility because installation 141441800 hit the GitHub API rate limit (HTTP 403), and Noema died on a GraphQL 503. No package or citation change. Co-authored-by: Seongho Bae From 7b711e73aad8de5aa492a6d6866b10b8849d1c8d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 18 Aug 2026 00:23:28 +0000 Subject: [PATCH 4/4] ci: retrigger Noema now that GitHub.com is operational Required noema-review still shows the HTTP 503 from the earlier GitHub.com outage (gh api graphql). Package checks already passed. Empty commit retriggers the org required review after status returned to All Systems Operational. Co-authored-by: Seongho Bae