ssscoring.notebook

  1# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
  2
  3"""
  4## Utility reusable code for notebooks.
  5"""
  6
  7
  8from ssscoring.constants import DEFAULT_SPEED_ACCURACY_SCALE
  9from ssscoring.constants import MAX_ALTITUDE_FT
 10from ssscoring.constants import SPEED_ACCURACY_THRESHOLD
 11from ssscoring.datatypes import PerformanceWindow
 12
 13import bokeh.io as bi
 14import bokeh.models as bm
 15import bokeh.plotting as bp
 16import pandas as pd
 17
 18
 19# *** constants ***
 20
 21DEFAULT_AXIS_COLOR_BOKEH = 'lightsteelblue'
 22"""
 23CSS color name for the axis colors used in notebooks and Streamlit
 24with Bokeh.
 25"""
 26
 27
 28SPEED_COLORS = colors = ('limegreen', 'blue', 'tomato', 'turquoise', 'deepskyblue', 'forestgreen', 'coral', 'darkcyan',)
 29"""
 30Colors used for tracking the lines in a multi-jump plot, so that each track is
 31associated with a different color and easier to visualize.  8 distinct colors,
 32corresponding to each jump in a competition.
 33"""
 34
 35
 36# *** global initialization ***
 37
 38# bp.output_notebook(hide_banner = True)
 39bp.output_file('/dev/null', mode='inline')
 40# TODO: make this configurable:
 41bi.curdoc().theme = 'dark_minimal'
 42
 43
 44# *** functions ***
 45
 46def initializePlot(jumpTitle: str,
 47                   height=500,
 48                   width=900,
 49                   xLabel='seconds from exit',
 50                   yLabel='km/h',
 51                   xMax=35.0,
 52                   yMax=550.0,
 53                   backgroundColorName='#1a1a1a',
 54                   colorName=DEFAULT_AXIS_COLOR_BOKEH):
 55    """
 56    Initiialize a plotting area for notebook output.
 57
 58    Arguments
 59    ---------
 60        jumpTitle: str
 61    A title to identify the plot.
 62
 63        height: int
 64    Height of the plot in pixels.  Default = 500.
 65
 66        width: int
 67    Width of the plot in pixels.  Default = 900.
 68
 69        xLabel: str
 70    X axis label.  Default:  `'seconds from exit'`
 71
 72        yLabel: str
 73    Y axis label.  Default:  `'km/h'`
 74
 75        xMax: float
 76    The maximum rnage for the X axis.  Default = 40.0
 77
 78        yMax: float
 79    The maximum range for the Y axis.  Default = 550
 80
 81        backgroundColorName
 82    A string with the CSS RGB value of the background color or its CSS color
 83    string name.
 84
 85        colorName
 86    A valid CSS color string.
 87    """
 88    bi.curdoc().theme = 'dark_minimal'
 89    plot = bp.figure(title=jumpTitle,
 90                     height=height,
 91                     width=width,
 92                     x_axis_label=xLabel,
 93                     y_axis_label=yLabel,
 94                     x_range=(0.0, xMax),
 95                     y_range=(0.0, yMax),
 96                     background_fill_color=backgroundColorName,
 97                     border_fill_color=backgroundColorName)
 98    plot.xaxis.axis_label_text_color=colorName
 99    plot.xaxis.major_label_text_color=colorName
100    plot.xaxis.axis_line_color=colorName
101    plot.xaxis.major_tick_line_color=colorName
102    plot.xaxis.minor_tick_line_color=colorName
103    plot.yaxis.axis_label_text_color=colorName
104    plot.yaxis.major_label_text_color=colorName
105    plot.yaxis.axis_line_color=colorName
106    plot.yaxis.major_tick_line_color=colorName
107    plot.yaxis.minor_tick_line_color=colorName
108    plot.title.text_color = colorName
109    return plot
110
111
112def _graphSegment(plot,
113                  x0=0.0,
114                  y0=0.0,
115                  x1=0.0,
116                  y1=0.0,
117                  lineWidth=1,
118                  color='black'):
119    plot.segment(x0=[ x0, ],
120                 y0=[ y0, ],
121                 x1=[ x1, ],
122                 y1=[ y1, ],
123                 line_width=lineWidth,
124                 color=color)
125
126
127def _initLinearAxis(label: str,
128                    rangeName: str,
129                    colorName: str=DEFAULT_AXIS_COLOR_BOKEH) -> bm.LinearAxis:
130    """
131    Make a linear initialized to use standard colors with Bokeh plots.
132
133    Arguments
134    ---------
135
136        label: str
137    The axis label, text string.
138
139        rangeName
140    The range name, often used for specifying the measurment units.
141
142        colorName
143    A valid CSS color string.
144
145    Return
146    ------
147    An instance of `bokeh.models.LinearAxis`.
148    """
149    linearAxis = bm.LinearAxis(
150            axis_label = label,
151            axis_label_text_color = colorName,
152            axis_line_color = colorName,
153            major_label_text_color = colorName,
154            major_tick_line_color=colorName,
155            minor_tick_line_color=colorName,
156            y_range_name = rangeName,
157    )
158    return linearAxis
159
160
161def initializeExtraYRanges(plot,
162                           startY: float = 0.0,
163                           endY: float = MAX_ALTITUDE_FT,
164                           maxSpeedAccuracy: float | None = None):
165    """
166    Initialize an extra Y range for reporting other data trend (e.g. altitude)
167    in the plot.
168
169    Arguments
170    ---------
171        plot
172    A valid instance of `bp.figure` with an existing plot defined for it
173
174        startY: float
175    The Y range starting value
176
177        endY: float
178    The Y range ending value
179
180        maxSpeedAccuracy: float
181    Maximum speed accuracy value to determine the range of the speed accuracy axis.
182    If None or < SPEED_ACCURACY_THRESHOLD, range is 0-10. Otherwise, range is 0-maxSpeedAccuracy*1.1
183
184    Returns
185    -------
186    An instance of `bp.figure` updated to report an additional Y axis.
187    """
188    speedAccuracyEnd = DEFAULT_SPEED_ACCURACY_SCALE
189    if maxSpeedAccuracy is not None and maxSpeedAccuracy >= SPEED_ACCURACY_THRESHOLD:
190        speedAccuracyEnd = maxSpeedAccuracy * 1.1
191    plot.extra_y_ranges = {
192        'altitudeFt': bm.Range1d(start = startY, end = endY),
193        'angle': bm.Range1d(start = 0.0, end = 90.0),
194        'speedAccuracy': bm.Range1d(start = 0.0, end = speedAccuracyEnd),
195    }
196    plot.add_layout(_initLinearAxis('Alt (ft)', 'altitudeFt', colorName=DEFAULT_AXIS_COLOR_BOKEH), 'left')
197    plot.add_layout(_initLinearAxis('angle', 'angle', colorName=DEFAULT_AXIS_COLOR_BOKEH), 'left')
198    plot.add_layout(_initLinearAxis('Speed accuracy ISC', 'speedAccuracy', colorName=DEFAULT_AXIS_COLOR_BOKEH), 'left')
199    return plot
200
201
202def validationWindowDataFrom(data: pd.DataFrame, window: PerformanceWindow) -> bm.ColumnDataSource:
203    """
204    Generate the validation window dataset for plotting the ISC speed accuracy
205    values.  It's a subset defined from the end of the scoring window to the
206    validation start.
207
208    Arguments
209    ---------
210        data
211    A dataframe with the `plotTime` column set, with all the jump data, after
212    speed validation processing.
213
214        window
215    A `ssscoring.datatypes.PerformanceWindow` instance, with the `validationStart`
216    value initialized.
217
218    Returns
219    -------
220    A column data source ready for plotting the Y-values of a Bokeh chart.
221    """
222    validationData = data[data.altitudeAGL <= window.validationStart]
223    return bm.ColumnDataSource({ 'x': validationData.plotTime, 'y': validationData.speedAccuracyISC, })
224
225
226def _plotSpeedAccuracy(plot, data, window):
227    accuracyDataSource = validationWindowDataFrom(data, window)
228    plot.line('x', 'y', y_range_name='speedAccuracy', legend_label='Speed accuracy ISC', line_width=5.0, line_color='lime', source=accuracyDataSource)
229
230    validationData = data[data.altitudeAGL <= window.validationStart]
231    plot.line(x = validationData.plotTime, y = pd.Series([ SPEED_ACCURACY_THRESHOLD, ]*len(validationData)), y_range_name='speedAccuracy', line_dash='dashed', line_color='lime', line_width=1.0)
232
233
234def graphJumpResult(plot,
235                    jumpResult,
236                    lineColor = 'green',
237                    legend = 'speed',
238                    showIt = True,
239                    showAccuracy = True):
240    """
241    Graph the jump results using the initialized plot.
242
243    Arguments
244    ---------
245        plot: bp.figure
246    A Bokeh figure where to render the plot.
247
248        jumpResult: ssscoring.JumpResults
249    A jump results named tuple with score, max speed, scores, data, etc.
250
251        lineColor: str
252    A valid color from the Bokeh palette:  https://docs.bokeh.org/en/2.1.1/docs/reference/colors.html
253    This module defines 8 colors for rendering a competition's results.  See:
254    `ssscoring.notebook.SPEED_COLORS` for the list.
255
256        legend: str
257    A title for the plot.
258
259        showIt: bool
260    A boolean flag for whether the call should render the max speed, time,
261    horizontal speed, etc. in the current plot.  This is used for discriminating
262    between single jump plots and plotting only the speed for the aggregate
263    plot display for a competition or training session.
264
265    To display the actual plot, use `bp.show(plot)` if running from Lucyfer/Jupyter
266    or use `st.bokeh_chart(plot)` if in the Streamlit environment.
267
268    ```python
269    # Basic usage showing speed accuracy overlay
270    graphJumpResult(plot, result)
271    bp.show(plot)
272
273    # Multiple jumps without speed accuracy overlay
274    for result in jumpResults:
275        graphJumpResult(plot, result, showIt=False, showAccuracy=False)
276    bp.show(plot)
277    ```
278    Another alternative use is in Streamlit.io applications:
279
280    ```python
281    # Streamlit app with speed accuracy overlay
282    graphJumpResult(plot, result, showIt=False)
283    st.bokeh_chart(plot, use_container_width=True)
284    ```
285
286    Returns
287    -------
288    `None`.
289    """
290    data = jumpResult.data
291    scores = jumpResult.scores
292    score = jumpResult.score
293    # Main speed line
294    plot.line(data.plotTime, data.vKMh, legend_label = legend, line_width = 2, line_color = lineColor)
295
296    if showIt:
297        plot.line(data.plotTime, data.hKMh, legend_label = 'H-speed', line_width = 2, line_color = 'red')
298        _plotSpeedAccuracy(plot, data, jumpResult.window)
299        _graphSegment(plot, scores[score], 0.0, scores[score], score, 3, 'lightblue')
300        _graphSegment(plot, scores[score]+1.5, 0.0, scores[score]+1.5, score, 1, 'darkseagreen')
301        _graphSegment(plot, scores[score]-1.5, 0.0, scores[score]-1.5, score, 1, 'darkseagreen')
302        plot.scatter(x = [ scores[score], ], y = [ score, ], marker = 'square_cross', size = [ 20, ], line_color = 'lightblue', fill_color = None, line_width = 3)
303
304
305def graphAltitude(plot,
306                  jumpResult,
307                  label = 'Alt (ft)',
308                  lineColor = 'palegoldenrod',
309                  rangeName = 'altitudeFt'):
310    """
311    Graph a vertical axis with additional data, often used for altitude in ft
312    ASL.
313
314    Arguments
315    ---------
316        plot: pb.figure
317    A Bokeh figure where to render the plot.
318
319        jumpResult: ssscoring.JumpResults
320    A jump results named tuple with score, max speed, scores, data, etc.
321
322        label: str
323    The legend label for the new Y axis.
324
325        lineColor: str
326    A color name from the Bokeh palette.
327
328        rangeName: str
329    The range name to associate the `LinearAxis` layout with the data for
330    plotting.
331
332    Returns
333    -------
334    `None`.
335    """
336    data = jumpResult.data
337    plot.line(data.plotTime, data.altitudeAGLFt, legend_label = label, line_width = 2, line_color = lineColor, y_range_name = rangeName)
338
339
340def graphAngle(plot,
341               jumpResult,
342               label = 'angle',
343               lineColor = 'deepskyblue',
344               rangeName = 'angle'):
345    """
346    Graph the flight angle
347
348    Arguments
349    ---------
350        plot: pb.figure
351    A Bokeh figure where to render the plot.
352
353        jumpResult: ssscoring.JumpResults
354    A jump results named tuple with score, max speed, scores, data, etc.
355
356        label: str
357    The legend label for the new Y axis.
358
359        lineColor: str
360    A color name from the Bokeh palette.
361
362        rangeName: str
363    The range name to associate the `LinearAxis` layout with the data for
364    plotting.
365
366    Returns
367    -------
368    `None`.
369    """
370    data = jumpResult.data
371    plot.line(data.plotTime, data.speedAngle, legend_label = label, line_width = 2, line_color = lineColor, y_range_name = rangeName)