docs: document keep_abundant_per_category and identify_abundant_per_category (PR #341)

[Copilot]

PR #341 introduced keep_abundant_per_category() and identify_abundant_per_category() as category-aware alternatives to global abundance filtering. This PR adds user-facing documentation so the feature is discoverable and correctly applied.

Changes

README.md

• Added both new functions to the Filtering and Selection Functions table

vignettes/introduction.Rmd

• Added both new functions to the function table
• Added a "Category-Aware Abundance Filtering" subsection inside the existing Abundance Filtering walkthrough with:
  • Conceptual motivation ("Why this matters")
  • Code chunks for: basic per-category filtering, CPM threshold, multi-category requirement, mark-only mode, and feature count comparison across strategies
  • Explicit guidance on when to prefer this over global keep_abundant()

inst/NEWS.rd

• Added changelog entry for both functions with a description of the key formula_design and minimum_category parameters

Key API (from PR #341)

# Retain genes abundant in at least one treatment group
airway |>
  keep_abundant_per_category(
    formula_design    = ~dex,   # grouping variable from colData
    minimum_counts    = 10,
    minimum_proportion = 0.7,
    minimum_category  = 1       # default: at least one category must pass
  )

# Mark only, without filtering
airway |>
  identify_abundant_per_category(formula_design = ~dex)

The core motivation: global filtering silently drops features that are strongly expressed in one group but absent in others — exactly the signals targeted by differential testing. Category-aware filtering preserves them.

Original prompt

Update the documentation in tidyomics/tidybulk to cover the functionality introduced by pull request #341 (https://github.com/tidyomics/tidybulk/pull/341), titled "Keep abundant per category as an alternative filtering method".

The goal is to create a documentation-focused pull request that updates the README and relevant vignette(s) so users can discover, understand, and correctly apply this feature.

Requirements:

1. Review PR Keep abundant per category as an alternative filtering method #341 to understand the exact user-facing API, argument names, behavior, and examples for the new functionality.
2. Update the README to document this capability clearly.
   • Explain what the new filtering mode does.
   • Show how to use it with the exact function signature introduced in PR Keep abundant per category as an alternative filtering method #341.
   • Explain why this matters, especially for retaining biologically meaningful features that are abundant in one category/group but not globally abundant across all samples.
3. Update the relevant vignette(s) with a more complete explanation.
   • Add a section describing category-aware abundance filtering.
   • Include a practical example using the real API from the PR.
   • Explain when to use this approach versus global filtering.
   • Emphasize why this is important for condition-specific, tissue-specific, or subgroup-specific signals.
4. Ensure the wording is polished and user-facing, not implementation-focused.
5. Keep the documentation consistent with the package style and existing docs structure.
6. If there is a NEWS/changelog file that should mention this user-facing functionality, update it if appropriate.
7. Open a pull request with the documentation changes.

Please make the documentation thorough and clear, with emphasis on both:

• how to use the feature
• why the feature is important in real analyses

Repository: tidyomics/tidybulk

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: please update README and vignettes with this functionality documenting it well, and why it is important

Assistant: I can do that, but I can’t directly make the doc changes unless you want me to open a PR.

If your goal is for me to implement the README/vignette updates in the repo, say:

• open a PR in tidyomics/tidybulk for PR #341 docs

and I’ll create it.

If you want the documentation text first, here’s a polished draft you can use for the README and vignettes.

Suggested documentation update

What changed

Add documentation for a new filtering option that keeps features that are abundant within at least one category, as an alternative to global abundance filtering.

Why this matters

This is important because biologically meaningful signals are often category-specific. A feature may be highly abundant in one group of samples but low or absent elsewhere. Global filtering can remove those features too early, especially in designs involving:

• case vs control comparisons
• tissue or cell-type stratification
• treatment-specific responses
• subgroup discovery

Filtering by abundance per category helps retain features that are informative for downstream differential analyses and visualization, while still removing broadly uninformative low-abundance features.

---

README text draft

You could add a short section under filtering / preprocessing.

### Keep features abundant in at least one category

In addition to standard abundance filtering across all samples, `tidybulk` supports filtering that preserves features abundant within at least one category.

This is useful when a transcript, gene, taxon, or feature is strongly expressed in only one experimental group. In those situations, global filtering can remove biologically relevant signals before downstream analysis.

For example, if a feature is abundant in treated samples but mostly absent in controls, keeping features that are abundant in at least one category allows you to retain that signal for downstream differential testing.

This approach is especially helpful for:

- case/control analyses
- multi-group experimental designs
- tissue- or cell-type-specific signals
- condition-specific biomarkers

In general, category-aware filtering provides a good balance between:

- removing broadly low-information features
- preserving group-specific biology

Example:

```r
tbl %>%
  keep_abundant(.sample = sample, .abundance = count, .category = condition)
```

Use this option when your analysis question depends on retaining features that may be strong in one group but not globally abundant across the full dataset.

If the actual argument name differs from .category, I should align the wording to the exact API in PR #341 before finalizing.

---

Vignette section draft

This should be a bit more explanatory and example-driven.

## Keeping features abundant in at least one category

A common preprocessing step is to remove features with very low abundance. This reduces noise...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[stemangiola]

@copilot this description you added in README is better done in Vognette, where we do the filtering

[Copilot]

Moved the detailed description to the vignette. README now only lists the two new functions in the Filtering and Selection Functions table (commit a72428f).

[stemangiola]

@copilot this PR should be merged into the originating PR #341

[Copilot]

@copilot this PR should be merged into the originating PR #341

I'm unable to directly push to another PR's branch — I can only commit to the current branch. To incorporate these documentation changes into PR #341, you can cherry-pick the commits from this branch:

git checkout <pr-341-branch>
git cherry-pick 58ea22e  # original docs commit
git cherry-pick a72428f  # README cleanup commit
git push

Alternatively, you can close this PR and add the documentation changes directly to PR #341's branch.

[stemangiola]

@GaoYingnan can you please merge this changes to your PR?