This page last changed on Sep 10, 2007 by scytacki.

In the Graph, Data, and DataGraph projects, there is a need to display the values of data. To make these displays as easy to read as possible for different levels of users, the display needs to support a lot of customization.

Java does not provide adequate number printing libraries to make this easy.

FIXME: Here is a bad example, please replace it with one that is more advanced.

For example, the number 1000 when rendered as a float in Java's Float.toString() method returns "1000.0"
You might want it to make the string look like 1000.

There are at least 2 kinds of configuration that displayed data values need to have.

There is the actual precision of the value being displayed. Many of the values displayed come from measurements. And measurements have an error range. One way to represent this in something like: 1001.12 +/- 0.05. This has 2 parts the signicant figures in the actual value, and the range of the error.
In the past we have not shown the range of error to the students. We also currently do not keep track of actual error range instead we keep track of something called precision. This is used in the code as well as in the otml configurations of data stores and data producers. This "precision" is the basically the log10 of the error range rounded to the next largest integer. So in the example above it would be "-1".

The other kind of customization is the number of decimal places to show. For example if you are measuring a plant you might have measured 2.2 centimeters, but you only want to show a 3 grader the following string: "it grew about 2 centimeters".

Another kind of customization is dealing with exponents. In some cases at a certain point the value being displayed should use a form of scientific notation. So the 1000 above would be shown as: "1.0 E3". Sometimes that is necessary to save screen space. In the case of saving screen space it is useful display the value in regular decimal notation as long as possible and then switch to scientific notation when the number gets too big of small.
Using exponenential notation is also necessary when working with units. Many common units have modifiers which jump up or down by 10^3. So once the value gets larger or smaller than 10^3 the unit should change. For example meters and kilometers or grams and kilograms

Currently the code for doing parts of this is scattered around. Here is a list of places where it can be found:

  • org.concord.graph.ui.SingleAxisGrid
    has code for display different number of decimal places and switching to exponential notation if the number is greater than 10^3 or less than 10^-3.
  • org.concord.graph.engine.MathUtil
    has code to return a rounded string of a float value. The rounding is customized by a number of max decimal places. It uses DecimalFormat to format the string.
    setValue() - uses precision to round the float to that precision, it uses Float.toString() to print the value
    setValue() - uses precision to round the float to that precision, it uses Float.toString() to print the value
  • org.concord.datagraph.ui.DataPointLabel
    updateDataPointLabels() - uses NumberFormat with precision to round the string form of the values.
  • org.concord.datagraph.ui.DashedDataLine
    draw() - uses NumberFormat with precision to round the string with the precision
    getValueAt() - uses precision to round the float to that precision, it uses Float.toString() to print the value. Note: the meaning of precision in the data table might be different. 2 means 2 decimal places should be shown.

The DataChannelDescription class stores a precision as an integer, and it also has a flag that specifies if this precision should be used or not. It is not clear though what is the exact meaning of "precision". Some components treat it as "number of decimals that should be shown in screen" (like the data table).

We should have a central place that does this and encourage people to always use the same functions instead of keep writing their own. We should also make very clear the definition of precision and other terms that might not be very well defined or understood in the framework.
Note: What about other projects that also use these terms? For example, RTT uses functions in MathUtil, and MW might have its own.

Document generated by Confluence on Jan 27, 2014 16:52