Saturday, May 30, 2020

Special Events Annotations

A common question asked when analyzing a completed roast profile is "what was the time and bean temperature when that gas change was made?"  To help answer this and similar questions, Artisan v2.4 introduces customizable, data driven special event annotations.  Special event annotations add detailed information in text format to the special event lines.  These annotations speed interpretation of a profile in post roast analysis by writing out the pertinent information directly on the graph. The user has broad flexibility when defining the text and data to be displayed.  This allows bespoke annotations that meet the user's individual needs.

For additional information about events please refer to Events, Buttons and Palettes, Event Quantifiers and the Artisan Quick Start Guide.

Adjusting the Position of Special Events Lines on the Graph

Here is a typical roast showing Power and Damper settings in the special event lines in the lower portion of the graph.  Before getting into how to annotate these special event lines, let's make a few adjustments so the special event lines do not overlap with the bean temperature curve.

To do this open the Axes window.  From the menu choose Config>> Axes.

For this example we change the Temperature Axis Min value to 50.  Next we fill the 100% Event Step field with 160.  This field is a new setting in Artisan.  It sets the temperature on the Y-axis that corresponds to a step value of 100.  By setting 100% Event Step to 160 we lower the special event lines below the bottom of the bean temperature (BT) curve.  Here is the result.

You may need to experiment to find the best 100% Event Step setting for your profiles.  The right value depends on your axis settings, TP temperature and your tolerance for having these elements overlap.

Custom Special Events Annotations

From the menu go to Config>> Events to open the Events configuration window

On the Config tab are displayed the four special Event Types.  In this case they were given the names Power, Damper, None and Sensory.  Only Power and Damper are selected, so these are the only two that are displayed in the graph.

Step is chosen in the Markers selection.  This selection determines how the special events will be displayed.  The special event annotations are displayed when the selection is Step or Step+.  For more information on how special events are displayed using the other selections see the Artisan Quick Start Guide.

Snap is unchecked.  Checking Snap would cause the zero value of the step lines to align to zero on the Y-axis.  When Snap is unchecked the zero step value is aligned at the bottom of the graph.  For this example we leave Snap unchecked.

Next, select the Annotations tab.

On the left hand side are the four special event types with the names they were given on the Config tab.  We can create annotations by filling in the edit boxes and checking Show to display them.  Examples of the annotations strings will be shown on the right.  Be aware that the data used in the examples in this window is static and is not taken from your profile. The Help button will display a help window with a complete list of the fields available for use in the annotations and notes on usage.

Let's create a simple annotation.  All fields that will be substituted for data values begin with a tilde character '~' (without the quotes).  The value of the present event is entered as '~E'.  The text 'Power ' lets us know what the value means.  The space character in between keeps a readable separation.  The example area shows 'Power 50'.

Power ~E

How does it look in the graph?

Let's add some additional useful information to the annotation.  We will show the bean temperature and the time when the adjustment took place.

Power ~E @ ~Y2~degmode ~dCHARGE sec

'~Y2' is substituted with the bean temperature, '~degmode' displays the degree symbol and either C or F depending on the units in use by the graph, and '~dCHARGE' is the number of seconds from CHARGE.  That's a lot of information!

More Complex Special Events Annotations

There is a more useful way to show time than just seconds from CHARGE.  What if we showed the time only when we are nearing FCs and show it as the number of seconds before FCs?  What if after FCs we showed the Development Time Ratio instead of time?  Both are possible!

To do this we need to add some characters that tell Artisan what to show when.  The first is a single quote mark.  Whatever is enclosed in a pair of single quotes ' will show only before FCs.  Anything between a pair of double quotes " will show only after FCs.  And one more, anything between back ticks ` will show only within 90 seconds before FCs.  That is a lot to take in, so to best understand how this works please experiment with the examples given in the Event Annotations Help. 

Power ~E% '@~Y2 ~degmode`, ~preFCs sec before FCs`'"@~DTR% DTR"
Damper ~E% '`FCs ~preFCs sec`'"@~DTR % DTR" 

The Damper now also has an annotation.  The data is recorded as % from 0-100.  Power is also recorded as a percent and indicated as such in this graph.


Special Events Annotations in the Background Profile

Special Event Annotations are not shown on the background profile when a foreground profile is displayed.  However they are shown on the background when Roast >> Background >> Annotations is checked and there is no foreground profile.  They are also displayed  during roasting and when Roast >> Background >> Annotations is checked.

Even More Advanced Annotations

Perhaps your Power setting is recorded as % as shown in the examples above, but you would like to display the Gas setting in kPa.  Assume that full gas for this roaster is 3.5kPa.  That means 100% is the same as 3.5kPa, 50% is 1.75kPa, and so forth.   That means to percent Power can be converted to kPa Gas by multiplying the Power value stored in the profile by 0.035.

The special events annotations allow for simple arithmetic operations.  A single multiply, divide, add or subtract operation can be executed on the special event value.  This example shows multiplying the recorded special event value by 0.035.

Gas ~E*0.035 kPa '@~Y2 ~degmode` ,~preFCs sec before FCs`'"@~DTR% DTR"
Damper ~E%  '`FCs ~preFCs sec`'"@~DTR % DTR"


When Annotations Overlap

Sometimes the change in value of a special event is small and causes the annotation text to overlap.  This can also happen when two different events are close in value and time.  An extreme example can be seen below.

To remedy this, change the Allowed Annotation Overlap to a lower value.  The default value is 100%.  In this example the value is reduced to 20%.

Some of the annotations will be hidden so that the others are readable.

There are many more fields available than described here and still more ways to use them.  Please refer to the Events Annotation Help page or the Artisan Quick Start Guide for additional information.