notes on PhET-iO instrumentation

[pixelzoom]

Function Builder was not instrumented for PhET-iO when initially developed, and (due to deadlines) little thought was given to instrumentation.

In this issue, I'll describe potential pitfalls with instrumentation, things that will need to be added/changed, pointers to things that might be useful, etc. Hopefully this will benefit whoever does the instrumentation.

[pixelzoom]

Identifying cards:
There is currently no way to identify or describe the cards in the Patterns screen (e.g. "butterfly card 1"). The base type (ImageCard) is given an HTMLImageElement that is loaded by the image plug-in, and doesn't know (or care) about the semantics of the image, since that knowledge is not required for image processing. So we'll need to add a name to each ImageCard. And since >1 instance of each card is created, we'll also need to add an index.

We'll also want to consider whether (e.g.) "butterfly card 1" or "butterfly card 2" is on top of the stack in the input carousel when the sim starts. And should the cards be numbered starting from 0 or 1?

In all screens except Patterns, there is currently only 1 instance of each card. But to make the sim "future proof", we should still include the index in the data stream for these cards.

[pixelzoom]

Equations:
SlopeInterceptEquation.toString and HelpfulEquation.toString can be used to provide a text-based representation of what the user is seeing (as rendered by SlopeInterceptEquationNode and HelpfulEquationNode respectively). It's typically unadvisable to rely on the format of any toString function, so we may want to change the names of these, and/or update their documentation.

Also worth noting is that, in both equations, a forward slash ('/') is used to denoted a fraction divisor line. And square brackets are used in HelpfulEquation to denote a term that appears in the numerator or denominator without surrounding parenthesis being displayed to the user.

For example, '[x + 3]/2 is rendered as:

This is also mentioned in equation-formats.md.

[pixelzoom]

Identifying functions:
To identify functions (in all screens), we'll need to add an index, so that we can identify (e.g.) "Warhol 1" or "Rotate90 2". We'll also want to consider whether (e.g.) "Warhol 1" or "Warhol 2" is on top of the stack in the function carousel when the sim starts. And should the cards be numbered starting from 0 or 1?

[pixelzoom]

Mystery screen functions:
In the Mystery screen, functions are reused from an invisible function carousel, as described in implementation-notes.md. There are currently N instances of each function type in the carousel, where N is the number of slots in the builder. If the data stream identifies them by index as suggested in #98 (comment), then the index isn't of any real interest. That's something that whoever is processing the data stream should be aware of.

[pixelzoom]

Location of objects for dragging and animation:
This sim supports multi-touch with no exclusions or limitations. It's possible to have many cards and functions being dragged and/or animating simultaneously. This can result in a huge amount of location data being streamed and interleaved. Not something that needs to be necessarily addressed in the implementation, but whoever is processing the data stream should be aware of this.

[pixelzoom]

Identifying challenges in the Mystery screen:
Mystery challenges are specified using a simple string format, as shown in MysteryChallenges.js. For example '+ 2 * 1 + 2'. This format makes it easy to read and modify challenges in the code. After a challenge is selected, MysteryChallenges.parseChallenge converts the string format to an array of objects. For the data stream, it might be appropriate to use the string format, prior to calling parseChallenge.

[pixelzoom]

Use consistent terminology:
When naming things in the data stream (tandems, units, etc.), it's highly recommended to use the same terminology that is used in the source code, as documented in implementation-notes.md. Anyone who is processing the data stream would do well to read implementation-notes.md.