ssscoring 1.5.0__py3-none-any.whl

ssscoring/__init__.py

@@ -0,0 +1,33 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+"""
+Speed Skydiving Scoring tools package for processing FlySight v1 and v2 CSV data
+files.
+
+This library relies on NumPy and pandas.  When running in a Lucyfer notebook,
+it also requires the Bokeh plotting library.
+
+The documentation for each module in this package is linked from the navigation
+bar.  The **fs1** module contains functions that process v1 files.  The v2
+implementation is in progress in a private Git branch.
+
+## Source code
+
+You are welcome to **<a href='https://github.com/pr3d4t0r/SSScoring' target='_new'>fork SSScoring</a>**
+on GitHub.  You will need Python 3.9 or later, pandas, and NumPy as minimum
+requirements.
+
+You may see the source files here:
+
+<a href='https://github.com/pr3d4t0r/SSScoring/tree/master/ssscoring' target='_new'>https://github.com/pr3d4t0r/SSScoring/tree/master/ssscoring</a>
+"""
+
+import importlib.metadata
+
+
+__VERSION__ = importlib.metadata.version('ssscoring')
+"""
+@public
+"""
+
+

ssscoring/constants.py

@@ -0,0 +1,85 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+"""
+Constants module and definitions.
+
+**All measurements are expressed in meters unless noted otherwise.**
+"""
+
+import math
+
+
+# +++ implementation +++
+
+BREAKOFF_ALTITUDE = 1707.0
+"""
+Breakoff altitude or hard deck.
+"""
+
+DEG_IN_RADIANS = math.pi/180.0
+"""
+π/180º
+"""
+
+EXIT_SPEED = 2*9.81
+"""
+Guesstimate of the exit speed; 2*g
+"""
+
+FLYSIGHT_1_HEADER = set([ 'time', 'lat', 'lon', 'hMSL', 'velN', 'velE', 'velD', 'hAcc', 'vAcc', 'sAcc', 'heading', 'cAcc', 'gpsFix', 'numSV', ])
+"""
+FlySight v1 CSV file headers.
+"""
+
+FT_IN_M = 3.2808
+"""
+Number of feet in a meter.
+"""
+
+IGNORE_LIST = [ '.ipynb_checkpoints', ]
+"""
+Internal use - list of files to be ignored during bulk file processing in the
+data lake (e.g. `./data`).
+"""
+
+LAST_TIME_TRANCHE = 25.0
+"""
+Times > 25 s are irrelevant because it means that the speed skydiver flew at
+vSpeed < 400 km/h.
+"""
+
+MAX_ALTITUDE_FT = 15500
+"""
+Maximum suggested altitude but irrelevant in general.  Max altitude without
+oxygen is 15,500 ft AGL at most DZs.  A jumnp from a higher altitude would
+require oxygen and would be scored 3,000 ft higher than the hard deck.
+"""
+
+MAX_ALTITUDE_METERS = MAX_ALTITUDE_FT/3.28
+"""
+See
+---
+    ssscoring.constants.MAX_ALTITUDE_FT
+"""
+
+MAX_SPEED_ACCURACY = 3.0
+"""
+Speed accuracy for the FlySight device.
+"""
+
+MIN_JUMP_FILE_SIZE = 1024*512
+"""
+FlySight v1 files smaller than `MIN_JUMP_FILE_SIZE` are ignored because they
+lack the minimum number of data points to contain a valid speed skydive.
+**TODO:** Revise for FlySight v2.
+"""
+
+PERFORMANCE_WINDOW_LENGTH = 2256.0
+"""
+Performance window length as defined by ISSA/IPC/USPA.
+"""
+
+VALIDATION_WINDOW_LENGTH = 1006.0
+"""
+The validation window length as defined in the competition rules.
+"""

ssscoring/datatypes.py

@@ -0,0 +1,54 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+
+"""
+SSScoring custom type definitions for easier symbolic manipuation.
+"""
+
+from collections import namedtuple
+
+
+# +++ implementation +++
+
+JumpResults = namedtuple('JumpResults', 'color data maxSpeed result score scores table window')
+"""
+A named tuple containing the score, maximum speed, scores throught the
+performance window, the results table for a jump, the output color for the
+result, and the result information string.
+
+Attributes
+----------
+- `color` - a string representing a color, green if the result is valid, red
+            otherwise
+- `data` - dataframe containing all the data points for plotting and
+           calculations
+- `maxSpeed` - maximum absolute speed registered during a skydive
+- `result` - dataframe of results
+- `score` - maximum mean speed during a 3-second window during the skydive
+- `scores` - a series with all the scored ruding the sliding 3-sec window for
+             the whole speed skydive
+- `table` - summary table of results of the speed run
+- `window` - the scoring window data, an instance of `PerformanceWindow`
+"""
+
+
+PerformanceWindow = namedtuple('PerformanceWindow', 'start end validationStart')
+"""
+An object to handle the performance window (as defined in competition rules) as
+a single object with all the properties necessary to interpret it and manipulate
+it across different function or method calls.
+
+Attributes
+----------
+- `start` - beginning or start of the performance window, or exit from the
+            aircraft
+- `end` - end of the performance window, or `start-PERFORMANCE_WINDOW_LENGTH`
+- `validationStart` - end of the performance window - the `VALIDATION_WINDOW_END`
+
+See
+---
+    ssscoring.constants.PERFORMANCE_WINDOW_LENGTH
+    ssscoring.constants.VALIDATION_WINDOW_END
+"""
+
+

ssscoring/errors.py

@@ -0,0 +1,30 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+
+import json
+
+
+# +++ classes +++
+
+class SSScoringError(Exception):
+    """
+    Abstract class that defines all exceptions and errors and has a dictionary
+    representation of itself, for cleaner structured logging.
+
+    Arguments
+    ---------
+        message : str
+    A meaningful error message, human-readable
+        errno : int
+    An optional integer value, similar to ERRNO in C/UNIX
+    """
+    def __init__(self, message: str, errno: int = -1):
+        self._info = message
+        self._errno = errno
+
+
+    def __str__(self):
+        e = {  'SSScoringError': self._info, 'errno': self._errno, }
+
+        return json.dumps(e)
+

ssscoring/fs1.py

@@ -0,0 +1,553 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+"""
+Functions and logic for detecting, validating, analyzing, and manipulating
+FlySight 1 CSV files, including detection in the file system.  The functions in
+this module assume that a data lake exists somewhere in the file system (whether
+local or cloud-based).
+"""
+
+
+from ssscoring.constants import BREAKOFF_ALTITUDE
+from ssscoring.constants import DEG_IN_RADIANS
+from ssscoring.constants import EXIT_SPEED
+from ssscoring.constants import FLYSIGHT_1_HEADER
+from ssscoring.constants import FT_IN_M
+from ssscoring.constants import IGNORE_LIST
+from ssscoring.constants import LAST_TIME_TRANCHE
+from ssscoring.constants import MAX_SPEED_ACCURACY
+from ssscoring.constants import MIN_JUMP_FILE_SIZE
+from ssscoring.constants import PERFORMANCE_WINDOW_LENGTH
+from ssscoring.constants import VALIDATION_WINDOW_LENGTH
+from ssscoring.datatypes import JumpResults
+from ssscoring.datatypes import PerformanceWindow
+from ssscoring.errors import SSScoringError
+
+import csv
+import math
+import os
+
+import pandas as pd
+
+
+# +++ functions +++
+
+def validFlySightHeaderIn(fileCSV: str) -> bool:
+    """
+    Checks if a file is a CSV in FlySight 1 format.  The checks include:
+
+    - Whether the file is a CSV, using a comma delimiter
+    - Checks for the presence of all the documented FlySight headers
+
+    Arguments
+    ---------
+        fileCSV
+    A file name to verify as a valid FlySight file
+
+    Returns
+    -------
+    `True` if `fileCSV` is a FlySight CSV file, otherwise `False`.
+    """
+    delimiters =  [',', ]
+    hasAllHeaders = False
+    with open(fileCSV, 'r') as inputFile:
+        try:
+            dialect = csv.Sniffer().sniff(inputFile.readline(), delimiters = delimiters)
+        except:
+            return False
+        if dialect.delimiter in delimiters:
+            inputFile.seek(0)
+            header = next(csv.reader(inputFile))
+        else:
+            return False
+        hasAllHeaders = FLYSIGHT_1_HEADER.issubset(header)
+    return hasAllHeaders
+
+
+def isValidMinimumAltitude(altitude: float) -> bool:
+    """
+    Reports whether an `altitude` is within the IPC and USPA valid parameters,
+    or within `BREAKOFF_ALTITUDE` and `PERFORMACE_WINDOW_LENGTH`.  In invalid
+    altitude doesn't invalidate a FlySight data file.  This function can be used
+    for generating warnings.  The stock FlySightViewer scores a speed jump even
+    if the exit was below the minimum altitude.
+
+    Arguments
+    ---------
+        altitude
+    An altitude in meters, often calculated as data.hMSL - DZ altitude.
+
+    Returns
+    -------
+    `True` if the altitude is valid.
+    """
+    minAltitude = BREAKOFF_ALTITUDE+PERFORMANCE_WINDOW_LENGTH
+    return altitude >= minAltitude
+
+
+def getAllSpeedJumpFilesFrom(dataLake: str) -> list:
+    """
+    Get a list of all the speed jump files from a data lake, where data lake is
+    defined as a reachable path that contains one or more FlySight CSV files.
+    This function tests each file to ensure that it's a speed skydive FlySight
+    file in a valid format and length.
+
+    Arguments
+    ---------
+        dataLake: str
+    A valid (absolute or relative) path name to the top level directory where
+    the data lake starts.
+
+    Returns
+    -------
+    A list of speed jump file names for later SSScoring processing.
+    """
+    jumpFiles = list()
+    for root, dirs, files in os.walk(dataLake):
+        if any(name in root for name in IGNORE_LIST):
+            continue
+        for fileName in files:
+            if 'CSV' in fileName:
+                jumpFileName = os.path.join(root, fileName)
+                stat = os.stat(jumpFileName)
+                if stat.st_size >= MIN_JUMP_FILE_SIZE and validFlySightHeaderIn(jumpFileName):
+                    jumpFiles.append(jumpFileName)
+
+    return jumpFiles
+
+
+def convertFlySight2SSScoring(rawData: pd.DataFrame,
+                              altitudeDZMeters = 0.0,
+                              altitudeDZFt = 0.0):
+    """
+    Converts a raw dataframe initialized from a FlySight CSV file into the
+    SSScoring file format.  The SSScoring format uses more descriptive column
+    headers, adds the altitude in feet, and uses UNIX time instead of an ISO
+    string.
+
+    If both `altitudeDZMeters` and `altitudeDZFt` are zero then hMSL is used.
+    Otherwise, this function adjusts the effective altitude with the value.  If
+    both meters and feet values are set this throws an error.
+
+    Arguments
+    ---------
+        rawData : pd.DataFrame
+    FlySight CSV input as a dataframe
+
+        altitudeDZMeters : float
+    Drop zone height above MSL
+
+        altitudeDZFt
+    Drop zone altitudde above MSL
+
+    Returns
+    -------
+    A dataframe in SSScoring format, featuring these columns:
+
+    - timeUnix
+    - altitudeMSL
+    - altitudeASL
+    - altitudeMSLFt
+    - altitudeASLFt
+    - hMetersPerSecond
+    - hKMh (km/h)
+    - vMetersPerSecond
+    - vKMh (km/h)
+    - angle
+    - speedAccuracy
+
+    Errors
+    ------
+    `SSScoringError` if the DZ altitude is set in both meters and feet.
+    """
+    if not isinstance(rawData, pd.DataFrame):
+        raise SSScoringError('convertFlySight2SSScoring input must be a FlySight CSV dataframe')
+
+    if altitudeDZMeters and altitudeDZFt:
+        raise SSScoringError('Cannot set altitude in meters and feet; pick one')
+
+    if altitudeDZMeters:
+        altitudeDZFt = FT_IN_M*altitudeDZMeters
+    if altitudeDZFt:
+        altitudeDZMeters = altitudeDZFt/FT_IN_M
+
+    data = rawData.copy()
+
+    data['altitudeMSLFt'] = data['hMSL'].apply(lambda h: FT_IN_M*h)
+    data['altitudeASL'] = data.hMSL-altitudeDZMeters
+    data['altitudeASLFt'] = data.altitudeMSLFt-altitudeDZFt
+    data['timeUnix'] = data['time'].apply(lambda t: pd.Timestamp(t).timestamp())
+    data['hMetersPerSecond'] = (data.velE**2.0+data.velN**2.0)**0.5
+    speedAngle = data['hMetersPerSecond']/data['velD']
+    speedAngle = round(90.0-speedAngle.apply(math.atan)/DEG_IN_RADIANS, 1)
+
+    data = pd.DataFrame(data = {
+        'timeUnix': data.timeUnix,
+        'altitudeMSL': data.hMSL,
+        'altitudeASL': data.altitudeASL,
+        'altitudeMSLFt': data.altitudeMSLFt,
+        'altitudeASLFt': data.altitudeASLFt,
+        'vMetersPerSecond': data.velD,
+        'vKMh': 3.6*data.velD,
+        'speedAngle': speedAngle,
+        'speedAccuracy': data.sAcc,
+        'hMetersPerSecond': data.hMetersPerSecond,
+        'hKMh': 3.6*data.hMetersPerSecond,
+    })
+
+    return data
+
+
+def dropNonSkydiveDataFrom(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Discards all data rows before maximum altitude, and all "negative" altitude
+    rows because we don't skydive underground (FlySight bug?).
+
+    Arguments
+    ---------
+        data : pd.DataFrame
+    Jump data in SSScoring format (headers differ from FlySight format)
+
+    Returns
+    -------
+    The jump data for the skydive
+    """
+    timeMaxAlt = data[data.altitudeASL == data.altitudeASL.max()].timeUnix.iloc[0]
+    data = data[data.timeUnix > timeMaxAlt]
+
+    data = data[data.altitudeASL > 0]
+
+    return data
+
+
+def _dataGroups(data):
+    data_ = data.copy()
+    data_['positive'] = (data_.vMetersPerSecond > 0)
+    data_['group'] = (data_.positive != data_.positive.shift(1)).astype(int).cumsum()-1
+
+    return data_
+
+
+def getSpeedSkydiveFrom(data: pd.DataFrame) -> tuple:
+    """
+    Take the skydive dataframe and get the speed skydiving data:
+
+    - Exit
+    - Speed skydiving window
+    - Drops data before exit and below breakoff altitude
+
+    Arguments
+    ---------
+        data : pd.DataFrame
+    Jump data in SSScoring format
+
+    Returns
+    -------
+    A tuple of two elements:
+
+    - A named tuple with performance and validation window data
+    - A dataframe featuring only speed skydiving data
+    """
+    data = _dataGroups(data)
+    groups = data.group.max()+1
+
+    freeFallGroup = -1
+    MIN_DATA_POINTS = 100 # heuristic
+    MIN_MAX_SPEED = 200 # km/h, heuristic; slower ::= no free fall
+    for group in range(groups):
+        subset = data[data.group == group]
+        if len(subset) >= MIN_DATA_POINTS and subset.vKMh.max() >= MIN_MAX_SPEED:
+            freeFallGroup = group
+
+    data = data[data.group == freeFallGroup]
+    data = data.drop('group', axis = 1).drop('positive', axis = 1)
+
+    # Speed ~= 9.81 m/s; subtract 1 second for actual exit.
+    exitTime = data[data.vMetersPerSecond > EXIT_SPEED].head(1).timeUnix.iat[0]-2.0
+    # TODO:  Delete this as the upper bounds the next time you see this note.
+    # data = data[data.vMetersPerSecond > EXIT_SPEED]
+    data = data[data.timeUnix >= exitTime]
+    data = data[data.altitudeASL >= BREAKOFF_ALTITUDE]
+
+    windowStart = data.iloc[0].altitudeASL
+    windowEnd = windowStart-PERFORMANCE_WINDOW_LENGTH
+    if windowEnd < BREAKOFF_ALTITUDE:
+        windowEnd = BREAKOFF_ALTITUDE
+
+    validationWindowStart = windowEnd+VALIDATION_WINDOW_LENGTH
+    data = data[data.altitudeASL >= windowEnd]
+
+    return PerformanceWindow(windowStart, windowEnd, validationWindowStart), data
+
+
+def isValidJump(data: pd.DataFrame,
+                window: PerformanceWindow) -> bool:
+    """
+    Validates the jump according to ISC/FAI/USPA competition rules.  A jump is
+    valid when the speed accuracy parameter is less than 3 m/s for the whole
+    validation window duration.
+
+    Arguments
+    ---------
+        data : pd.DataFramce
+    Jumnp data in SSScoring format
+        window : ssscoring.PerformanceWindow
+    Performance window start, end values in named tuple format
+
+    Returns
+    -------
+    `True` if the jump is valid according to ISC/FAI/USPA rules.
+    """
+    accuracy = data[data.altitudeASL < window.validationStart].speedAccuracy.max()
+    return accuracy < MAX_SPEED_ACCURACY
+
+
+def jumpAnalysisTable(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Generates the HCD jump analysis table, with speed data at 5-second intervals
+    after exit.
+
+    Arguments
+    ---------
+        data : pd.DataFrame
+    Jump data in SSScoring format
+
+    Returns
+    -------
+    A tuple with a pd.DataFrame and the max speed recorded for the jump:
+
+    - A table dataframe with time and speed
+    - a floating point number
+    """
+    table = None
+
+    for column in pd.Series([ 5.0, 10.0, 15.0, 20.0, 25.0, ]):
+        for interval in range(int(column)*10, 10*(int(column)+1)):
+            # Use the next 0.1 sec interval if the current interval tranche has
+            # NaN values.
+            columnRef = interval/10.0
+            timeOffset = data.iloc[0].timeUnix+columnRef
+            tranche = data.query('timeUnix == %f' % timeOffset).copy()
+            tranche['time'] = [ column, ]
+            if not tranche.isnull().any().any():
+                break
+
+        if pd.isna(tranche.iloc[-1].vKMh):
+            tranche = data.tail(1).copy()
+            tranche['time'] = tranche.timeUnix-data.iloc[0].timeUnix
+
+        if table is not None:
+            table = pd.concat([ table, tranche, ])
+        else:
+            table = tranche
+
+    table = pd.DataFrame({
+                'time': table.time,
+                'vKMh': table.vKMh,
+                'hKMh': table.hKMh,
+                'speedAngle': table.speedAngle,
+                'netVectorKMh': (table.vKMh**2+table.hKMh**2)**0.5,
+                'altitude (ft)': table.altitudeASLFt, })
+
+    return (data.vKMh.max(), table)
+
+
+def processJump(data: pd.DataFrame):
+    """
+    Take a dataframe in SSScoring format and process it for display.  It
+    serializes all the steps that would be taken from the ssscoring module, but
+    includes some text/HTML data in the output.
+
+    Arguments
+    ---------
+        data: pd.DataFrame
+    A dataframe in SSScoring format
+
+    Returns
+    -------
+    A `JumpResults` named tuple with these items:
+
+    - `score` speed score
+    - `maxSpeed` maximum speed during the jump
+    - `scores` a Series of every 3-second window scores from exit to breakoff
+    - `data` an updated SSScoring dataframe `plotTime`, where 0 = exit, used
+      for plotting
+    - `window` a named tuple with the exit, breakoff, and validation window
+      altitudes
+    - `table` a dataframe featuring the speeds and altitudes at 5-sec intervals
+    - `color` a string that defines the color for the jump result; possible
+      values are _green_ for valid jump, _red_ for invalid jump, per ISC rules
+    - `result` a string with the legend of _valid_ or _invalid_ jump
+    """
+    data = data.copy()
+    data = dropNonSkydiveDataFrom(data)
+    window, data = getSpeedSkydiveFrom(data)
+    validJump = isValidJump(data, window)
+    score = 0.0
+    scores = dict()
+    table = None
+
+    if validJump:
+        maxSpeed, table = jumpAnalysisTable(data)
+        color = '#0f0'
+        result = '🟢 valid'
+        baseTime = data.iloc[0].timeUnix
+        data['plotTime'] = data.timeUnix-baseTime
+
+        for spot in data.plotTime:
+            r0 = data[data.plotTime == spot]
+            r1 = data[data.plotTime == spot+3.0]
+
+            if not r1.empty:
+                scores[0.5*(float(r0.vKMh.iloc[0])+float(r1.vKMh.iloc[0]))] = spot
+        score = max(scores)
+
+    else:
+        color = '#f00'
+        maxSpeed = -1
+        score = 0
+        result = '🔴 invalid'
+
+    return JumpResults(color, data, maxSpeed, result, score, scores, table, window)
+
+
+
+def processAllJumpFiles(jumpFiles: list, altitudeDZMeters = 0.0) -> dict:
+    """
+    Process all jump files in a list of valid FlySight files.  Returns a
+    dictionary of jump results with a human-readable version of the file name.
+    The `jumpFiles` list can be generated by hand or the output of the
+    `ssscoring.getAllSpeedJumpFilesFrom` called to operate on a data lake.
+
+    Arguments
+    ---------
+        jumpFiles
+    A list of relative or absolute path names to individual FlySight CSV files.
+
+        altitudeDZMeters : float
+    Drop zone height above MSL
+
+        dict
+    A dictionary of jump results.  The key is a human-readable version of a
+    `jumpFile` name with the extension, path, and extraneous spaces eliminated
+    or replaced by appropriate characters.  File names use Unicode, so accents
+    and non-ANSI characters are allowed in file names.
+    """
+    jumpResults = dict()
+    for jumpFile in jumpFiles:
+        jumpResult = processJump(
+            convertFlySight2SSScoring(pd.read_csv(jumpFile, skiprows = (1, 1)),
+            altitudeDZMeters = altitudeDZMeters))
+        tag = jumpFile.replace('CSV', '').replace('.', '').replace('/data', '').replace('/', ' ').strip()
+        if 'valid' in jumpResult.result:
+            jumpResults[tag] = jumpResult
+    return jumpResults
+
+
+def aggregateResults(jumpResults: dict) -> pd.DataFrame:
+    """
+    Aggregate all the results in a table fashioned after Marco Hepp's and Nklas
+    Daniel's score tracking data.
+
+    Arguments
+    ---------
+        jumpResults: dict
+    A dictionary of jump results, in which each result corresponds to a FlySight
+    file name.  See `ssscoring.processAllJumpFiles` for details.
+
+    Returns
+    -------
+    A dataframe featuring these columns:
+
+    - Score
+    - Speeds at 5, 10, 15, 20, and 25 second tranches
+    - Final time contemplated in the analysis
+    - Max speed
+
+    The dataframe rows are identified by the human readable jump file name.
+    """
+    speeds = pd.DataFrame()
+    for jumpResultIndex in sorted(list(jumpResults.keys())):
+        jumpResult = jumpResults[jumpResultIndex]
+        if jumpResult.score > 0.0:
+            t = jumpResult.table
+            finalTime = t.iloc[-1].time
+            t.iloc[-1].time = LAST_TIME_TRANCHE
+            t = pd.pivot_table(t, columns = t.time)
+            t.drop(['altitude (ft)'], inplace = True)
+            d = pd.DataFrame([ jumpResult.score, ], index = [ jumpResultIndex, ], columns = [ 'score', ], dtype = object)
+            for column in t.columns:
+                d[column] = t[column].iloc[3]
+            d['finalTime'] = [ finalTime, ]
+            d['maxSpeed'] = jumpResult.maxSpeed
+
+            if speeds.empty:
+                speeds = d.copy()
+            else:
+                speeds = pd.concat([ speeds, d, ])
+    return speeds.sort_index()
+
+
+def roundedAggregateResults(jumpResults: dict) -> pd.DataFrame:
+    """
+    Aggregate all the results in a table fashioned after Marco Hepp's and Nklas
+    Daniel's score tracking data.  All speed results are rounded at `n > x.5`
+    for any value.
+
+    Arguments
+    ---------
+        jumpResults: dict
+    A dictionary of jump results, in which each result corresponds to a FlySight
+    file name.  See `ssscoring.processAllJumpFiles` for details.
+
+    Returns
+    -------
+    A dataframe featuring the **rounded values** for these columns:
+
+    - Score
+    - Speeds at 5, 10, 15, 20, and 25 second tranches
+    - Max speed
+
+    The `finalTime` column is ignored.
+
+    The dataframe rows are identified by the human readable jump file name.
+
+    This is a less precise version of the `ssscoring.aggregateResults`
+    dataframe, useful during training to keep rounded results available for
+    review.
+    """
+    aggregate = aggregateResults(jumpResults)
+    for column in [col for col in aggregate.columns if 'Time' not in str(col)]:
+        aggregate[column] = aggregate[column].apply(round)
+
+    return aggregate
+
+
+def totalResultsFrom(aggregate: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculates the total and mean speeds for an aggregation of speed jumps.
+
+    Arguments
+    ---------
+        aggregate: pd.DataFrame
+    The aggregate results dataframe resulting from calling `ssscoring.aggregateResults`
+    with valid results.
+
+    Returns
+    -------
+    A dataframe with one row and two columns:
+
+    - totalSpeed ::= the sum of all speeds in the aggregated results
+    - meanSpeed ::= the mean of all speeds
+    - maxScore ::= the max score among all the speed scores
+
+    Raises
+    ------
+    `AttributeError` if aggregate is an empty dataframe or `None`, or if the
+    `aggregate` dataframe doesn't conform to the output of `ssscoring.aggregateResults`.
+    """
+    totals = pd.DataFrame({ 'totalSpeed': [ aggregate.score.sum(), ], 'meanSpeed': [ aggregate.score.mean(), ], 'maxScore': [ aggregate.score.max(), ], }, index = [ 'totalSpeed'],)
+
+    return totals
+
+

ssscoring/notebook.py

@@ -0,0 +1,245 @@
+# See: https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt
+
+"""
+## Utility reusable code for notebooks.
+"""
+
+
+from bokeh.models import LinearAxis
+from bokeh.models import Range1d
+
+from ssscoring.constants import MAX_ALTITUDE_FT
+
+import bokeh.io as bi
+import bokeh.plotting as bp
+
+
+# *** constants ***
+DATA_LAKE_ROOT = './data' # Lucyfer default
+SPEED_COLORS = colors = ('limegreen', 'blue', 'tomato', 'turquoise', 'deepskyblue', 'forestgreen', 'coral', 'darkcyan',)
+
+
+# *** global initialization ***
+
+bp.output_notebook(hide_banner = True)
+# TODO: make this configurable:
+bi.curdoc().theme = 'dark_minimal'
+
+
+# *** functions ***
+
+def initializePlot(jumpTitle: str,
+                   height = 500,
+                   width = 900,
+                   xLabel = 'seconds from exit',
+                   yLabel = 'km/h',
+                   # TODO: roll back to 40.0?
+                   # xMax = 40.0,
+                   xMax = 35.0,
+                   yMax = 550.0):
+    """
+    Initiialize a plotting area for notebook output.
+
+    Arguments
+    ---------
+        jumpTitle: str
+    A title to identify the plot.
+
+        height: int
+    Height of the plot in pixels.  Default = 500.
+
+        width: int
+    Width of the plot in pixels.  Default = 900.
+
+        xLabel: str
+    X axis label.  Default:  `'seconds from exit'`
+
+        yLabel: str
+    Y axis label.  Default:  `'km/h'`
+
+        xMax: float
+    The maximum rnage for the X axis.  Default = 40.0
+
+        yMax: float
+    The maximum range for the Y axis.  Default = 550
+    """
+    return bp.figure(title = jumpTitle,
+                     height = height,
+                     width = width,
+                     x_axis_label = xLabel,
+                     y_axis_label = yLabel,
+                     x_range = (0.0, xMax),
+                     y_range = (0.0, yMax))
+
+
+def _graphSegment(plot,
+                  x0 = 0.0,
+                  y0 = 0.0,
+                  x1 = 0.0,
+                  y1 = 0.0,
+                  lineWidth = 1,
+                  color = 'black'):
+    plot.segment(x0 = [ x0, ],
+                 y0 = [ y0, ],
+                 x1 = [ x1, ],
+                 y1 = [ y1, ],
+                 line_width = lineWidth,
+                 color = color)
+
+
+def initializeExtraYRanges(plot,
+                           startY: float = 0.0,
+                           endY: float = MAX_ALTITUDE_FT):
+    """
+    Initialize an extra Y range for reporting other data trend (e.g. altitude)
+    in the plot.
+
+    Arguments
+    ---------
+        plot
+    A valid instance of `bp.figure` with an existing plot defined for it
+
+        startY: float
+    The Y range starting value
+
+        endY: float
+    The Y range ending value
+
+    Returns
+    -------
+    An instance of `bp.figure` updated to report an additional Y axis.
+    """
+    plot.extra_y_ranges = {
+        'altitudeFt': Range1d(start = startY, end = endY),
+        'angle': Range1d(start = 0.0, end = 90.0),
+    }
+    plot.add_layout(LinearAxis(y_range_name = 'altitudeFt', axis_label = 'Alt (ft)'), 'left')
+    plot.add_layout(LinearAxis(y_range_name = 'angle', axis_label = 'angle'), 'left')
+
+    return plot
+
+
+def graphJumpResult(plot,
+                    jumpResult,
+                    lineColor = 'green',
+                    legend = 'speed',
+                    showIt = True):
+    """
+    Graph the jump results using the initialized plot.
+
+    Arguments
+    ---------
+        plot: bp.figure
+    A Bokeh figure where to render the plot.
+
+        jumpResult: ssscoring.JumpResults
+    A jump results named tuple with score, max speed, scores, data, etc.
+
+        lineColor: str
+    A valid color from the Bokeh palette:  https://docs.bokeh.org/en/2.1.1/docs/reference/colors.html
+    This module defines 8 colors for rendering a competition's results.  See:
+    `ssscoring.notebook.SPEED_COLORS` for the list.
+
+        leged: str
+    A title for the plot.
+
+        showIt: bool
+    A boolean flag for whether the call should render the plot upon the function
+    call.  This flag is used for combining two or more jumps on the same plot.
+    In that case, a call to this function is made with a different `jumpResult`
+    and the `showIt` flag set to `False`.  When the user is ready to view the
+    combined plot, issue a call to `bp.show(plot)`.  Example:
+
+    ```python
+    for result in jumpResults:
+        graphJumpResult(plot, result, showIt = False)
+
+    bp.show(plot)
+
+    Returns
+    -------
+    `None`.
+    ```
+    """
+    data = jumpResult.data
+    scores = jumpResult.scores
+    score = jumpResult.score
+    plot.line(data.plotTime, data.vKMh, legend_label = legend, line_width = 2, line_color = lineColor)
+
+    if showIt:
+        plot.line(data.plotTime, data.hKMh, legend_label = 'H-speed', line_width = 2, line_color = 'red')
+        _graphSegment(plot, scores[score], 0.0, scores[score], score, 3, 'lightblue')
+        _graphSegment(plot, scores[score]+1.5, 0.0, scores[score]+1.5, score, 1, 'darkseagreen')
+        _graphSegment(plot, scores[score]-1.5, 0.0, scores[score]-1.5, score, 1, 'darkseagreen')
+        plot.scatter(x = [ scores[score], ], y = [ score, ], marker = 'square_cross', size = [ 20, ], line_color = 'lightblue', fill_color = None, line_width = 3)
+        bp.show(plot)
+
+
+def graphAltitude(plot,
+                  jumpResult,
+                  label = 'Alt (ft)',
+                  lineColor = 'palegoldenrod',
+                  rangeName = 'altitudeFt'):
+    """
+    Graph a vertical axis with additional data, often used for altitude in ft
+    ASL.
+
+    Arguments
+    ---------
+        plot: pb.figure
+    A Bokeh figure where to render the plot.
+
+        jumpResult: ssscoring.JumpResults
+    A jump results named tuple with score, max speed, scores, data, etc.
+
+        label: str
+    The legend label for the new Y axis.
+
+        lineColor: str
+    A color name from the Bokeh palette.
+
+        rangeName: str
+    The range name to associate the `LinearAxis` layout with the data for
+    plotting.
+
+    Returns
+    -------
+    `None`.
+    """
+    data = jumpResult.data
+    plot.line(data.plotTime, data.altitudeASLFt, legend_label = label, line_width = 2, line_color = lineColor, y_range_name = rangeName)
+
+
+def graphAngle(plot,
+               jumpResult,
+               label = 'angle',
+               lineColor = 'deepskyblue',
+               rangeName = 'angle'):
+    """
+    Graph the flight angle
+
+    Arguments
+    ---------
+        plot: pb.figure
+    A Bokeh figure where to render the plot.
+
+        jumpResult: ssscoring.JumpResults
+    A jump results named tuple with score, max speed, scores, data, etc.
+
+        label: str
+    The legend label for the new Y axis.
+
+        lineColor: str
+    A color name from the Bokeh palette.
+
+        rangeName: str
+    The range name to associate the `LinearAxis` layout with the data for
+    plotting.
+
+    Returns
+    -------
+    `None`.
+    """
+    data = jumpResult.data
+    plot.line(data.plotTime, data.speedAngle, legend_label = label, line_width = 2, line_color = lineColor, y_range_name = rangeName)
+

ssscoring-1.5.0.dist-info/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2018-2024 Eugene "pr3d4t0r" Ciurana
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ssscoring-1.5.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.1
+Name: ssscoring
+Version: 1.5.0
+Summary: ssscoring - Speed Skydiving scoring tools
+Author-email: Eugene Ciurana pr3d4t0r <ssscoring.project@cime.net>
+License: BSD-3-Clause
+Classifier: Intended Audience :: Other Audience
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Requires-Python: >=3.9.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: click
+Requires-Dist: jupyter-bokeh
+
+% ssscoring(3) Version 1.5.0 | Spped Skydiving Scoring API documentation
+
+Name
+====
+
+**SSScoring** - Speed Skydiving Scoring high level library in Python
+
+
+Synopsis
+========
+```python
+# Short code snippet will go here.
+```
+
+
+Description
+===========
+Documentation in progress.
+
+
+License
+=======
+The **SSScoring** package, documentation and examples are licensed under the
+[BSD-3 open source license](https://github.com/pr3d4t0r/SSScoring/blob/master/LICENSE.txt).
+
+

ssscoring-1.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ssscoring/__init__.py,sha256=SnLe-PTy5EdKXBi1jL-pT3PP7dP5vqMFx4evrWmnkHw,998
+ssscoring/constants.py,sha256=L1EhRX0ampvm_GtO-6F3zJWdWBIT8w5ObB0aXWIdRIE,1784
+ssscoring/datatypes.py,sha256=q3On1wuKfKLirIfA_GfZslhsjiSibxvVXdRv07WOAwA,1819
+ssscoring/errors.py,sha256=jJqBEugEw-3lW0j2coj9b3bW0ZwtQODJ47NV_YMElWQ,707
+ssscoring/fs1.py,sha256=Ixr0ciZukBB9DaSwg6tmdwuRW5WMnwdETyuiT0UWO0M,18178
+ssscoring/notebook.py,sha256=Dl-NUFOLd94gs1ORNUmFdjTwSQszfbk8s8LTxgTBAX4,7052
+ssscoring-1.5.0.dist-info/LICENSE.txt,sha256=Nk5_436gyC2j0OUFBhG14LHkhdTvW00ZdzgyaVxzLiA,1529
+ssscoring-1.5.0.dist-info/METADATA,sha256=ZML4T7d6kFtpSUBBbSc19bFB9kvRQ9mnrw5cW_oBTRU,1021
+ssscoring-1.5.0.dist-info/WHEEL,sha256=Mdi9PDNwEZptOjTlUcAth7XJDFtKrHYaQMPulZeBCiQ,91
+ssscoring-1.5.0.dist-info/entry_points.txt,sha256=-hbXHRPOboL6yOxFX-x2Wj1jF5Qz71BNWof-pKb62M4,46
+ssscoring-1.5.0.dist-info/top_level.txt,sha256=mNXsbNRRwarXyeFMPoqMQJN1KfrQR6R0_UkmpCjabKk,10
+ssscoring-1.5.0.dist-info/RECORD,,

ssscoring-1.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (73.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ssscoring-1.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ssscoring = ssscoring:_main

ssscoring-1.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ssscoring