Models

​

Overview

​

Purpose

• Evaluate athletes objectively using data-driven metrics with customizable weighting
• Compare athletes across different positions using position-specific scoring criteria
• Track performance against defined targets and benchmarks
• Segment evaluation by athlete characteristics (position, experience, etc.)

​

Use Cases

• Recruitment evaluation and ranking
• Transfer portal analysis
• Performance benchmarking against team standards
• Position-specific athlete assessment
• Multi-factor valuation for roster decisions

​

Model Structure

​

Root Metric

• Cannot be deleted or renamed
• Has a fixed path of ""
• Aggregates all direct children using weighted scoring

​

Metric Hierarchy

​

Metric Types

​

AUTO

• Requires an athlete_variable_id linking to the data source
• Requires an agg_type specifying how to aggregate multiple data points
• Value is fetched and calculated automatically based on configuration

​

MANUAL

• No automatic data fetching
• Values are stored as athlete metric values
• Useful for subjective assessments or data not captured in variables

​

GROUP

• Act as organizational containers in the tree
• Score is calculated from weighted child scores
• Can be static (just aggregates children) or dynamic (has its own data source)

​

Metric Configuration

​

Weight

• Weights of all siblings should sum to 1 (100%)
• A weight of 0.25 means this metric contributes 25% of the parent’s score
• Weight of 0 effectively disables the metric

​

Interpolation Methods

• Worst: The raw value that produces score 0
• Target: The raw value that produces the full weighted score
• Best: The upper bound of the value range

​

Stepwise Configuration

{
  target: number; // Threshold value
  weight: number; // Score at this step (0-1)
  label: string | null; // Optional label (e.g., "Good", "Excellent")
}

​

Units

​

Fallback Behavior

​

Model Groups

​

Group Hierarchy

• Groups can have parent groups (creating nested segments)
• Each group can filter by athlete position
• Each group can filter by data conditions (e.g., “Total Points > 100”)

​

Universal vs Group-Specific Metrics

• Universal metrics (model_group_id: null) apply to all athletes
• Group-specific metrics only appear when evaluating athletes matching that group

​

Metric Overrides

• Weight
• Interpolation type and details
• Fallback behavior
• Data filters

​

Applicability

1. Finds all groups the athlete matches (by position and data filters)
2. Builds “branches” from root to each applicable leaf group
3. Collects all universal metrics plus group-specific metrics from applicable branches
4. Merges overrides from shallowest to deepest group

​

Score Calculation

​

Flow

1. Data Aggregation: For AUTO metrics, fetch and aggregate raw data
2. Interpolation: Map raw value to normalized score using interpolation method
3. Weighting: Multiply normalized score by metric weight
4. Propagation: Roll up child scores to parent groups

​

Group Score Calculation

1. Sum all child weighted scores
2. Calculate the sum of all child weights
3. Determine children’s performance ratio (scores sum / weights sum)
4. Adjust base weight by children’s performance

​

Example

Root (weight: 1.0)
├── Athleticism (GROUP, weight: 0.4)
│   ├── Speed (AUTO, weight: 0.5)
│   └── Strength (AUTO, weight: 0.5)
└── Production (GROUP, weight: 0.6)
    ├── Points (AUTO, weight: 0.7)
    └── Assists (AUTO, weight: 0.3)

• Speed: 0.8 (80% of target)
• Strength: 0.6 (60% of target)
• Points: 0.9 (90% of target)
• Assists: 0.7 (70% of target)

• Athleticism = (0.8 × 0.5 + 0.6 × 0.5) × 0.4 = 0.28
• Production = (0.9 × 0.7 + 0.7 × 0.3) × 0.6 = 0.504
• Overall = 0.28 + 0.504 = 0.784

​

Key Types Reference

​

ClientSideModel

{
  data: AthleteVariable;        // Model metadata
  groups: ModelGroup[];         // Segmentation groups
  metrics: ClientSideModelMetric[]; // All metrics
}

​

ModelMetric

{
  id: ModelMetricId;
  name: string | null;
  path: string;                 // Hierarchy position
  type: "auto" | "manual" | "group";
  value_type: "static" | "dynamic";
  weight: number;               // 0-1

  // Data source (AUTO metrics)
  athlete_variable_id: AthleteVariableId | null;
  agg_type: AggregationType | null;

  // Scoring configuration
  interpolation_type: InterpolationType;
  interpolation_details: { worst, target, best, ... };

  // Unit display
  unit_type: UnitType;
  unit_details: { decimal_places?, steps?, ... };

  // Missing data handling
  fallback_type: "value" | "ignore" | "none";
  fallback_details: { value? } | null;

  // Segmentation
  model_group_id: ModelGroupId | null;
  layout: { x, y };             // UI position
}

​

ModelGroup

{
  id: ModelGroupId;
  name: string | null;
  parent_group_id: ModelGroupId | null;
  position: AthletePosition | null;     // Position filter
  data_filters: DataFilter[] | null;    // Data-based filters
  order: number | null;
}

​

ModelMetricOverride

{
  id: ModelMetricOverrideId;
  metric_id: ModelMetricId;
  model_group_id: ModelGroupId;

  // All fields nullable - only set fields override
  weight: number | null;
  interpolation_type: InterpolationType | null;
  interpolation_details: { ... } | null;
  fallback_type: FallbackType | null;
  fallback_details: { ... } | null;
  data_filters: DataFilter[] | null;
}

​

Validation