[GidonFrischkorn]

Part of #255.

Base branch: 255-mpt-design (stack rebased on develop 6f04c69, 2026-10-04; design 07494c7 merged in, which carries PRs 1 to 3 and develop 186250e; develop 222a7ef merged in 2026-10-08; head edba61b, 2026-10-09). PR 4 of 6 in the MPT stack. 7 files, +2818/-0.

What this adds

mpt_from_string() reads MPTinR-style model text. Each line is one branch, blank lines separate trees, and the category comes from an inline # category comment or from categories. The categories argument can be a list by tree for models where trees use different response labels, or one shared character vector for trees that share labels. Comments (lines starting with #) are skipped without separating trees; only blank lines separate trees.

mpt_from_eqn() reads EQN files (multiTree, MPTinR, TreeBUGS). Lines that end in the same category are summed. The tree_names argument maps file tree labels to bmm tree names, e.g. c("1" = "old", "2" = "new"). The first line of an EQN file is read as an equation count if it is a lone integer; otherwise it is parsed as an equation like any other line.

Both functions take impossible, a named list of response categories that cannot occur in certain trees, e.g. list(tree1 = c("a", "b")).

Both pass tree_id, covariates, simplex, restrictions and links on to mpt().

User-visible changes and error messages

• Both importers error when impossible or categories names are unknown to the model (not in the trees or categories after import).
• mpt_from_eqn(): prefix-collision error when the <tree>_ prefix strip creates duplicate category names (B1).
• mpt_from_eqn(): merge message when the categories argument maps multiple categories of a tree onto one (Q1).
• mpt_from_eqn(): restrictions are checked to use only names from the file, before renaming.
• mpt_from_string(): now handles readLines() output correctly, preserving blank lines that separate trees.
• mpt_renaming attribute is a data frame with columns kind (parameter/tree/category), tree (NA for parameters), file_name, bmm_name, and a new renamed column (TRUE if a name changed). The import message prints only rows where a name changed. Tree rows track the tree-label mapping.
• mpt_from_eqn(): error when covariates are symbols that are not in the EQN file.
• mpt_from_eqn(): error when a category name does not start with a letter (points to the categories argument).
• mpt_from_eqn() help page: states that bmm reads the first line unless it is the equation count, so users should delete a title line or start it with # for TreeBUGS/MPTinR files.
• Migration documentation in the Rd pages shows how to reshape data from MPTinR/TreeBUGS formats.

Design decisions

File format and line skipping (decision 1). The first line of an EQN file is skipped only if it is a single integer. When skipped, the count is compared with the number of equation lines that follow and a warning is emitted on a mismatch. A first line that is not a lone integer is parsed as an equation. A line with fewer than three fields anywhere is an error naming the line number and its text.

Categories argument as list by tree (mpt_from_string). The categories argument can be either a character vector shared by all trees, or a list with one vector per tree. In either form, entries are matched to lines by position. A shared vector suits trees that use the same responses in the same order; a list suits trees with different response sets.

Impossible categories (decision 2). The impossible argument takes a named list of categories that cannot occur in each tree, using the category names after mapping/sanitizing. Unknown tree names or categories error by naming the trees or categories that are not in the model.

Tree name mapping (reviewer default Q5). The tree_names argument maps file tree labels to bmm names, e.g. c("1" = "old", "2" = "new"). bmm tree names must start with a letter and contain only letters, digits, or underscores. Unmapped labels keep their name; unknown keys error.

Category prefix strip and name sanitization (reviewer default Q9; existing design). Categories in EQN files often carry a <tree>_ prefix to distinguish trees (e.g. old_hit, new_fa). The prefix is stripped if the category is not mapped by the categories argument. All remaining underscores and dots are then stripped (brms does not allow them in non-linear parameter names). Names that would clash after this are errors. Restrictions are written with the file's own names and are renamed together with the parameters.

Renaming map (reviewer default Q10). The mpt_renaming attribute is a data frame with columns kind (parameter/tree/category), tree (NA for parameters), file_name, bmm_name, and renamed (TRUE if the name changed). It holds one row per parameter, tree label and category. The import message prints only the rows where a name changed, in a compact multi-line table with one line per parameter rename and categories grouped per tree.

Provenance (reviewer default Q6). mpt_from_eqn() stores attr(model, "mpt_source") <- list(file = normalizePath(file), md5 = unname(tools::md5sum(file)), lines = raw_lines). mpt_from_string() stores list(text = text_as_one_string).

Comments in mpt_from_string (decision 4). A line whose first non-blank character is # is a comment and is skipped (not a tree separator; only blank lines separate trees). An inline expression # category comment labels that line. This differs from MPTinR, where everything after # is ignored and # lines count as blank.

Validation

The Al Hadhrami, Bartsch & Oberauer (2025) binding-model validation ran on 2 October from the published EQN files and still needs a rerun on this head. The imported model objects (unitization and hybrid) are identical to that import. The validation checked 3 trees, 10 categories, 12 and 18 free parameters, probit, (1 |p| id).

The identifiability check of PR 1 on these imports, at this head: unrestricted, Jacobian rank 19 of 21 (unitization) and 21 of 27 (hybrid), which the parameter count does not catch; with the design constants, 12 of 12 and 18 of 18.

Test coverage

The #487 review round: 120 tests, 487 expectations in the import tests, 0 failed. Its code verifier found no silent wrong model in about 160 adversarial inputs and killed 79 of 79 mutants. Tests cover model construction, file format errors, category mapping, the merge message (Q1), the renaming map with its renamed column and tree rows, impossible categories, tree names, the prefix-collision error (B1), restrictions in file names, unknown and invalid category names, the covariate-symbol check, readLines() input and the header advice. One test added at the merge-up (d1dc7d2): the identifiability check counts only the categories a tree can produce. The re-review round took the import file from 37 tests / 110 expectations to 41 / 128; the 120 / 487 figures above are the whole mpt filter, not this file.

Changes since the re-review of 2026-10-09 (e579ffb)

An internal review (2026-10-09) gave the verdict MERGE AFTER FIXES. One silent wrong model and four narrower gaps, fixed in one round plus a nit round, checked by three independent reviewers:

• A category label that is only its tree prefix is refused instead of silently shifting or merging categories. old_ as a label in tree old left an empty name after the prefix strip, which the renaming map then dropped; the import went through with the wrong categories. This was the one silent-wrong-model finding.
• Map arguments are validated as maps. A categories or tree_names value that is a factor, NA or the empty string, a duplicated tree_names entry in mpt_from_string(), and a tree named twice in impossible each get their own message instead of a raw nzchar() error (98aaaac). mpt_from_eqn() now refuses a list of length-1 values for categories — a behaviour change against a6a55ae, and the only one.
• Sanitizing problems are reported together, with the remedy that fits parameters or categories, and a parameter that sanitizes to an empty name is named (cdec70d). A sanitized parameter that clashes with a covariate is distinguished from one that clashes with another parameter.
• The title hint leads for a header such as 6 # count and is not shown for a one-line first tree whose expression is 1; the merge message in mpt_from_string() matches mpt_from_eqn()'s (e9851ad, b4a444a).
• Docs: mapped category values are sanitized too, and the first-line note on MPTinR/TreeBUGS is exact.

Verification: every one of the 13 reference imports identical to a6a55ae apart from the intended refusals, MPTinR parameter sets equal (21 and 27), author mutants 79 of 79 killed, check() 0/0/0 before and after. The committed tree's diff hash matched the independent reviewer's.

Since 2026-10-08 (develop sync 2, open items)

• The sanitizing message names the clashing spellings as the file writes them: D_o and D.o gave "produces duplicated names: 'Do'", a name that appears nowhere in the file; now "'D_o', 'D.o' become 'Do'" (98061b2). The two pinned tests fail on the old code and pass on the new.
• Reviewer C's other two message items need no change. impossible = c(s = "E1") no longer ends in "Every entry needs a name." (only an unnamed list does). A title whose third word is exactly 1 (Model v 1) loses the title hint by design, because catch c1 1 is a valid one-line tree; Model v 1 test keeps the hint.
• The 13 reference imports are identical to bb4b584 in every field.

Gates on 255-mpt-import (edba61b)

• Focus tests, filter mpt|distributions|conditional|pp_check|update|data_check|helpers-prior|default-priors: 0 failed, 0 errors, 0 skipped, 2503 passed.
• check() on an rsync copy: Status OK, 0 errors, 0 warnings, 0 notes.
• Stancode of 2HTM, PCM and OL2019 identical, and print() of the seven reference models identical except the parameter_info() line of e7c8504, against bb4b584.
• document(): no drift. git merge-tree against develop 222a7ef: clean.

Update 2026-10-13: develop through #546 carried up, MPT fits in tests/local (head b1fc508)

This update replaces the "Gates" section above, if any.

• The design level is merged in twice (develop as of fix(update): leave brms's own default priors out of the carried-over prior #539 on 2026-10-12, as of test: tier the suite, four workers and a time budget (ADR 0004) #546 on 2026-10-13); with it the MPT fits of the lower levels moved to tests/local. Nothing else changed in this level's own files.

Measured at this head: document() no drift. The full suite and R CMD check were run at the tip of the stack (#489).

CI on this head: R-CMD-check passes on macOS, Ubuntu and Windows (Windows check step 9 minutes), tests-source passes within the time budget (suite 570 s), and file-size passes.

[GidonFrischkorn]

Update 2026-10-12: design merged (head eaf48c1)

No change to the importers at this level since the last update. The level carries the current design (#486) forward: the two review fixes of the range check, the TreeBUGS recipe fix, the update() prior fix and the merged develop (#530). The merge was clean. Measured at this head: parse of every R file and document() without drift. The importer-level review items that remained after the 7 Oct re-review are in the 1.5.0 follow-up list.