Repository navigation
Description for main lines in alignment_to_bam - #5062
Conversation
adamnovak
left a comment
There was a problem hiding this comment.
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.
| * 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) |
There was a problem hiding this comment.
I would write this like this:
| * 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) |
There was a problem hiding this comment.
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.
865712d to
6180bc2
Compare
adhirakunnath-hue
left a comment
There was a problem hiding this comment.
fixed wording and formatting
Updated parameter documentation format in alignment.hpp
adhirakunnath-hue
left a comment
There was a problem hiding this comment.
Added Doxygen Param Tags
adamnovak
left a comment
There was a problem hiding this comment.
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.
|
I've pulled this into the vgteam repo on a branch named |
Adds comments to alignment_to_bam() in src/alignment.hpp explaining its parameters (bam_header, alignment, refseq, refpos, refrev, cigar).