Skip to content
This repository was archived by the owner on Jan 11, 2026. It is now read-only.

DATA_FLOW.md

Latest commit

 

History

History
71 lines (41 loc) · 6.47 KB

DATA_FLOW.md

File metadata and controls

71 lines (41 loc) · 6.47 KB

Risk Score Implementation

Purpose and Overview

The risk score calculation is a crucial component of the Usage-Based Insurance (UBI) system. Its primary goal is to assess the driving behavior and associated risk level of an individual based on various telemetry data inputs. This risk assessment is then used to determine an appropriate insurance premium, with higher-risk drivers being charged higher premiums, and lower-risk drivers receiving discounts.

The risk score serves as a quantitative measure of the likelihood of an accident occurring, based on the driver's driving patterns, vehicle usage, and environmental factors. By incorporating this risk assessment into the insurance pricing model, the UBI system aims to incentivize safer driving practices and promote a more equitable distribution of insurance costs.

Input Data Sources

The risk score calculation relies on two main sources of input data:

  1. IOVData (In-Vehicle Data): This interface encapsulates various telemetry signals collected from the vehicle's on-board diagnostics (OBD) system. It includes information such as:

    • powertrainTransmissionTravelledDistance: Odometer reading in kilometers
    • speed: Vehicle speed in kilometers per hour
    • powertrainFuelSystemRelativeLevel: Current available fuel level as a percentage
    • powertrainCombustionEngineSpeed: Engine speed in revolutions per minute (RPM)
    • obdEngineLoad: Engine load as a percentage
    • powertrainTractionBatteryStateOfChargeCurrent: Battery state of charge as a percentage
    • tripsMorning: Number of trips made between 7:00 AM and 10:00 AM
    • tripsEvening: Number of trips made between 5:00 PM and 7:00 PM
    • tripsNight: Number of trips made between 12:00 AM and 4:00 AM

  2. POIData (Point of Interest Data): This interface represents a key-value mapping of various points of interest (POIs) and their corresponding counts or frequencies. It captures information about the types of locations the driver visits, which can provide insights into their driving patterns and potential risk factors. The specific POI categories may vary based on the available data sources.

The IOVData and POIData are typically collected from the vehicle's telemetry systems and location tracking services, respectively. These data sources provide real-world insights into the driver's behavior, enabling a more accurate and personalized risk assessment.

Calculation Methodology

The risk score calculation is performed by the logisticRegression function, which takes two inputs: the DriverData (containing IOVData and POIData) and a set of Coefficients.

  1. Input Validation: Before proceeding with the calculation, the validateIOVData function is called to ensure that the provided IOVData is valid and within the expected ranges. This step helps catch and handle any erroneous or out-of-range input values.

  2. Linear Combination: The logisticRegression function computes a linear combination of the input features (IOVData and POIData) using the provided coefficients. Each feature is multiplied by its corresponding coefficient, and the products are summed to obtain a single linear sum.

  3. Logistic Function: The linear sum is then passed through the logistic function (1 / (1 + exp(-linearSum))), which maps the linear sum to a value between 0 and 1. This value represents the estimated probability of an accident occurring, given the input data and coefficients.

The coefficients used in the linear combination are determined through historical data analysis and machine learning techniques. They represent the relative importance and impact of each input feature on the overall risk assessment.

Output Format

The logisticRegression function returns the estimated accident probability, which is then used to calculate the monthly insurance premium. The getInsuranceResult function encapsulates this process and returns an InsuranceResult object with the following fields:

  • accidentProbability: The estimated probability of an accident occurring, represented as a value between 0 and 1.
  • monthlyPremium: The calculated monthly insurance premium based on the accident probability and a predefined base premium and risk factor.

To ensure compatibility with blockchain systems, the output values are scaled to 18 decimal places before being returned.

Test Coverage

The risk score implementation is thoroughly tested using a suite of unit tests written with the Jest testing framework. These tests cover various scenarios and edge cases to ensure the correctness and reliability of the calculation process. Here are some key aspects covered by the tests:

  1. Normal Driving Behavior: Tests the calculation of insurance results for typical driving patterns, ensuring that the output falls within expected ranges.

  2. High-Risk Driving Behavior: Verifies that the risk score and premium are appropriately higher for aggressive driving patterns, such as high speeds, excessive engine load, and frequent night trips.

  3. Input Validation: Tests the input validation process by providing out-of-range values and ensuring that the appropriate errors are thrown or handled gracefully.

  4. Missing Data Handling: Checks how the system handles missing or incomplete input data, such as when POIData is not available.

  5. Coefficient Sensitivity: Verifies that changes to the coefficients used in the logistic regression calculation result in the expected changes in the output risk score and premium.

  6. Result Consistency: Ensures that identical inputs produce consistent results across multiple invocations of the calculation functions.

  7. Error Handling: Tests the error handling mechanisms by simulating various error scenarios, such as invalid input data or calculation errors, and verifying that the appropriate error messages and default values are returned.

  8. Edge Cases and Boundary Conditions: Includes tests that cover edge cases and boundary conditions, such as accident probabilities at the extreme ends of the range (0 and 1), or input values at the minimum and maximum allowed limits.

The test suite also includes utilities and helpers for setting up test data, mocking dependencies, and asserting expected outcomes. Code coverage reports are generated to ensure that all critical code paths are exercised by the tests.

By thoroughly testing the risk score implementation, we can have confidence in the correctness and reliability of the calculation process, ensuring that the UBI system provides accurate and fair risk assessments for drivers.