augur export prefers num_date over numdate exported by augur refine

[huddlej]

The augur refine command exports branch length information including a numdate field that provides a likely estimate for each node's date.
The augur export command checks for both numdate and num_date fields in any "node data" JSONs or the metadata TSV and preferentially selects the num_date information.
In the case where the metadata TSV has a num_date field that was annotated by a previous step in the pipeline, the maximum likelihood numdate value from augur refine is omitted in favor of the metadata's value.

There are a couple issues to figure out:

1. Can we pick one name for the date attribute and use it consistently across all datasets and code repositories?
2. Can we determine a way to resolve conflicts between fields in data passed to augur export?

Even if the solution to the second part is to print an error and exit loudly, that would allow users to track down the issue with their data.

[tsibley]

My 2¢:

1. 👍 for doing this. I'd tend towards num_date if they're otherwise equal names.
2. I don't think there's a good general resolution method where the behaviour would be obvious to an outside observer. 👍 for requiring that annotation files being joined in augur export have unique field names, and exiting with a descriptive, useful error message if they don't. (This is also the most parsimonious and easiest to implement option.)

[huddlej]

This is related to #180 and duplicates that issues request to pick a standard name for numerical dates. This ticket adds the request of making augur export exit on name collisions.

[rneher]

treetime uses numdate internally. The parsing of dates from user generated tables is a constant head-ache. I think the main reason we prefer floating point dates over other date spec is that they are unambiguous to parse.

[huddlej]

Revisiting this issue after the augur v6 updates to how auspice JSONs are exported and the original issue with conflicting key names in metadata and node JSONs remains.

The current implementation for merging metadata and node JSONs for augur v2 export explicitly overwrites the keys in the metadata. This can result in silently overwriting data that the user would expect to pass through to the final auspice JSONs.

Instead of overwriting overlapping keys, parse_node_data_and_metadata should raise an exception and the augur export v2 subcommand should catch that exception and print the exception message to standard error. This will alert the user to the conflict and allow them to resolve it explicitly.

[jstoja]

@huddlej Do I understand well that node_data shouldn't overwrite metadata keys?
From the tests (for example tb), it seems that node_data is more precise than metadata for the date field.

Raising an exception here means that the the export will fail since the function won't return. Maybe just printing a warning in the parse function will be enough?