rolescry

New function: harmonize_roles()

• harmonize_roles(sites) aligns the roles detected name-blind in two or more sites (a named list of data.frames) into a map (role by site, aligned/partial/absent), descriptive checks and a site_only table. Flags are categorical only: type_mismatch, coding_mismatch, size_mismatch; Jaccard and range overlap are reported but never flagged. The residual covariate role is excluded. Detectors are unchanged. See ?harmonize_roles, the README and the vignette.

New role: coupled_pair

• The identifiable object in a dependent (binary, positive-continuous) pair is the PAIR itself; whether it is (survival time, event) or (cause, binary outcome) is design-relative and, in general, not a function of the joint distribution. The survival roles are now assigned only when censoring geometry singles the survival reading out: the continuous member is anchored at zero (mean - 2 sd <= 0), events sit strictly earlier than censorings, and the top time-tertile's event rate is strictly below the bottom's. Otherwise the new coupled_pair role reports the pair with both readings, and the user decides. Documented ceiling: a zero-anchored continuous cause whose larger values are protective still reads as survival.
• A randomized-trial table (binary arm shifting a positive measurement) is therefore no longer reported as a survival pair: it becomes coupled_pair.
• **Dominance gate.** When two decisive pairs on DISJOINT time columns compete, the winner is assigned the survival roles only if its event-time association dominates at the 2-sigma universal (Fisher z two-correlation comparison); otherwise the pair is reported as coupled_pair with the competing reading named. A rival sharing the winner's time column agrees on the axis and merely offers another event candidate (a ranking question), and an ID-typed time candidate may win on its exceptional evidence bar but may not veto a structurally-typed reading.

Binary-outcome evidence: two-part MDL code

• The per-predictor 2-sigma dCor test behind outcome_binary is replaced by a Bernoulli MDL code: a candidate cause is admitted only when its one-slope logistic code -- or, for non-monotone dependence, a two-Gaussian split of the predictor by the outcome -- saves more bits than the slope's parameter cost (1/2 log2 n) PLUS the log2(m) model-index bits naming it among the m candidates (Rissanen two-part code). The naming term makes the evidence selection-consistent, so scanning many predictors on noise no longer buys phantom outcomes (~14% -> ~6% of pure-noise tables); a weak borderline cause now stays honestly silent instead.

Pass 5: derived deciders for group, pairs and ordinal scales

• **group_var** is the character/factor column with the highest normalized Shannon entropy H/log2(k) (ties: fewer levels, then value fingerprint); a column with a level seen fewer than 3 times is not a candidate. The point table is gone.
• **Paired vs agreement** is decided by the MDL shift bits of the best pair (bits saved by coding the difference with a free mean, net of one parameter): > 0 => paired_pairs, otherwise agreement_pairs. potential_pairs now carries bits and shift_bits.
• **Ordinal scale_items** are accepted when a one-factor Gaussian two-part code on the standardized candidate columns saves bits over independence (.mdl_factor_bits).
• score/max_score/pct are bits (max_score NA) for derived roles and points for the ported ones.
• **Measured and rejected, kept on ported scorers:** survival admission/rank by association bits, wide repeated_measures as a one-factor block (false positives rose from 15 to 163-207 tables), and a derived binary-item scale criterion (it rejected every simulated binary battery) each regressed false positives or recall and were reverted. Survival, wide repeated_measures and binary scale_items therefore remain on point scorers.

Domain generalization (finance and beyond)

• **New role time_index.** Date/POSIXct columns -- and character columns whose every value parses as a date -- type as Datetime and are reported as calendar axes. They were previously typed "Other" and invisible to every detector. The class and format are properties of the values, so name-blindness is preserved.
• **Panel entity/time axis.** On a balanced long panel both axis readings satisfy the structural test. Serial dependence of the measures along the candidate time axis (2-sigma) now picks the entity; when nothing discriminates, the panel is reported with its admissible axis readings (repeated_measures$panel_axes) and subject_id stays silent. A Datetime column can be the panel time axis.
• **Short rating batteries.** A battery of exactly 3-4 ordinal items (e.g. multi-agency credit ratings) is now scoreable as scale_items, guarded by the pairwise 2-sigma dependence gate; the >= 5-item path is unchanged.
• **Finance keyword dictionary.** rolescry_default_name_bonus(domain = "finance") (or "all"); the default "clinical" is unchanged. The name channel remains optional and capped.
• README, DESCRIPTION and examples reworded domain-neutrally.

Behavior changes

• **Logical event columns.** A TRUE/FALSE column now value-types as Binary; it was typed "Other" and silently excluded from every survival and outcome candidate set.
• **Sink veto in repeated measures.** A column MDL-explained by two or more mutually independent other block members is a dependency sink (collider), not a repeated measurement, and is removed from the block. y = x1 + x2 + noise is no longer swallowed as a correlated block, so the continuous outcome can be detected.
• **covariate is now the residual role.** It lists the continuous, categorical and binary columns that no other role claimed. In 0.2.0 it listed every such column, including the survival pair, the group and the outcomes.
• **Survival pairs are compared on common rows.** Every admissible time/event pair is re-evaluated on the rows complete in all candidate columns. Previously each pair was judged on its own available cases, so a pair whose columns were missing in different rows could win on a different subsample (e.g. survival::lung).
• **Integer follow-up times.** An all-distinct positive integer column (which value-types as an identifier) is now a survival-time candidate. Because this overturns the identifier typing, it must pass both association tests (monotone MDL and the dCor independence test), not either one (e.g. survival::ovarian).
• **Subject id atomicity.** A column already assigned to a survival role is no longer also reported as subject_id.

Bug fixes

• The KSG mutual-information estimator returned NaN on tied values (a neighbor count of -1 passed to digamma()), which made the dependence measure NaN and emitted warnings (e.g. survival::pbc). Counts are now clamped at zero.
• Correlation calls on constant columns in the paired/agreement scorers no longer emit "standard deviation is zero" warnings; the result is unchanged (NA).

Documentation

• The README quick-start example now uses data in which the documented roles are actually present, and a "Known limitations" section was added.
• ?detect_roles states that roles can overlap, that covariate is residual, and that a role is reported as not found rather than guessed.