Expose keep_unary_in_individuals functionality to Python

[hyanwong]

#1119 enables the C API to pass a TSK_KEEP_UNARY_IN_INDIVIDUALS option flag to tsk_treeseq_simplify. We should also expose this to the Python API by adding a keep_unary_in_individuals=False parameter to ts.simplify() and tc.simplify().

[jeromekelleher]

We could also explore having keep_unary take an enumeration as well as a bool, like you initially suggested. But, we should think about what other situations we might want to keep unary (or what other subset of them we might want to keep) before doing this. (Which is why I didn't suggest pushing ahead with the Python level change in #1119)

[petrelharp]

Seems like we need this: #1154 - I'll put in a simple boolean flag (easiest) to aid in debugging; we can adjust as needed. I like the idea of having keep_unary=(True|False|"individuals"), though - seems appropriate, given that keep_unary_individuals should give a strict subset of keep_unary, and extensible.

[hyanwong]

To follow up on @jeromekelleher 's request for thoughts, I expect that people might want to keep unary node when (a) they are recombination nodes, in a full ARG.(b) when it is migration node or (c) when it is a census node. In fact, the list at https://msprime.readthedocs.io/en/stable/api.html#node-flags probably covers the extra cases.

However

1. These are msprime-specific node types, and it's arguable whether tskit should know about them (although there is an argument to be made for allowing tskit to describe recombinations and census event natively, I guess)
2. various combinations of these might be required by the user: e.g. "keep recombination nodes and migration nodes but not census nodes", etc.

So here's a suggestion: can we allow the user to provide a bit mask which, when ANDed against the node flag, specifies which type of unary nodes are kept? That way it can work with non-tskit flags (like msprime.NODE_IS_RE_EVENT) without explicit coding. The only problem then is how to make this compatible with the keep_unary_in_individuals option.

[petrelharp]

So here's a suggestion: can we allow the user to provide a bit mask which, when ANDed against the node flag, specifies which type of unary nodes are kept? That way it can work with non-tskit flags (like msprime.NODE_IS_RE_EVENT) without explicit coding. The only problem then is how to make this compatible with the keep_unary_in_individuals option.

That's a nice idea. I think that'd just have to be a different option, though - don't see how to put it in to the same argument. (besides, what if you wanted to keep RE_EVENT nodes and individuals... ??)

[jeromekelleher]

Yes, I think this is a separate feature, which we don't have any immediate use for.

[hyanwong]

Yes, I think this is a separate feature, which we don't have any immediate use for.

Yes, I agree. It's not for immediate implementation. I'm just replying to your comment above about "we should think about what other situations we might want to keep unary (or what other subset of them we might want to keep) before doing this".