The API of accessing fields of BioAlignments

[jakobnissen]

For context, please read https://discourse.julialang.org/t/accessing-type-internal-fields-in-package-interfaces/70263

In brief, I was teaching some students about BioAlignments recently. My fellow teachers, who did not know about the package, were surprised at the workflow a user is faced with. Let me give an example:

The pairalign function returns a PairwiseAlignmentResult, which contains a PairwiseAlignment, which again contains an Alignment. A user may, in the same breadth, be interested in extracting information from all these three types, for example the score from the first, the number of matches of the second, and the CIGAR string from the third.

However, it is quite unclear, and undocumented how the user is supposed to get these internal types from their initial PairwiseAlignmentResult. Both me and my fellow teachers thought accessing a type's undocumented fields is messing with internal behaviour, but then how are you supposed to get e.g. the Alignment object? Further, how is a user even supposed to know they are to use dump to inspect the fields of the returned object? Weirdly, the alignment function, despite its name, does not actually return an Alignment object.

Here is what I propose:

• We should improve the docstrings and docs for each type. What exactly is the difference between PairwiseAlignmentResult, PairwiseAlignment and Alignment?
• We should add documented, exported functions the extract the relevant types, and have them displayed at the top of the docs for each type. Fields that are NOT directly relevant to the user should not have these getter functions
• When adding these features, we should have some simple test where we exercise basic functionality and make sure the user does not need to reach into internal struct layouts to perform simple tasks