Skip to content

Description for main lines in alignment_to_bam - #5062

Merged
adamnovak merged 3 commits into
vgteam:masterfrom
adhirakunnath-hue:adhirakunnath-hue-patch-1
Nov 13, 2026
Merged

adamnovak merged 3 commits into
vgteam:masterfrom
adhirakunnath-hue:adhirakunnath-hue-patch-1

Conversation

@adhirakunnath-hue

@adhirakunnath-hue adhirakunnath-hue commented Oct 14, 2026 •

Copy link
Copy Markdown

Adds comments to alignment_to_bam() in src/alignment.hpp explaining its parameters (bam_header, alignment, refseq, refpos, refrev, cigar).

@adamnovak adamnovak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a couple of problems here we would need to see fixed before being able to merge this.

First, this includes all the changes from #5028, and #5028 still has changes that need to be made to it for it to be ready to merge. Either #5028 needs to be finished and merged first, or a git rebase operation needs to be done so that the changes made in 865712d are on top of mainline vg and not on top of the README changes. You could do this using the "interactive rebase" method described in https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History, using the section on "Reordering Commits" to remove the README commits from this branch, followed by a "force push" of the branch to Github.

If that doesn't work, you can start a new branch after checking out origin/master, and copy-paste in all your changes.

The second problem is that the new comments aren't in quite the right terms for including in vg, because they don't use the appropiate bioinformatics terms used elsewhere in the code. For example, they use "letters" instead of "sequence", and "letter number" instead of "sequence position". It's definitely a good idea to explain these parameters, but I think the explanations shouldn't also be explaining the general terminology of the field. If we do want to explain what a "sequence" is somewhere, we should put that material on the vg Github wiki in one of the introductory pages.

Finally, it looks like there are only changes to alignment.hpp. These would be fine changes on their own, but the title of the PR makes it sound like there were meant to be new comments added to the body of the function, which may have gone missing between the author's computer and Github. A longer description of the PR's intent was not provided, so it's hard to be sure whether they were supposed to be there or not.

Comment thread src/alignment.hpp Outdated
Comment on lines +166 to +172
* Decoding each line
* Bam_header = the file’s table of contents
* Alignment = vg’s notes about the read (name, letters, quality scores)
* Refseq (reference sequence) = what chromosome it was placed in (chr1)
* Refpos (reference position) = what letter number it was in that chromosome (124566)
* Refrev (reference review) = did it match the other side of the DNA (true or false)
* Cigar = the match description (50M 2I)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would write this like this:

Suggested change
* Decoding each line
* Bam_header = the file’s table of contents
* Alignment = vg’s notes about the read (name, letters, quality scores)
* Refseq (reference sequence) = what chromosome it was placed in (chr1)
* Refpos (reference position) = what letter number it was in that chromosome (124566)
* Refrev (reference review) = did it match the other side of the DNA (true or false)
* Cigar = the match description (50M 2I)
* bam_header = the file’s metadata
* alignment = vg’s representation of the read (name, sequence, quality scores)
* refseq (reference sequence) = what chromosome it was placed on (chr1)
* refpos (reference position) = what sequence offset it was placed at on that chromosome (124566). This follows SAM/BAM conventions, and gives the lowest position in the reference regardless of read orientation.
* refrev (reference reverse-ness) = whether it was placed on the reverse strand (true) or forward strand (false)
* cigar = the alignment description (50M 2I)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of =, you could try Doxygen param tags, which would format a little better in the automatically-generated web documentation: https://vgteam.github.io/vg/namespacevg.html#a0d064f9483fe862fe937abc9e7474e57

Added detailed comments explaining the decoding process for alignments.
@adhirakunnath-hue
adhirakunnath-hue force-pushed the adhirakunnath-hue-patch-1 branch from 865712d to 6180bc2 Compare October 21, 2026 03:17

@adhirakunnath-hue adhirakunnath-hue left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed wording and formatting

Updated parameter documentation format in alignment.hpp

@adhirakunnath-hue adhirakunnath-hue left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added Doxygen Param Tags

@adamnovak adamnovak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know that we need the [in] part (isn't that sort of the only option on e.g. a const int32?), but this looks OK.

@adamnovak

Copy link
Copy Markdown
Member

I've pulled this into the vgteam repo on a branch named alignment-to-bam-docs so tests will run.

@adamnovak
adamnovak merged commit c5c67c7 into vgteam:master Nov 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants