Adds match forecasting, EPA support, and UI polish

Introduces match forecasting and upcoming/noteworthy match features, and adds EPA as a prediction model alongside OPR and XGB. Updates UI for better form consistency, chip presets, and improved interaction for team/event comparison and season records. Expands translations, updates site branding to "FTC Stats", improves accessibility, and adds more detailed team and event insights. Enhances simulation controls, event links, and match prediction explanations for greater clarity and flexibility.

Author: caezium

packages/common/src/index.ts

@@ -17,6 +17,7 @@ export * from "./logic/stats/make-tep-stats";
 export * from "./logic/stats/make-match-stats";
 export * from "./logic/predictions/match-prediction";
 export * from "./logic/predictions/event-simulation";
+export * from "./logic/predictions/epa";
 export * from "./logic/TournamentLevel";
 export * from "./utils/filter";
 export * from "./utils/gql/enum";

packages/common/src/logic/predictions/epa.ts

@@ -0,0 +1,99 @@
+import { Alliance } from "../Alliance";
+import { DESCRIPTORS } from "../descriptors/descriptor-list";
+import { Season } from "../Season";
+import { TournamentLevel } from "../TournamentLevel";
+
+export type EpaMatch = {
+    tournamentLevel: TournamentLevel;
+    scheduledStartTime?: string | null;
+    actualStartTime?: string | null;
+    teams: {
+        teamNumber: number | null;
+        alliance: Alliance;
+        surrogate?: boolean | null;
+    }[];
+    scores:
+        | {
+              red: { totalPoints: number; totalPointsNp?: number | null };
+              blue: { totalPoints: number; totalPointsNp?: number | null };
+          }
+        | null
+        | undefined;
+};
+
+export type EpaOptions = {
+    baseK?: number;
+    includeElims?: boolean;
+};
+
+function getTimestamp(match: EpaMatch): number {
+    const raw = match.actualStartTime ?? match.scheduledStartTime;
+    if (!raw) return 0;
+    const time = Date.parse(raw);
+    return Number.isFinite(time) ? time : 0;
+}
+
+function getScore(season: Season, score: { totalPoints: number; totalPointsNp?: number | null }) {
+    const descriptor = DESCRIPTORS[season];
+    if (!descriptor.pensSubtract && typeof score.totalPointsNp === "number") {
+        return score.totalPointsNp;
+    }
+    return score.totalPoints;
+}
+
+export function calculateEpaRatings(
+    matches: EpaMatch[],
+    season: Season,
+    options: EpaOptions = {}
+): Record<number, number> {
+    const baseK = options.baseK ?? 0.25;
+    const includeElims = options.includeElims ?? false;
+
+    const ratings = new Map<number, number>();
+    const counts = new Map<number, number>();
+
+    const sorted = [...matches].sort((a, b) => getTimestamp(a) - getTimestamp(b));
+
+    for (const match of sorted) {
+        if (!match.scores || !("red" in match.scores)) continue;
+        if (!includeElims && match.tournamentLevel !== TournamentLevel.Quals) continue;
+
+        const redTeams = match.teams
+            .filter((t) => t.alliance === Alliance.Red && !t.surrogate)
+            .map((t) => t.teamNumber)
+            .filter((t): t is number => typeof t === "number");
+        const blueTeams = match.teams
+            .filter((t) => t.alliance === Alliance.Blue && !t.surrogate)
+            .map((t) => t.teamNumber)
+            .filter((t): t is number => typeof t === "number");
+
+        if (!redTeams.length || !blueTeams.length) continue;
+
+        const redScore = getScore(season, match.scores.red);
+        const blueScore = getScore(season, match.scores.blue);
+
+        const redPred = redTeams.reduce((sum, team) => sum + (ratings.get(team) ?? 0), 0);
+        const bluePred = blueTeams.reduce((sum, team) => sum + (ratings.get(team) ?? 0), 0);
+
+        const redError = redScore - redPred;
+        const blueError = blueScore - bluePred;
+
+        for (const team of redTeams) {
+            const count = counts.get(team) ?? 0;
+            const k = baseK / Math.sqrt(count + 1);
+            const next = (ratings.get(team) ?? 0) + (k * redError) / redTeams.length;
+            ratings.set(team, next);
+            counts.set(team, count + 1);
+        }
+
+        for (const team of blueTeams) {
+            const count = counts.get(team) ?? 0;
+            const k = baseK / Math.sqrt(count + 1);
+            const next = (ratings.get(team) ?? 0) + (k * blueError) / blueTeams.length;
+            ratings.set(team, next);
+            counts.set(team, count + 1);
+        }
+    }
+
+    return Object.fromEntries(ratings.entries());
+}

packages/common/src/logic/predictions/match-prediction.ts

@@ -32,6 +32,28 @@ function calculateWinProbability(scoreDiff: number, variance: number): number {
     return 1 / (1 + Math.exp(-k * normalizedDiff));
 }
 
+/**
+ * Predict match outcome from precomputed alliance scores.
+ */
+export function predictMatchFromScores(
+    predictedRedScore: number,
+    predictedBlueScore: number,
+    variance: number = 100
+): MatchPrediction {
+    const scoreDiff = predictedRedScore - predictedBlueScore;
+    const redWinProb = calculateWinProbability(scoreDiff, variance);
+    const blueWinProb = 1 - redWinProb;
+    const confidence = Math.min(Math.abs(scoreDiff) / 50, 1);
+
+    return {
+        redWinProbability: redWinProb,
+        blueWinProbability: blueWinProb,
+        predictedRedScore: Math.max(0, predictedRedScore),
+        predictedBlueScore: Math.max(0, predictedBlueScore),
+        confidence,
+    };
+}
+
 /**
  * Predict match outcome based on alliance OPRs
  *

packages/server/src/graphql/resolvers/Home.ts

@@ -1,10 +1,16 @@
 import {
+    Alliance,
+    BoolTy,
     DESCRIPTORS,
     DateTimeTy,
     EventTypeOption,
     IntTy,
+    RegionOption,
+    RemoteOption,
     Season,
+    TournamentLevel,
     getEventTypes,
+    getRegionCodes,
     list,
     nn,
     nullTy,
@@ -17,7 +23,58 @@ import { EventGQL } from "./Event";
 import { Event } from "../../db/entities/Event";
 import { MatchGQL } from "./Match";
 import { MatchScore } from "../../db/entities/dyn/match-score";
-import { EventTypeOptionGQL } from "./enums";
+import { EventTypeOptionGQL, RegionOptionGQL, RemoteOptionGQL } from "./enums";
+import { GraphQLObjectType } from "graphql";
+import { singleSeasonScoreAwareMatchLoader } from "./Match";
+import { DateTime } from "luxon";
+import { SelectQueryBuilder } from "typeorm";
+
+const NoteworthyMatchesGQL = new GraphQLObjectType({
+    name: "NoteworthyMatches",
+    fields: {
+        highScore: { type: list(nn(MatchGQL)) },
+        combinedScore: { type: list(nn(MatchGQL)) },
+        losingScore: { type: list(nn(MatchGQL)) },
+    },
+});
+
+type MatchKey = { eventSeason: Season; eventCode: string; id: number };
+
+async function loadMatches(keys: MatchKey[]) {
+    if (!keys.length) return [];
+    const matches = await singleSeasonScoreAwareMatchLoader(keys, [], true, true);
+    const byKey = new Map(matches.map((m) => [`${m.eventSeason}-${m.eventCode}-${m.id}`, m]));
+    return keys
+        .map((k) => byKey.get(`${k.eventSeason}-${k.eventCode}-${k.id}`))
+        .filter((m): m is Match => !!m);
+}
+
+function applyEventFilters(
+    q: SelectQueryBuilder<Match>,
+    {
+        region,
+        type,
+        remote,
+    }: {
+        region?: RegionOption | null | undefined;
+        type?: EventTypeOption | null | undefined;
+        remote?: RemoteOption | null | undefined;
+    }
+) {
+    if (region && region !== RegionOption.All) {
+        q.andWhere("e.region_code IN (:...regions)", { regions: getRegionCodes(region) });
+    }
+
+    if (type && type !== EventTypeOption.All) {
+        q.andWhere("e.type IN (:...types)", { types: getEventTypes(type) });
+    }
+
+    if (remote && remote !== RemoteOption.All) {
+        q.andWhere("e.remote = :remote", { remote: remote === RemoteOption.Remote });
+    }
+
+    return q;
+}
 
 export const HomeQueries: Record<string, GraphQLFieldConfig<any, any>> = {
     activeTeamsCount: {
@@ -119,4 +176,170 @@ export const HomeQueries: Record<string, GraphQLFieldConfig<any, any>> = {
                 .getOne();
         },
     },
+
+    upcomingMatches: {
+        type: list(nn(MatchGQL)),
+        args: {
+            season: IntTy,
+            limit: nullTy(IntTy),
+            minutes: nullTy(IntTy),
+            region: { type: RegionOptionGQL },
+            type: { type: EventTypeOptionGQL },
+            remote: { type: RemoteOptionGQL },
+            elim: nullTy(BoolTy),
+        },
+        resolve: async (
+            _,
+            {
+                season,
+                limit,
+                minutes,
+                region,
+                type,
+                remote,
+                elim,
+            }: {
+                season: number;
+                limit?: number | null;
+                minutes?: number | null;
+                region?: RegionOption | null;
+                type?: EventTypeOption | null;
+                remote?: RemoteOption | null;
+                elim?: boolean | null;
+            }
+        ) => {
+            const windowMinutes = minutes ?? 60 * 24;
+            const start = DateTime.now().minus({ minutes: 5 }).toJSDate();
+            const end = DateTime.now().plus({ minutes: windowMinutes }).toJSDate();
+
+            let q = DATA_SOURCE.getRepository(Match)
+                .createQueryBuilder("m")
+                .leftJoin(Event, "e", "e.season = m.event_season AND e.code = m.event_code")
+                .select("m.event_season", "eventSeason")
+                .addSelect("m.event_code", "eventCode")
+                .addSelect("m.id", "id")
+                .where("m.event_season = :season", { season })
+                .andWhere("NOT m.has_been_played")
+                .andWhere("m.scheduled_start_time IS NOT NULL")
+                .andWhere("m.scheduled_start_time > :start", { start })
+                .andWhere("m.scheduled_start_time < :end", { end });
+
+            if (elim !== null && elim !== undefined) {
+                if (elim) {
+                    q.andWhere("m.tournament_level <> :quals", { quals: TournamentLevel.Quals });
+                } else {
+                    q.andWhere("m.tournament_level = :quals", { quals: TournamentLevel.Quals });
+                }
+            }
+
+            q = applyEventFilters(q, { region, type, remote });
+
+            q.orderBy("m.scheduled_start_time", "ASC").limit(Math.min(limit ?? 50, 100));
+
+            const raw = await q.getRawMany();
+            const keys: MatchKey[] = raw.map((r) => ({
+                eventSeason: +r.eventSeason as Season,
+                eventCode: r.eventCode,
+                id: +r.id,
+            }));
+
+            return loadMatches(keys);
+        },
+    },
+
+    noteworthyMatches: {
+        type: NoteworthyMatchesGQL,
+        args: {
+            season: IntTy,
+            limit: nullTy(IntTy),
+            region: { type: RegionOptionGQL },
+            type: { type: EventTypeOptionGQL },
+            remote: { type: RemoteOptionGQL },
+        },
+        resolve: async (
+            _,
+            {
+                season,
+                limit,
+                region,
+                type,
+                remote,
+            }: {
+                season: number;
+                limit?: number | null;
+                region?: RegionOption | null;
+                type?: EventTypeOption | null;
+                remote?: RemoteOption | null;
+            }
+        ) => {
+            const descriptor = DESCRIPTORS[season as Season];
+            const scoreKey = descriptor.pensSubtract ? "totalPoints" : "totalPointsNp";
+            const ns = DATA_SOURCE.namingStrategy;
+            const scoreCol = ns.columnName(scoreKey, undefined, []);
+
+            const base = DATA_SOURCE.getRepository(Match)
+                .createQueryBuilder("m")
+                .innerJoin(
+                    `match_score_${season}`,
+                    "red",
+                    "m.event_season = red.season AND m.event_code = red.event_code AND m.id = red.match_id AND red.alliance = :red",
+                    { red: Alliance.Red }
+                )
+                .innerJoin(
+                    `match_score_${season}`,
+                    "blue",
+                    "m.event_season = blue.season AND m.event_code = blue.event_code AND m.id = blue.match_id AND blue.alliance = :blue",
+                    { blue: Alliance.Blue }
+                )
+                .leftJoin(Event, "e", "e.season = m.event_season AND e.code = m.event_code")
+                .select("m.event_season", "eventSeason")
+                .addSelect("m.event_code", "eventCode")
+                .addSelect("m.id", "id")
+                .where("m.event_season = :season", { season })
+                .andWhere("m.has_been_played")
+                .andWhere("NOT e.modified_rules");
+
+            const filtered = applyEventFilters(base, { region, type, remote });
+
+            const maxScoreExpr = `GREATEST(red.${scoreCol}, blue.${scoreCol})`;
+            const sumScoreExpr = `(red.${scoreCol} + blue.${scoreCol})`;
+            const losingScoreExpr = `LEAST(red.${scoreCol}, blue.${scoreCol})`;
+
+            const cap = Math.min(limit ?? 30, 100);
+
+            const highRaw = await filtered
+                .clone()
+                .orderBy(maxScoreExpr, "DESC")
+                .addOrderBy("m.scheduled_start_time", "ASC")
+                .limit(cap)
+                .getRawMany();
+
+            const combinedRaw = await filtered
+                .clone()
+                .orderBy(sumScoreExpr, "DESC")
+                .addOrderBy("m.scheduled_start_time", "ASC")
+                .limit(cap)
+                .getRawMany();
+
+            const losingRaw = await filtered
+                .clone()
+                .orderBy(losingScoreExpr, "DESC")
+                .addOrderBy("m.scheduled_start_time", "ASC")
+                .limit(cap)
+                .getRawMany();
+
+            const toKeys = (rows: any[]): MatchKey[] =>
+                rows.map((r) => ({
+                    eventSeason: +r.eventSeason as Season,
+                    eventCode: r.eventCode,
+                    id: +r.id,
+                }));
+
+            return {
+                highScore: await loadMatches(toKeys(highRaw)),
+                combinedScore: await loadMatches(toKeys(combinedRaw)),
+                losingScore: await loadMatches(toKeys(losingRaw)),
+            };
+        },
+    },
 };