feat: sort ASCII-style alignment pileups

[deliaBlue]

Description

Fixes #145.

In addition, the treatment of insertions within an alignment's sequence has been documented where required.

Conventional Commits

• I made sure that the PR title follows the
  Conventional Commits specification

Checklist

• My code changes follow the style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• [] I have added tests that prove my fix is effective or that my feature
  works
• New and existing tests pass locally with my changes and I have not
  reduced the code coverage relative to the previous state
• I have updated any sections of the project's documentation that are
  affected by the proposed changes

Summary by Sourcery

Add configurable sorting for ASCII-style alignment pileups and document alignment insertion handling.

New Features:

• Introduce --sort-by and --reverse-sort options to control ordering of ASCII-style alignment pileups by position or count and direction.
• Expose pileup sorting mode via the global configuration (sort_by) and propagate it through Snakemake rules to the pileup script.

Enhancements:

• Update ascii_alignment_pileup script version to 1.3.0.
• Clarify and document how insertions in alignments are handled when generating ASCII-style alignment pileups.

Documentation:

• Extend API, workflow, overview, pipeline, and README documentation to describe pileup sorting modes, configuration keys, and insertion handling semantics.

Tests:

• Update test configuration files to include the new sort_by setting for linting and pipeline tests.

[sourcery-ai]

Reviewer's Guide

Adds configurable sorting for ASCII-style alignment pileups (by count or by position, with optional reversal), wires it through the Snakemake rules and config, documents the behavior (including insertion handling), and bumps the script version.

File-Level Changes

Change	Details	Files
Add configurable sorting behavior to ASCII-style alignment pileup generation.	Introduce CLI options --sort-by ("position" or "counts") and --reverse-sort to ascii_alignment_pileup.R with defaults and help text. Parse new CLI options into sort.by and rev.sort variables and use them to control ordering of the pileup data frame. Implement two sorting modes: by first nucleotide position then count then last nucleotide position, or by count then positions, with direction controlled by rev.sort. Retain strand-specific handling by reversing sequences before/after sorting and computing first/last non-padding character positions accordingly. Bump script version from 1.2.1 to 1.3.0.	workflow/scripts/ascii_alignment_pileup.R
Wire new sorting configuration through workflow rules and config files.	Extend config_template.yaml with a sort_by key defaulting to 'position' and explanatory comments. Pass config["sort_by"] as a parameter to per-library, per-run, and per-condition pileup Snakemake rules, mapping it to the --sort-by CLI flag in the R script invocation. Update test config files to include sort_by: 'position' so they conform to the new schema.	config/config_template.yaml workflow/rules/pileup.smk test/test_files/config_lint.yaml test/test_files/config.yaml config/config_schema.json
Document new sorting behavior and clarify insertion handling in pileups documentation.	Add a SORTING section to the ascii_alignment_pileup R script API docs describing default sort behavior, the --sort-by option, and --reverse-sort flag semantics. Document sort_by in workflow module docs and pipeline overview, including default and allowed values. Add warnings/notes in overview and README explaining how insertions in alignments are handled (removed from the read sequence and collapsed appropriately). Mention new parameter sections in pileup-related workflow docs for the sort_by configuration.	docs/api/ascii_alignment_pileup.R.md docs/workflow/modules/pileups.md pipeline_documentation.md docs/workflow/overview.md README.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#145	Add CLI options --sort-by ("position" or "counts", default "position") and --reverse-sort to ascii_alignment_pileup.R.	❌	The PR adds both options to ascii_alignment_pileup.R (sort.by and rev.sort are parsed from CLI), but the default for --sort-by is set to "counts" rather than the requested "position". While the workflow config passes sort_by: 'position', the script’s own CLI default does not match the issue specification.
#145	Implement sorting of ASCII-style alignment pileups according to --sort-by and --reverse-sort, affecting order by position and counts as described.	✅

Possibly linked issues

• feat: sort ASCII-style alignment pileups #145: The PR implements the requested --sort-by and --reverse-sort pileup sorting options and wires them into workflow/docs.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 3 issues, and left some high level feedback:

• Consider validating --sort-by against the supported values ("position" and "counts") early in ascii_alignment_pileup.R and failing fast on invalid input instead of silently falling back to the else branch.
• The new --reverse-sort CLI flag is defined in ascii_alignment_pileup.R but never passed from the Snakemake rules, so the workflow currently cannot change the sort direction; either wire it through the rules or document it as a script-only option.
• In docs/api/ascii_alignment_pileup.R.md the option list entry for the reverse-sort flag is missing the leading -- (it appears as reverse-sort instead of --reverse-sort), which may confuse users when calling the script.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider validating `--sort-by` against the supported values ("position" and "counts") early in `ascii_alignment_pileup.R` and failing fast on invalid input instead of silently falling back to the `else` branch.
- The new `--reverse-sort` CLI flag is defined in `ascii_alignment_pileup.R` but never passed from the Snakemake rules, so the workflow currently cannot change the sort direction; either wire it through the rules or document it as a script-only option.
- In `docs/api/ascii_alignment_pileup.R.md` the option list entry for the reverse-sort flag is missing the leading `--` (it appears as `reverse-sort` instead of `--reverse-sort`), which may confuse users when calling the script.

## Individual Comments

### Comment 1
<location path="workflow/scripts/ascii_alignment_pileup.R" line_range="141" />
<code_context>
+          action="store",
+          type="character",
+          default="counts",
+          help="Specify the sort type (either \"position\" or \"counts\"). 
+          [default \"%default\"]",
+          metavar="string"
</code_context>
<issue_to_address>
**issue (bug_risk):** The help string is split across lines in a way that will break R string syntax.

This help string will cause a parse error because double-quoted strings in R cannot span multiple physical lines. Please either keep the string on one line, insert an explicit `\n` before `[default "%default"]`, or build it with `paste()` or a similar approach.
</issue_to_address>

### Comment 2
<location path="workflow/scripts/ascii_alignment_pileup.R" line_range="140" />
<code_context>
+          "--sort-by",
+          action="store",
+          type="character",
+          default="counts",
+          help="Specify the sort type (either \"position\" or \"counts\"). 
+          [default \"%default\"]",
</code_context>
<issue_to_address>
**question:** CLI default for --sort-by differs from the workflow config default.

The CLI default for this flag is "counts", whereas `config_template.yaml` uses `sort_by: 'position'`. Via the Snakemake workflow, the config overrides this, but when running the script directly, users see different default behavior. If this difference isn’t intentional, please align the defaults; if it is, consider documenting the distinction explicitly rather than relying only on `%default`.
</issue_to_address>

### Comment 3
<location path="docs/api/ascii_alignment_pileup.R.md" line_range="148-153" />
<code_context>
   not provided the input BAM file(s) name will be used instead.
+- <b>`--sort-by=STRING`</b>: Specify the sort type (either "position" or
+  "counts"). (default = "counts")
+- <b>`reverse-sort`</b>: Reverse the sort order; from "from-left-to-right" to
+  "from-right-to-left" for sort type "position", and from "descending" to
+  "ascending" for sort type "counts".
</code_context>
<issue_to_address>
**issue (typo):** Option name is missing leading dashes compared to earlier usage of `--reverse-sort`.

In the options list this flag is shown as `reverse-sort` (no leading `--`), which is inconsistent with the earlier `--reverse-sort` usage and the actual CLI. Please update this entry to `<b>
--reverse-sort`</b>` to match.

```suggestion
- <b>`--sort-by=STRING`</b>: Specify the sort type (either "position" or
  "counts"). (default = "counts")
- <b>`--reverse-sort`</b>: Reverse the sort order; from "from-left-to-right" to
  "from-right-to-left" for sort type "position", and from "descending" to
  "ascending" for sort type "counts".
- <b>`-h`</b> | <b>`--help`</b>: Show this information and die.
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[uniqueg]

Looks good. One minor thing: best to define sort_by as an enumerator, which can only take on the values position (default) or counts, then validate the user choice via an optparse custom validator.

[uniqueg]

LGTM