Add tutorial #99
Add tutorial #99
Conversation
Installed a library that should allow us to execute Node.js code with it. Even if a Python Notebook is not the best way to store a tutorial (and I think it might be), this will allow me to organize my thoughts and the code-output format will be useful in recording what users should do and what the result is.
There was a problem hiding this comment.
Nice start. My major comment here is that I think demonstrating the use of the JSON package, which would include using JavaScript to navigate a Phyx file as a JSON file, is out of scope. (And part of the motivation for phyx.js is that people don't have to do that, isn't it?)
So I think that part should be mostly cut, save perhaps for a few (1-2) things (such as specifiers?) to demonstrate the added value phyx.js brings to inspecting the content of a Phyx file.
Second, the issue description (which BTW does IMO give the correct scope) says how to read a Phyx file, check it for validity, examine phyloreferences, phylogenies and specifiers, and describe how to convert the file into RDF. I do agree with that description, but I'm not sure each of these points is fully reflected in the tutorial. It's certainly not structured like this, and it's not clear why not, or what is gained by using a different structure.
As a more minor comment, consider for every place a variable includes the wrapped prefix, whether the fact that it's an instance of a wrapping class is important to carry through for the tutorial reader, or whether that's most motivated by you avoiding name clashes, i.e., needing to distinguish by name between the object passed in and the wrapped object instantiated from it. For example, isn't conceptually a wrappedPhyloref simply a phyloreference object, and a wrappedSpecifier simply a specifier object? For a tutorial, one that reads quicker due to fewer letters to discern is better.
Good point! Done in d80b0ef.
After a few changes, I've ended up with the following structure:
I think this works well, and is pretty good to the originally proposed order. What do you think?
True, but in this case the distinction is important since most of the wrapped objects don't entirely wrap the entire object, mainly to avoid writing a lot of boilerplate code: for example, PhylogenyWrapper doesn't reveal the underlying Newick string, since accessing it via Does that make sense? I could add a shorter version of the previous paragraph to the "Examining phyloreferences, taxonomic units and taxon concepts" section if it would help, but I think it might be too much detail for this tutorial. Alternatively, I could actually add the necessary boilerplate code to make all this work if that would be better (i.e. add a getter so that |
|
Based on our phone conversation, I'll delete the sections "Navigating a Phyx document as a JSON file" and "Validating a Phyx document using JSON Schema", which aren't directly relevant to a phyx.js tutorial. We should move the "Validating a Phyx document using JSON Schema" into the README file. Add some text to be a bit clearer on what the wrappers can do and cannot do, and then focus just on what the wrappers do (which is what the later sections do). (Add a section at the end to say "Here's all the nice, useful things we can do with phyx.jx ... and here are some other things that you can't do (there are many data and attributes not accessible through phyx.js), but that's because it's pretty accessible directly in JSON"). |
|
@hlapp Here's an updated version of the tutorial as per our conversation from last week. Let me know what you think! |
|
One thing I forgot is to add date and author under the title. |
A long term fix for this will be covered by #101.
This PR adds an "Introduction to phyx.js" tutorial that describes how the library is intended to be used. Since phyx.js doesn't have a standard workflow, I instead wrote this tutorial to look at how Phyx documents can be accessed as JSON documents, how phyx.js wrappers can help access parts of those documents, and how it can be used to convert the whole document into an OWL document.
I could write additional tutorial steps demonstrating how to use PhylogenyWrapper to recurse through all the nodes in a phylogeny, or PhylorefWrapper to calculate the default nomenclatural code for a phyloreference, but I suspect that's too in-the-weeds for what is intended to be a broad introduction.
I wrote the tutorial in Jupyter Notebook running an IJavascript kernel. The Jupyter Notebook itself is included in this PR, but since GitHub's rendering of this notebook sometimes fails unexpected, I think we should point people to the Markdown version of this file instead. This PR will also include this tutorial in the phyx.js documentation website at https://www.phyloref.org/phyx.js/manual/index.html.
Closes #98.