Skip to content

masque 0.17.0: controls, plan and handover - #2

Open
max578 wants to merge 16 commits into
mainfrom
feat/0.17.0
Open

max578 wants to merge 16 commits into
mainfrom
feat/0.17.0

Conversation

@max578

@max578 max578 commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

Takes masque to 0.17.0. This PR is here to run CI on every platform before the version is frozen for a study; merging waits for CRAN's answer on 0.16.0.

Controls. control_spec(), controls() and control_table() derive null, negative and positive datasets by permutation, from a clone and, with a private seed, from the original.

Plan and handover. masque_plan() holds the roles and named specs. mask(df, plan) resolves each control spec on the source and writes it back to the recipe. clone_plan() gives the same plan in the clone's names and labels. handover() writes the clone, that plan, the data card and a note to one folder, after the release gate. controls(real, plan, recipe = rec) runs the spec on the owner's side from a private key.

Conditioning. mask(conditional = "design") keeps design means and carries no treatment effect. Column names give an explicit partition.

Behaviour changes.

  • A site's displacement is keyed on its value and the seed, so one seed gives one displacement after rows are shuffled, added or removed. An existing clone moves under the new draw, so a rebuild is a new release of its sites.
  • Under the hierarchy ladder a design level needs three rows to carry a shift. A two-row level gave a clone correlated 0.99 with the original at its rows, and the audit read low.
  • The audit now grades a number that tracks the original on its own row, so some conditional clones grade higher than before.
  • With a plan and its recipe, the owner's permutations come from SHA-256 of a 256-bit system key, because a derived integer seed could be searched against a per-replicate statistic.
  • apply_recipe() and controls() with a recipe refuse a table whose values differ from those the recipe was built on.
  • The plan's default control unit passes over a column with too few units for a 5 percent level, and warns when several qualify.

Local checks at 901852f, macOS arm64: suite 3824 expectations, 0 failed. With the Suggests masked, 3339, 0 failed. R CMD check also passes on R 4.5.2, where the first CI run found the value fingerprint hashing how text was held in memory. R CMD check --as-cran on the tarball: 0 errors, 0 warnings, 1 NOTE from the sandbox's OpenMP startup message. The pkgdown site was not built, because the favicon service is blocked in the sandbox.

max578 added 13 commits November 5, 2026 17:36
A control spec declares what a control removes and plants: the column
to permute (default the single treatment), the design strata and unit of
the restricted permutation, the unit-grained columns, the numeric targets
and the per-level shift in target-SD units, the replicate count and the
seed. controls() resolves it against any table with a role table and
control_table() regenerates the null, a negative replicate or a positive
replicate from its seed. Nothing is re-simulated.

The null permutes every analysed column at its grain; the negative
permutes the declared column within the strata at its unit; the positive
is the same permutation plus the shift, so positive minus negative is the
planted truth exactly. A whole-valued target takes a per-level whole
shift and a shift that rounds away is refused. The planted vector comes
from the spec's seed; a private run seed, for the owner's side, changes
the permutations only.

Refusals by class for a degenerate permutation, strata not nested above
the unit, a target of the wrong kind or grain, an event column as target
and a missing seed; both guards were falsified. 314 new expectations,
full suite 3494/0. Vignette "Known-truth controls" on john_alpha, both
sides.
Rationale for the seed and the unit moved out of the parameter text into
the commit record (prose guard P1, P4); file headers and helper comments
cut to the contract.
…orrected

The vignette tested gen before the blocks, because aov orders interaction
terms last, so its pipeline read a false-positive rate of 0.185 (MCSE 0.012)
on john_alpha negatives against 0.047 (0.007) with gen last. The real-table
p-value moves from 3.6e-7 to 1.5e-5.

The docs said a negative control leaves the effect of `on` exactly absent.
Within incomplete blocks each block keeps its set of levels, so part of the
real effect survives. Examples now use complete replicates as strata, and the
vignette and docs state both limits.
A pinned seed reproduced a site's displacement only on a byte-identical table.
Draws are now a pure hash of seed, pair, try and site value, so shuffled, added
or removed rows leave other sites where they were. Corrects the rebuild table.
…tion

The design option keeps block and environment variance with no treatment effect,
so a treatment test on the clone has the original's denominator and a true null.
Column names give the partition; both run through the existing ladder.
…side controls

A plan holds the roles and named specs. mask() resolves each control spec on the
source and writes it back; the clone is unchanged by the spec. The analyst works
from the clone-vocabulary plan; the owner replays cleaning, checks the table and
the spec against the recipe and draws from a private seed. Version 0.17.0.
The clone plan's effect is drawn over sorted clone labels, so its order and the
public seed give away no map. Dropped on or target, a spec seed equal to the mask
seed, a plan passed to mask_set(), and a local clone at handover are refused. A
design level needs three rows to carry a shift, and the audit grades a number
that tracks the original row by row. Private seeds leave the manifest.
The audit measures tracking on the rows of small levels, with the means of large
terms taken out, so strong environments no longer block a clone and a tracking
subset is seen. Owner control seeds derive from a random key on the recipe. Spec
names holding hidden names are refused; a lone small level gets no shift; blank
handling is limited to on; a numeric alias of any value works on both sides.
…e the 0.17.0 tag

The owner's derived seed had 28 bits, and a per-replicate statistic verifies a
guess. Permutations on the plan route now come from SHA-256 of a 256-bit system
key. The default control unit is the finest legal column, not the coarsest. The
recipe's integrity check binds values. The refusal text says what each writer
records. Limits of the audit, the ladder and the land test are documented.
Integrity tolerance tightened to the bound of a 15-digit file, with a second sum
for small values beside a large one, and column types read back from a file now
match. The default unit returns to the coarsest column that can reach a 5 percent
level, with a warning when several qualify, because a finer unit hid
pseudoreplication. Arrangement counts use label symmetry across strata and keep a
unit whose first row is missing. The shape warning covers many levels. str() of
controls hides the key.
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 96.35762% with 55 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
R/plan.R 95.11% 31 Missing ⚠️
R/controls.R 97.78% 11 Missing ⚠️
R/recipe_print.R 61.11% 7 Missing ⚠️
R/control_spec.R 98.26% 2 Missing ⚠️
R/mask.R 95.91% 2 Missing ⚠️
R/check_integrity.R 98.07% 1 Missing ⚠️
R/jitter_coordinates.R 95.83% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

The negative control leaves any real effect of the permuted column in the
outcome. Each released reading is classed by what it estimates, the null is
a smoke test that a leak already in the table passes, and the planted size
is read against the residual of the pipeline's own model.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants