Including field metadata to studio tree

[matthew-blackman]

We would like to make sure that fields look as expected in the studio tree. Although individual projectiles are not stateful, we want see what additional metadata should be included in the tree.

Preliminary ideas:

1. Total number of landed projectiles
2. Mean landing distance
3. SD of landing distance

[samreid]

This may not be something valuable for the tree itself (through a new instrumented Property instance), but rather something to be added to the examples.md with a line of code for each.

[matthew-blackman]

@samreid and I discussed this, and agree that field information presented on each individual screen should be instrumented for that screen. This includes:

• Number of landed projectiles on VSM screens
• Mean and standard deviation on Measures screen
• Number of completed samples on Sampling screen

As far as allowing designers to access field metadata on screens where it is not instrumented, @samreid and I had success using the following command to get the mean distance of projectiles on a field:
_.mean((await phetioClient.invokeAsync('phetioEngine', 'getPhetioElementState', ['projectileDataLab.variabilityScreen.model.fields.field1'] )).landedProjectiles.map(p=>p.x))

We feel that this is a good balance of usability and flexibility for PhET-IO customization, and that there is precedent in Center and Variability. Let's create examples in examples.md that can give instructional designers the ability to query data measures on any screen, but instrument the data measures that are relevant to each screen's learning goals.

[samreid]

I committed an initial draft for "Number of landed projectiles on VSM screens" and wanted to check in about several of the details before applying this pattern elsewhere.

• I instrumented the outer DynamicProperty on the model as well as the inner one on the Field so the client could get either.
• I marked them as phetioFeatured: true since they seem important
• I marked them as phetioReadOnly: true since they are derived from the inner workings of the simulation
• I marked them as phetioState: false since they should be computed from the state of the projectiles and not stored in a redundant way that could get out of sync. However, this means clients will be able to see the value in studio and get the value from a phetioClient 'getValue' command, but not get the state then look up the entry in the state. However, the client could run a computation like the one above on the state. An alternative would be to invent a new "one way street" so that these values can be written into the state but not restored from the state (like DerivedProperty instances do).

@matthew-blackman can you please review and comment on these aspects before I apply the pattern elsewhere?

[matthew-blackman]

@samreid and I discussed this, and agreed that we can hold off putting field metadata into the simulation state, and add it later if a client requests it. If a client wants to listen to or access field metadata, they can do so at runtime by using the instrumented properties in studio.

However, a more complex implementation would require using state with the PhET-IO API. For example, they could access the total number of landed projectiles on a field with await phetioClient.invokeAsync('phetioEngine', 'getPhetioElementState', ['projectileDataLab.variabilityScreen.model.fields.field1'] ).landedProjectiles.length

Let's instrument the field metadata in studio with properties, but keeping them as readonly in the state is sufficient. We will also add to the examples.md file to show how field metadata can be accessed through state with the PhET-IO API.

[samreid]

I finished implementing what was requested. This issue is ready for review.

As I worked on this, I did not have a good feeling about the value vs complexity tradeoff. For instance, the last 2 commits added 34 lines of code and added 28 new instrumented PhET-iO elements. These are elements that will take up weight in the tree, in the API files and will introduce additional burden for migration rules in PhET-iO. This seems like a lot of unnecessary cost for something that is also redundant and that we do not have a clear vision for why a client would want to use those in a wrapper or in studio.

[matthew-blackman]

It's nice to have these dynamic properties exposed on the Measures screen, since that is where we can visually display the Mean, SD and SE. Reviewed the tree as part of #30 and all looks great here. Nice work! Closing.