docs(impute): Update documentation w.r.t. censoredInt and MBimpute

[tonywu1999]

Motivation and Context

Based on this google groups post, it appears the MSstats documentation is not correct w.r.t. how the code handles censoredInt and MBimpute.

---

PR Type

Documentation

---

Description

• Clarify censored missing-value semantics

  • Define NA, 0, and NULL
  • Explain left-censoring and random missingness

• Document imputation behavior consistently

  • Describe AFT-based imputation wording
  • Note imputation ignored for NULL

• Regenerate matching .Rd references

---

Diagram Walkthrough

flowchart LR
  A["R/dataProcess.R roxygen docs"]
  B["Clarified censoredInt and censored_symbol behavior"]
  C["Clarified MBimpute and impute behavior"]
  D["Regenerated .Rd documentation files"]
  A -- "updates" --> B
  A -- "updates" --> C
  B -- "propagates to" --> D
  C -- "propagates to" --> D

Loading

File Walkthrough

Relevant files

Documentation

7 files dataProcess.R Clarify censored-value and imputation parameter docs          +23/-20  MSstatsSummarizeSingleTMP.Rd Sync TMP single-protein argument documentation                      +12/-10  MSstatsSummarizeWithMultipleCores.Rd Update multicore summarization argument descriptions          +12/-10  MSstatsSummarizeWithSingleCore.Rd Update single-core summarization argument descriptions      +12/-10  dataProcess.Rd Refresh `dataProcess` censored and imputation docs              +12/-11  dot-getNonMissingFilterStats.Rd Clarify internal censored-symbol parameter behavior            +7/-6      dot-runTukey.Rd Align Tukey summarization censored-value documentation      +8/-7

---

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates across seven files clarify the semantics of censoring and imputation parameters (censored_symbol, impute, censoredInt, MBimpute) in MSstats functions, explicitly defining how parameter values ('NA', '0', NULL) control missing-value encoding and imputation behavior.

Changes

Cohort / File(s)	Summary
Roxygen Documentation R/dataProcess.R	Updated censoredInt parameter documentation to explicitly map parameter values to censoring assumptions: 'NA' for left-censoring, '0' for zero-value censoring with NA treated as missing-at-random, NULL for disabled censoring and imputation.
Primary Summarization Functions man/MSstatsSummarize*.Rd (SingleTMP, WithMultipleCores, WithSingleCore), man/dataProcess.Rd	Rewrote impute and censored_symbol documentation across four files to clarify conditional behavior: impute applies only under specific censoring settings; 'NA' vs '0' distinguishing left-censored interpretation; NULL disables censoring and imputation entirely.
Internal Helper Functions man/dot-getNonMissingFilterStats.Rd, man/dot-runTukey.Rd	Updated censored_symbol parameter documentation for internal functions, aligning with primary API changes to explicitly define left-censoring semantics and NULL behavior as missing-at-random with no censoring.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Feature model weights #174: Introduces/implements censored_symbol and modifies imputation/censoring behavior that this PR's documentation updates describe.
• feat(protein turnover): per-label statistics and multi-label summarization #193: Modifies the same documentation and parameter semantics around censoring/imputation across the same functions.

Suggested labels

Review effort 2/5, documentation

Poem

🐰 A rabbit hops through docs with care,
Clarifying censors here and there,
"NULL" means missing, "NA" means lost,
And "0" defines the lower cost,
With meanings clear, we hop along! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: updating documentation for censoredInt and MBimpute parameters across multiple files to clarify censored-value semantics and imputation behavior.
Description check	✅ Passed	PR description includes motivation/context, detailed changes with file breakdown, and checklist reference, but testing section is empty.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[coderabbitai]

🧹 Nitpick comments (2)

man/dot-runTukey.Rd (1)

18-24: Minor: "impute is ignored" text references a parameter .runTukey doesn't have.

.runTukey() itself has no impute argument (see usage on line 7), so the last sentence — which is copy/pasted from the shared censored_symbol paragraph used by MSstatsSummarizeSingle* — reads a bit oddly in this helper's Rd page. Also, the 'NA' (default) label is inherited wording but the function signature has no default for censored_symbol. Since this is auto-generated, consider tailoring the roxygen text in R/utils_summarization.R for .runTukey (e.g., drop the "(impute is ignored)" clause here, or link to dataProcess for end-user semantics).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@man/dot-runTukey.Rd` around lines 18 - 24, The .runTukey Rd entry incorrectly
mentions an impute argument and a default for censored_symbol; update the
roxygen in R/utils_summarization.R that generates the .runTukey help so the
censored_symbol text for .runTukey does not state "(impute is ignored)" and does
not assert "'NA' (default)"; instead provide wording appropriate for .runTukey
(e.g., drop the impute clause and omit the default claim or add a note pointing
users to dataProcess for semantics), ensuring you change the shared
censored_symbol text only for the .runTukey documentation generation and keep
MSstatsSummarizeSingle* text unchanged.

R/dataProcess.R (1)

191-197: Nit: 'NA' (default) label is inaccurate for the exported helpers.

MSstatsSummarizeWithMultipleCores, MSstatsSummarizeWithSingleCore, and MSstatsSummarizeSingleTMP are exported but their signatures don't supply a default for censored_symbol (only dataProcess()'s censoredInt = "NA" does). Users calling these helpers directly will get an error, not the "default". Consider rephrasing for these helpers, e.g. 'NA' (value used by dataProcess by default) or just 'NA'.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@R/dataProcess.R` around lines 191 - 197, The param doc claims "'NA'
(default)" but the exported helper functions MSstatsSummarizeWithMultipleCores,
MSstatsSummarizeWithSingleCore, and MSstatsSummarizeSingleTMP do not provide a
default for censored_symbol, causing a mismatch; either (A) add censored_symbol
= "NA" to those functions' signatures so the doc is accurate, or (B) reword the
roxygen `@param` text in R/dataProcess.R to "'NA' (value used by dataProcess by
default)" (or just "'NA'") so it no longer asserts a default for the helpers;
update the documentation text accordingly and ensure the helper functions'
parameter names match exactly (censored_symbol / censoredInt mapping) so the
exported help is consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@man/dot-runTukey.Rd`:
- Around line 18-24: The .runTukey Rd entry incorrectly mentions an impute
argument and a default for censored_symbol; update the roxygen in
R/utils_summarization.R that generates the .runTukey help so the censored_symbol
text for .runTukey does not state "(impute is ignored)" and does not assert
"'NA' (default)"; instead provide wording appropriate for .runTukey (e.g., drop
the impute clause and omit the default claim or add a note pointing users to
dataProcess for semantics), ensuring you change the shared censored_symbol text
only for the .runTukey documentation generation and keep MSstatsSummarizeSingle*
text unchanged.

In `@R/dataProcess.R`:
- Around line 191-197: The param doc claims "'NA' (default)" but the exported
helper functions MSstatsSummarizeWithMultipleCores,
MSstatsSummarizeWithSingleCore, and MSstatsSummarizeSingleTMP do not provide a
default for censored_symbol, causing a mismatch; either (A) add censored_symbol
= "NA" to those functions' signatures so the doc is accurate, or (B) reword the
roxygen `@param` text in R/dataProcess.R to "'NA' (value used by dataProcess by
default)" (or just "'NA'") so it no longer asserts a default for the helpers;
update the documentation text accordingly and ensure the helper functions'
parameter names match exactly (censored_symbol / censoredInt mapping) so the
exported help is consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 74dd8c1f-2323-41df-8cc9-e8faa6642e79

📥 Commits

Reviewing files that changed from the base of the PR and between b05b398 and e0210d7.

📒 Files selected for processing (7)

• R/dataProcess.R
• man/MSstatsSummarizeSingleTMP.Rd
• man/MSstatsSummarizeWithMultipleCores.Rd
• man/MSstatsSummarizeWithSingleCore.Rd
• man/dataProcess.Rd
• man/dot-getNonMissingFilterStats.Rd
• man/dot-runTukey.Rd