tskit-dev
Document example code for how to create an inverted node map
When returning a node map from simplify(), I often find I need the inverted map (from new node ID to old), and have to remember every time the best way to do this (e.g should I just use a dict, or a numpy method). It would perhaps be useful to add a one-liner to the simplify docs to say how to get the reverse map in this case?
Sounds like a good thing to have in an examples section in the docs. I think a page "Analysis/simplifcation" with useful worked examples, which are linked to from the docstring, is entirely warranted.
I think maybe a whole page for all examples, with sections for analysis, simplification, etc. might be more flexible? Then we could dump e.g. miscellaneous examples in their own category at the end of the page.
Maybe - but some pages (export) are already built around example based structure, and others (stats, topology) would benefit from doing so. If we just have one big examples bucket that we toss everything into content will get lost and we'll be back to trying to find some logical structure later.
Adding a "simplification" page would allow us to make progress on the immediately identified problem and let us add some useful content. There is the grey line then between that content and the simplification tutorial. I don't know where that line would be drawn, other than the tskit "simplification" page would not need an overall narrative, and can simply be disconnected sections that can be referred to (a-la the msprime docs)
I suggested a page of examples not just because I think some might not fall into obvious categories, but also because I'm worried that a whole page on simplification will require us to structure some sort of narrative at the top (like we have in the stats page), rather than just dump examples in there and link to them from the docstrings. But maybe we make the pages first and see what they look like?
Are there pieces of example code that would be difficult to "home". Where would you e.g. suggest putting the map_mutations code that I recently added to that docstring? Does it come under "topological analysis", for example?
I'm worried that a whole page on simplification will require us to structure some sort of narrative at the top (like we have in the stats page),
Case in point: the "export" page is very narrative driven, I feel. I'm not super keen on writing that sort of narrative for a simplification page on the main docs site. That seems like the role of the simplification tutorial instead.
There's no narrative going through the export page I would have thought - there's a few bits where we refer back to previous sections, but nothing linking things together.
If we make a "simplification" page that just consists of a few disconnected fragments then we may have to refactor that later. If we make an "examples" page then we'll definitely have to refactor it later. The intro can literally be "simplifification is powerful. See the tutorial for more information on what it does. Here's some examples of specific things you might like to do."
Or we could add a simplification section to some other page where we put examples. We do need to improve the tskit documentation, and this will largely consist of going through the existing docs and making it more example driven using jupyter-book. Making a separate "examples" page is a backwards step because it'll prevent examples getting added to where they should go (since it's easier the just dump an example in there than to think about where it should go in the overall doc structure).