Skip to contents

Summarize APA report-output bundles

Usage

# S3 method for class 'mfrm_apa_outputs'
summary(object, top_n = 3, preview_chars = 160, ...)

Arguments

object

Output from build_apa_outputs().

top_n

Maximum non-empty lines shown in each component preview.

preview_chars

Maximum characters shown in each preview cell.

...

Reserved for generic compatibility.

Value

An object of class summary.mfrm_apa_outputs.

Details

This summary is a diagnostics layer for APA text products, not a replacement for the full narrative.

It reports component completeness, line/character volume, and a compact preview for quick QA before manuscript insertion.

Interpreting output

  • overview: total coverage across standard text components.

  • decision: the source-fit decision shown before draft-completeness checks; text completeness cannot promote a review or blocked fit.

  • components: per-component density and mention checks (including residual-PCA mentions).

  • sections: package-native section coverage table.

  • content_checks: contract-based alignment checks for APA drafting readiness.

  • overview$DraftContractPass: the primary contract-completeness flag for draft text components.

  • overview$ReadyForAPA: a backward-compatible alias of that contract flag, not a certification of inferential adequacy.

  • preview: first non-empty lines for fast visual review.

Typical workflow

  1. Build outputs via build_apa_outputs().

  2. Run summary(apa) to screen for empty/short components.

  3. Use apa$report_text, apa$table_figure_notes, and apa$table_figure_captions as draft components for final-text review.

Examples

# Saved synthetic JML/RSM analysis of example_core.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "core-jml.rds", package = "mfrmr"))
fit <- example_fit$fit
diag <- example_fit$diagnostics
apa <- build_apa_outputs(fit, diag)
summary(apa)
#> mfrmr APA Outputs Summary
#> 
#> Overview
#>  Components NonEmptyComponents TotalCharacters TotalNonEmptyLines Sections
#>           3                  3           10835                128        9
#>  AvailableSections ContentChecks ContentChecksPassed DraftContractPass
#>                  6             9                   9              TRUE
#>  ReadyForAPA
#>         TRUE
#> 
#> Decision
#>  - Interpretation: Fit-readiness requirements satisfied; formal inference is
#>    not supported
#>  - Formal inference: No
#>  - Why: The precision contract does not support formal inference (exploratory
#>    precision).
#>  - Next: The fit-readiness requirements were satisfied, but the precision
#>    contract does not support formal inference; keep the draft exploratory and
#>    review `precision_review_report()` before substantive use.
#> 
#> Component stats
#>              Component NonEmpty Characters Lines NonEmptyLines
#>            report_text     TRUE       5181    76            69
#>     table_figure_notes     TRUE       4987    50            34
#>  table_figure_captions     TRUE        667    41            25
#>  ResidualPCA_Mentions
#>                     0
#>                     4
#>                     2
#> 
#> Sections
#>                   SectionId  Parent                            Heading
#>               method_design  Method                    Design and data
#>           method_estimation  Method                Estimation settings
#>               results_scale Results                  Scale functioning
#>            results_measures Results                     Facet measures
#>    results_population_model Results Latent-regression population model
#>       results_fit_precision Results                  Fit and precision
#>  results_residual_structure Results                 Residual structure
#>      results_bias_screening Results                     Bias screening
#>            results_cautions Results                 Reporting cautions
#>  Available SentenceCount
#>       TRUE             3
#>       TRUE             5
#>       TRUE             2
#>       TRUE             3
#>      FALSE             0
#>       TRUE             6
#>      FALSE             0
#>      FALSE             0
#>       TRUE             1
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Text
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         A many-facet rating-scale Rasch model was fit to 768 observations from 48 persons scored on\na 4-category scale (1-4). The design included facets for Rater (n = 4), Criterion (n = 4).\nThe smallest non-person facet-level count was 192 retained rating rows, placing it in the\npackage's 'strong' screening band. These counts are not counts of independent examinees or\neffective sample sizes and do not establish precision or interval coverage. Review\ntargeting, connectedness and estimator-specific uncertainty alongside\n`facet_small_sample_review()`.
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     The RSM specification was estimated using JML with mfrmr. Precision summaries were\nexploratory in this run. Recommended use for this precision profile: JML standard errors\nand normal bands are exploratory approximations. Changing to MML does not by itself\nestablish valid uncertainty; review the fitted model and its uncertainty assumptions..\nOptimization met the numerical convergence checks after 209 function evaluations and 53\ngradient evaluations (LogLik = -820.949). MML model-comparison criteria are unavailable for\nthis fit; numerical completion alone does not establish comparability. Legacy descriptive\nAIC = 1753.898; legacy descriptive BIC = 2013.950; neither enters the common MML ranking\npanel. Terminal gradient sup-norm = 0.0001 (review threshold = 0.0001). Constraint\nsettings: noncenter facet = Person; anchored levels = 0 (facets: none); group anchors = 0\n(facets: none); dummy facets = none. Centered facets sum to zero across all levels,\nincluding anchors and group totals.
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           Category counts were available for all 4 categories: 0 unused and 0 below 10. Counts alone\ndo not establish category adequacy. Adjacent threshold comparisons: 0 decreasing among 2\navailable; 0 of 2 comparisons unavailable. Available estimates range from -1.32 to 1.38\nlogits. Adjacent threshold comparisons: 0 decreasing among 2 available; 0 of 2 comparisons\nunavailable.
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Person measures ranged from -2.18 to 2.68 logits (M = 0.00, SD = 1.10). Rater measures\nranged from -0.33 to 0.33 logits (M = -0.00, SD = 0.31). Criterion measures ranged from\n-0.42 to 0.25 logits (M = 0.00, SD = 0.29).
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  
#>  Overall mean-square fit was within the 0.5-1.5 screening band (infit MnSq = 0.99, outfit\nMnSq = 1.02). This band is the package's review convention; published mean-square\nguidelines differ, and band position is screening evidence rather than a model-validity\ndecision. MnSq outside [0.5, 1.5]: 1 of 56 classified elements flagged; 0 of 56 elements\nunclassified. Largest misfit signals among 56 elements with complete paired statistics:\nPerson:P023 (|ZSTD| = 2.20); Person:P018 (|ZSTD| = 1.79); Person:P048 (|ZSTD| = 1.60).\nCriterion exploratory reliability summary = 0.89 (separation = 2.78). Person exploratory\nreliability summary = 0.90 (separation = 3.01). Rater exploratory reliability summary =\n0.90 (separation = 3.05). Separation reliability describes differences among facet\nlocations relative to their estimation errors. High Person values indicate distinguishable\nabilities; high rater values indicate distinguishable severities, not inter-rater\nagreement. Low rater values can also reflect imprecision and do not establish agreement.\nThe index does not test every rater pair or quantify the practical size of severity\ndifferences. Reliability, separation and Strata are approximate compatibility indices using\nmarginal SEs; joint-information SEs do not validate this variance decomposition. They do\nnot account for covariance among estimates. EAP-based separation is not posterior-variance\nEAP reliability. Model and fit-adjusted values are companion indices, not confidence\nlimits. Strata describes hypothetical distinguishable strata, not discovered groups. Facet\nheterogeneity chi-square summaries use diagonal SE weights, not full-covariance joint\ntests. Inter-rater agreement for Rater is reported separately from separation reliability.\nDiagnostics match scores within Person and all remaining non-rater facets; each compared\npair contributes one opportunity per matched context. The denominator is 1152\nmatched-context opportunities across rater pairs, not a count of independent people. 6 of 6\ncandidate rater pairs have matched scores. Observed exact agreement = 0.36; observed\nadjacent agreement (absolute score difference at most 1, including exact matches) = 0.83;\nmodel-expected exact agreement = 0.37. The model-expected baseline uses fitted category\nprobabilities with calibration fixed; it is not chance agreement or an inferential test. It\nassumes conditional independence at the saved Person point score (EAP for MML), rather than\nintegrating over the Person posterior. These descriptive summaries do not classify rater\nquality or establish fairness. Element-level 95% approximate intervals (Normal\napproximation) accompany 56 of 56 estimates; 0 of 56 estimates have intervals eligible for\nprimary reporting.
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Precision note: this run relies on exploratory precision summaries, so confidence intervals\nand reliability summaries should not be treated as formal inferential quantities.
#> 
#> Content checks
#>                          Check Passed
#>         Method section heading   TRUE
#>        Results section heading   TRUE
#>    Precision caution alignment   TRUE
#>  Bias screening note alignment   TRUE
#>          Residual PCA coverage   TRUE
#>                  Note coverage   TRUE
#>               Caption coverage   TRUE
#>          Core section coverage   TRUE
#>   Interrater summary alignment   TRUE
#>                                                                           Detail
#>                                APA narrative should begin with a Method heading.
#>                                  APA narrative should include a Results heading.
#>               Precision caution should appear in the report text or note blocks.
#>                                                No bias screening block required.
#>     Residual PCA availability should be reflected in prose, notes, and captions.
#>        All note-map entries should be represented in the consolidated note text.
#>  All caption-map entries should be represented in the consolidated caption text.
#>             Core package-native sections should be available in the section map.
#>          Interrater agreement wording should appear in the report text or notes.
#> 
#> Preview
#>              Component
#>            report_text
#>     table_figure_notes
#>  table_figure_captions
#>                                                                                                                                                           Preview
#>                                          Method. | Design and data. | A many-facet rating-scale Rasch model was fit to 768 observations from 48 persons scored on
#>  Table 1. Facet summary | Note. Measures are reported in logits; higher person values indicate higher ability, and higher non-person facet values indicate gre...
#>                                                                                         Table 1 | Facet Summary (Measures, Precision, Fit, Reliability) | Table 2
#> 
#> Notes
#>  - All standard APA text components are populated.Contract-based content checks passed.In this summary, ReadyForAPA/DraftContractPass indicates contract completeness for draft text components; it does not certify formal inferential adequacy.Use object fields directly for full text; summary provides compact diagnostics.