Examples

[kgd-al]

Part of the ongoing joss review (https://github.com/openjournals/joss-reviews/issues/4866)

I have a few remarks stemming from the provided example so I address them all here:

1. example/basics.py

The example provided in the description could be a standalone file (in a dedicated folder) to facilitate forking.

2. Non interactive print

In the same line as #50, it would be better for the common ancestry tests to use print as well:

print(hstrat.does_have_any_common_ancestor(individual1, individual2)) # -> False
print(hstrat.does_have_any_common_ancestor(individual1_child1, individual2)) # -> False

3. True case(s?)

Adding a True case would also help with understanding

print(hstrat.does_have_any_common_ancestor(individual1_child1, individual1)) # -> True

4.

What are your thoughts on a human-friendly way to see the contents of the stratum (.e.g __repr__ or a ToString)?

5.

May be provide a practical example:

class Genome:
  def __init__(self):
    self._data = 0
    self._stratum = hstrat...

 def mutate(self):
   self._data += 1
   self._stratum ???

 ....

a = Genome()
b = Genome()
for i in range(100):
  a.mutate()
  b.mutate()

# do something fascinating (may be with a graph?)

So that users can see at a glance how to include your library in their code and how to make something of it fast.

[mmore500]

I like the idea of putting examples in an examples folder. This will also make it easier to make sure they stay up to date over time (because we can run the examples as part of CI). Working on this now!

[mmore500]

Just merged #64 into the master branch. It updates the example in the README to be a little simpler and have True cases. The bigger change is creating a new examples/ folder with some of the more practical examples you suggested.

Let me know your thoughts on the changes to the examples and if you have any ideas for further improvements.

I think adding a nice way to print out a column and a stratum could be useful and make for a good additional example where it just shows the state of a column over a few generations step-by-step. Will update you when I get that together.

Thank you for the suggestions! I think this will be a big improvement to the usability of the library.

[kgd-al]

I have reviewed #64 and it addresses all of my above remarks, except 4. What are your thoughts on that? If I want a quick and dirty look at the column or serialize it to my custom format, what is the entry point?

[mmore500]

Implemented hstrat.col_to_ascii to create a pretty-print representation of the internal state of a column. To support this, I also implemented hstrat.col_to_dataframe which creates a pandas DataFrame representation of a hstrat column.

Put together a little demo of hstrat.col_to_ascii in examples/ascii_stratum_retention_viz.py.

Let me know your thoughts on these improvements.

Apologies for the delayed response! Agreed that this will be a useful tool to peek at what's going on under the hood (and especially to help new users get acquainted).

[kgd-al]

Great! It might not be crucial for everyone but, as my first reaction was 'how to print it?' followed by 'Well let's dig in the code and expose all those private members', it should help all of us print-maniacs.