Documentation and Summary page improvements

[gaurav]

• Added note that definition should include qualifiers (closes Add support for documenting qualifiers in clade definitions #168)
• Documented the CSV export format (related to Document CSV export format #257, but I won't close that until I like to it from somewhere in the interface) as a Markdown file.
• Fixed a bug in which we were providing all the expected resolutions before all the actual resolution in the CSV file, despite the header saying that they should be interleaved (i.e. expected 1, actual 1, expected 2, actual 2).
• The Open Tree of Life lookup code was previously recording the provenance of the phylogeny in the phylogeny description field, but since this field is no longer used, I've moved it into the phylogeny curator notes field (see example below).
• I accidentally turned on "reformat file on save", and so my IDE changed a bunch of file formatting without me noticing. That shouldn't change any functionality and should be easier to read/maintain in the future, but it's still annoying.

This PR also closes #300 by modifying the summary table to make it clear that the final columns refer to phylogenies and replacing phylogeny descriptions (which are no longer displayed in Klados) with phylogeny curator notes.

[gaurav]

• No need to add "(including qualifiers)" -- free-form text already says I can write whatever I want.

[hlapp]

See inline notes. Perhaps a bit of a mess left from copy&paste?

[gaurav]

Thanks for the feedback, @hlapp! I've rewritten the "expected" and "actual" column descriptions as following:

• Phylogeny: [Phylogeny label] expected: The label of the node in the specified phylogeny to which the phyloreference was expected to resolve by the author.
  • Example: Alligatoridae
• Phylogeny: [Phylogeny label] actual: The label of the node actually resolved in the specified phylogeny to which the phyloreference was expected to resolve by the author.
  • Example: Alligatoridae_ott195670, or (unlabelled) if the node has no label

Is this clear?

The N in these descriptions was a defunct description of what we do if a phylogeny is unlabeled; in this case, instead of labeling this column Phylogeny: [Phylogeny label] expected, we use Phylogeny [Phylogeny index] expected, e.g. Phylogeny 1 expected. Should we include this information in this documentation as well? We could also use Phylogeny: [Phylogeny index] expected so they're a bit more similar to each other. What do you think?

[hlapp]

Isn't it Tidy Data practice to have NA or an equivalent value representation to signify that there is no value? Why should we make up a special string to signify the absence of a value? Or is this the special value that's already present on the phylogeny?

[gaurav]

The idea behind (unlabelled) was to distinguish between the case where a phyloref doesn't resolve at all (I think we currently represent this as blank in the Phylogeny: [Phylogeny label] actual field) and the case where it does resolve, but it does so on a node that doesn't have a label. Some options:

• NA for unlabelled node and blank for no resolution
• (unlabelled) (or some other standard string) for unlabelled node and NA (or some other string, e.g. (could not resolve), None) for no resolution
• NA: unlabelled node vs NA: could not resolve
• We could use the internal node identifier, which looks something like #phylogeny0_node0, if the resolved node is unlabelled and blank if the phyloref could not be resolved
• Add additional Phylogeny: [Phylogeny label] error column, which is blank unless the ... actual column is NA.

What do you think?

[hlapp]

Perhaps this: We could use the internal node identifier, which looks something like #phylogeny0_node0, if the resolved node is unlabelled and blank if the phyloref could not be resolved?

But on reflection, using (unlabelled) and (could not resolve) seem at least as clear if not clearer.

[gaurav]

But on reflection, using (unlabelled) and (could not resolve) seem at least as clear if not clearer.

Agreed! I've implemented this in 5464ea6.

[gaurav]

I've made this a bit clearer in d9f349f:

• Phylogeny: [Phylogeny label] expected: The label of the node in the specified phylogeny to which the phyloreference was expected to resolve.
  • Example: Alligatoridae
  • Will be set to (none) if no expected node was found.
• Phylogeny: [Phylogeny label] actual: The label of the node actually resolved for this phyloreference in the specified phylogeny.
  • Example: Alligatoridae_ott195670
  • Will be set to (resolution not yet run) if resolution has not yet been run.
  • Will be set to (could not resolve) if this phyloreference could not be resolved.
  • Will be set to (unlabelled) if a node was resolved, but it had no label.

[hlapp]

See inline note. @gaurav can you comment, fix, and/or clarify?

[hlapp]

I'm having trouble parsing The label of the node actually resolved in the specified phylogeny to which the phyloreference was expected to resolve by the author in contrast to The label of the node in the specified phylogeny to which the phyloreference was expected to resolve by the author. In the first case, is the node to which the phyloreference is found to resolve different from what the author seems to have expected, or is it the node's label that different from what the author seemed to have expected?

[gaurav]

I'm having trouble parsing The label of the node actually resolved in the specified phylogeny to which the phyloreference was expected to resolve by the author in contrast to The label of the node in the specified phylogeny to which the phyloreference was expected to resolve by the author. In the first case, is the node to which the phyloreference is found to resolve different from what the author seems to have expected, or is it the node's label that different from what the author seemed to have expected?

Ugh, yes, that's a bit of a mess. How about:

• Phylogeny: [Phylogeny label] expected: The label of the node in the specified phylogeny to which the phyloreference was expected to resolve.
• Phylogeny: [Phylogeny label] actual: The label of the node actually resolved for this phyloreference in the specified phylogeny.

I've implemented this change in 2003205.

[hlapp]

Looks all good, finally 👍