Add timeline vector metrics
This commit is contained in:
1 parent
77ba93b94a
commit
a69e86f2bc
13 files changed
+1543
-37
No files matched your search
@@ -1,5 +1,5 @@
|
||||
import { Logger } from '@nestjs/common';
|
||||
import { FEATURE_SCHEMA_VERSION } from '@persona-lenz/shared';
|
||||
import { FEATURE_SCHEMA_VERSION, VECTOR_METRICS } from '@persona-lenz/shared';
|
||||
import type { ConnectionService } from '../global/database/connection.service';
|
||||
import type { Account } from '../global/database/schemas';
|
||||
import { RiotNotFoundError, type RiotApiClient } from '../riot/riot-api.client';
|
||||
@@ -8,6 +8,7 @@ import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { AnalysisPipelineService } from './analysis-pipeline.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
import { TimelineDerivedService } from './timeline-derived.service';
|
||||
import { TimelineMetricService } from './timeline-metric.service';
|
||||
|
||||
function createJobData(): UserAnalysisJobData {
|
||||
return {
|
||||
@@ -69,6 +70,15 @@ function createMatchPayload(matchId = 'KR_1') {
|
||||
kills: 10,
|
||||
totalDamageDealtToChampions: 30_000,
|
||||
},
|
||||
{
|
||||
participantId: 6,
|
||||
puuid: 'enemy-puuid',
|
||||
teamId: 200,
|
||||
teamPosition: 'MIDDLE',
|
||||
championId: 134,
|
||||
kills: 4,
|
||||
totalDamageDealtToChampions: 16_000,
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
@@ -85,7 +95,7 @@ function createTimelinePayload(
|
||||
},
|
||||
info: {
|
||||
frameInterval: 60_000,
|
||||
frames: events.length > 0 ? [{ timestamp: 0, events }] : [],
|
||||
frames: [{ timestamp: 0, events, participantFrames: {} }],
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -281,6 +291,7 @@ function createPipelineHarness(options: PipelineHarnessOptions = {}) {
|
||||
new FeatureExtractorService(),
|
||||
new ProfileBuilderService(),
|
||||
new TimelineDerivedService(),
|
||||
new TimelineMetricService(),
|
||||
),
|
||||
updateAnalysisJob,
|
||||
updatePlayerMatchFeature,
|
||||
@@ -400,6 +411,20 @@ describe('AnalysisPipelineService', () => {
|
||||
expect(timelineSet.timelineFetchedAt).toBeInstanceOf(Date);
|
||||
});
|
||||
|
||||
it('refetches cached timeline data when it is malformed', async () => {
|
||||
const { getMatchTimeline, service, updateRiotMatch } =
|
||||
createPipelineHarness({
|
||||
existingMatchRaw: createMatchPayload(),
|
||||
existingTimeline: {},
|
||||
});
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
expect(getMatchTimeline).toHaveBeenCalledWith('KR_1', 'asia');
|
||||
const timelineSet = findTimelineSet(updateRiotMatch);
|
||||
expect(timelineSet.timeline).toEqual(createTimelinePayload());
|
||||
});
|
||||
|
||||
it('stores derived timeline data when a timeline is available', async () => {
|
||||
const timeline = createTimelinePayloadWithFrames('KR_1', [
|
||||
{
|
||||
@@ -440,12 +465,18 @@ describe('AnalysisPipelineService', () => {
|
||||
{
|
||||
timestamp: 900_000,
|
||||
events: [
|
||||
{
|
||||
type: 'WARD_PLACED',
|
||||
timestamp: 850_000,
|
||||
creatorId: 1,
|
||||
},
|
||||
{
|
||||
type: 'ELITE_MONSTER_KILL',
|
||||
timestamp: 900_000,
|
||||
killerId: 4,
|
||||
killerTeamId: 100,
|
||||
monsterType: 'DRAGON',
|
||||
assistingParticipantIds: [1],
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -453,16 +484,39 @@ describe('AnalysisPipelineService', () => {
|
||||
const getMatchTimeline = jest
|
||||
.fn<Promise<Record<string, unknown>>, [string, string]>()
|
||||
.mockResolvedValue(timeline);
|
||||
const { service, updatePlayerMatchFeature } = createPipelineHarness({
|
||||
getMatchTimeline,
|
||||
});
|
||||
const { service, updatePlayerMatchFeature, updatePlayerProfile } =
|
||||
createPipelineHarness({
|
||||
getMatchTimeline,
|
||||
});
|
||||
|
||||
await service.processUserAnalysisJob(createJobData(), 'analysis-job-1');
|
||||
|
||||
const playerMatchFeatureSet = asRecord(
|
||||
asRecord(updatePlayerMatchFeature.mock.calls[0][1]).$set,
|
||||
);
|
||||
const playerMatchFeatureSetFeatures = asRecord(
|
||||
playerMatchFeatureSet.features,
|
||||
);
|
||||
const playerMatchFeatureSetNormalized = asRecord(
|
||||
playerMatchFeatureSet.normalized,
|
||||
);
|
||||
const playerMatchFeatureSetVector =
|
||||
playerMatchFeatureSet.vector as number[];
|
||||
expect(playerMatchFeatureSet.timelineProcessed).toBe(true);
|
||||
expect(playerMatchFeatureSetFeatures).toMatchObject({
|
||||
objectivePreWardRateNumerator: 1,
|
||||
objectivePreWardRateDenominator: 1,
|
||||
eliteObjectiveParticipationRateNumerator: 1,
|
||||
eliteObjectiveParticipationRateDenominator: 1,
|
||||
});
|
||||
expect(playerMatchFeatureSetNormalized.objectivePreWardRate).toBe(1);
|
||||
expect(
|
||||
playerMatchFeatureSetVector[
|
||||
VECTOR_METRICS.findIndex(
|
||||
(metric) => metric.id === 'objectivePreWardRate',
|
||||
)
|
||||
],
|
||||
).toBe(1);
|
||||
expect(playerMatchFeatureSet.derived).toEqual({
|
||||
fightClusters: [
|
||||
{
|
||||
@@ -524,6 +578,19 @@ describe('AnalysisPipelineService', () => {
|
||||
},
|
||||
],
|
||||
});
|
||||
const playerProfileSet = asRecord(
|
||||
asRecord(updatePlayerProfile.mock.calls[0][1]).$set,
|
||||
);
|
||||
const playerProfileSetProfile = asRecord(playerProfileSet.profile);
|
||||
const playerProfileSetVector = playerProfileSet.vector as number[];
|
||||
expect(playerProfileSetProfile.objectivePreWardRate).toBe(1);
|
||||
expect(
|
||||
playerProfileSetVector[
|
||||
VECTOR_METRICS.findIndex(
|
||||
(metric) => metric.id === 'objectivePreWardRate',
|
||||
)
|
||||
],
|
||||
).toBe(1);
|
||||
});
|
||||
|
||||
it('continues raw match analysis when timeline fetch fails', async () => {
|
||||
|
||||
@@ -22,6 +22,7 @@ import type {
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
import { TimelineDerivedService } from './timeline-derived.service';
|
||||
import { TimelineMetricService } from './timeline-metric.service';
|
||||
|
||||
interface MatchRecord {
|
||||
matchId: string;
|
||||
@@ -48,6 +49,14 @@ function isRecordValue(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function isTimelinePayload(value: unknown): value is Record<string, unknown> {
|
||||
if (!isRecordValue(value)) {
|
||||
return false;
|
||||
}
|
||||
const info = asRecord(value.info);
|
||||
return Array.isArray(info.frames) && info.frames.length > 0;
|
||||
}
|
||||
|
||||
function asNumber(value: unknown, fallback = 0): number {
|
||||
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
|
||||
}
|
||||
@@ -75,6 +84,7 @@ export class AnalysisPipelineService {
|
||||
private readonly featureExtractorService: FeatureExtractorService,
|
||||
private readonly profileBuilderService: ProfileBuilderService,
|
||||
private readonly timelineDerivedService: TimelineDerivedService,
|
||||
private readonly timelineMetricService: TimelineMetricService,
|
||||
) {}
|
||||
|
||||
public async processUserAnalysisJob(
|
||||
@@ -311,7 +321,7 @@ export class AnalysisPipelineService {
|
||||
existingTimeline: unknown,
|
||||
regionalRoute: UserAnalysisJobData['regionalRoute'],
|
||||
): Promise<Record<string, unknown> | undefined> {
|
||||
if (isRecordValue(existingTimeline)) {
|
||||
if (isTimelinePayload(existingTimeline)) {
|
||||
return existingTimeline;
|
||||
}
|
||||
|
||||
@@ -320,6 +330,12 @@ export class AnalysisPipelineService {
|
||||
matchId,
|
||||
regionalRoute,
|
||||
);
|
||||
if (!isTimelinePayload(timeline)) {
|
||||
this.logger.warn(
|
||||
`Skipping malformed timeline for matchId="${this.safeLogText(matchId)}"`,
|
||||
);
|
||||
return undefined;
|
||||
}
|
||||
await this.storeRiotMatchTimeline(matchId, timeline);
|
||||
return timeline;
|
||||
} catch (error) {
|
||||
@@ -366,12 +382,29 @@ export class AnalysisPipelineService {
|
||||
);
|
||||
if (feature.queueId !== queueId) continue;
|
||||
if (matchRecord.timeline) {
|
||||
feature.derived = {
|
||||
...this.timelineDerivedService.buildDerivedData(
|
||||
matchRecord.timeline,
|
||||
const derived = this.timelineDerivedService.buildDerivedData(
|
||||
matchRecord.timeline,
|
||||
matchRecord.raw,
|
||||
);
|
||||
const timelineMetrics =
|
||||
this.timelineMetricService.extractTimelineMetrics(
|
||||
feature,
|
||||
matchRecord.raw,
|
||||
),
|
||||
matchRecord.timeline,
|
||||
derived,
|
||||
);
|
||||
feature.derived = {
|
||||
...derived,
|
||||
};
|
||||
feature.features = {
|
||||
...feature.features,
|
||||
...timelineMetrics.features,
|
||||
};
|
||||
feature.normalized = {
|
||||
...feature.normalized,
|
||||
...timelineMetrics.normalized,
|
||||
};
|
||||
feature.vector = timelineMetrics.vector;
|
||||
feature.timelineProcessed = true;
|
||||
}
|
||||
|
||||
|
||||
@@ -131,7 +131,19 @@ describe('AnalysisReadService', () => {
|
||||
expect(profileFindOne).toHaveBeenCalledWith({
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
});
|
||||
expect(analysis.profile.playstyle.kda).toBe(0.8);
|
||||
expect(analysis.profile.playstyle.goldDiffAt10).toBeUndefined();
|
||||
expect(analysis.profile.playstyle.objectivePreWardRate).toBeUndefined();
|
||||
expect(
|
||||
analysis.strengths.some((metric) => metric.metricId === 'goldDiffAt10'),
|
||||
).toBe(false);
|
||||
expect(
|
||||
analysis.weaknesses.some(
|
||||
(metric) => metric.metricId === 'deathWithShutdownBountyGivenRate',
|
||||
),
|
||||
).toBe(false);
|
||||
expect(analysis.strengths).toEqual([
|
||||
{ metricId: 'deathsPerMin', value: 0.1 },
|
||||
{ metricId: 'kda', value: 0.8 },
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { Injectable, NotFoundException } from '@nestjs/common';
|
||||
import {
|
||||
FEATURE_SCHEMA_VERSION,
|
||||
METRICS,
|
||||
type AnalysisJobStatusDto,
|
||||
type MetricValueDto,
|
||||
@@ -90,11 +91,11 @@ export class AnalysisReadService {
|
||||
sampleGameCount: profile.sampleGameCount,
|
||||
championPool: profile.championPool,
|
||||
playstyle: Object.fromEntries(
|
||||
METRICS.map((metric) => [
|
||||
metric.id,
|
||||
this.clampMetricValue(profile.profile[metric.id]),
|
||||
Object.entries(profile.profile).map(([metricId, value]) => [
|
||||
metricId,
|
||||
this.clampMetricValue(value),
|
||||
]),
|
||||
) as PlayerAnalysisDto['profile']['playstyle'],
|
||||
),
|
||||
featureSchemaVersion: profile.featureSchemaVersion,
|
||||
confidence: profile.confidence,
|
||||
},
|
||||
@@ -118,7 +119,7 @@ export class AnalysisReadService {
|
||||
const playerProfileModel =
|
||||
await this.connectionService.getModel('playerProfile');
|
||||
return playerProfileModel
|
||||
.findOne({ puuid, queueId })
|
||||
.findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION })
|
||||
.lean<PlayerProfileRecord>()
|
||||
.exec();
|
||||
}
|
||||
@@ -127,8 +128,13 @@ export class AnalysisReadService {
|
||||
profile: Record<string, number>,
|
||||
direction: 'strength' | 'weakness',
|
||||
): MetricValueDto[] {
|
||||
return METRICS.map((metric) => {
|
||||
const value = this.clampMetricValue(profile[metric.id]);
|
||||
return METRICS.flatMap((metric) => {
|
||||
const rawValue = profile[metric.id];
|
||||
if (typeof rawValue !== 'number' || !Number.isFinite(rawValue)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const value = this.clampMetricValue(rawValue);
|
||||
return {
|
||||
metricId: metric.id,
|
||||
score: metric.direction === 'lowerIsBetter' ? 1 - value : value,
|
||||
|
||||
@@ -19,6 +19,7 @@ import { createBullMqOptions } from './bullmq.config';
|
||||
import { FeatureExtractorService } from './feature-extractor.service';
|
||||
import { ProfileBuilderService } from './profile-builder.service';
|
||||
import { TimelineDerivedService } from './timeline-derived.service';
|
||||
import { TimelineMetricService } from './timeline-metric.service';
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
@@ -50,6 +51,7 @@ import { TimelineDerivedService } from './timeline-derived.service';
|
||||
FeatureExtractorService,
|
||||
ProfileBuilderService,
|
||||
TimelineDerivedService,
|
||||
TimelineMetricService,
|
||||
],
|
||||
controllers: [AnalysisController],
|
||||
exports: [AnalysisQueueService, AnalysisPipelineService],
|
||||
|
||||
@@ -98,9 +98,9 @@ describe('FeatureExtractorService', () => {
|
||||
soloKills: 2,
|
||||
});
|
||||
expect(feature.vector).toEqual(
|
||||
VECTOR_METRICS.map((metric) => feature.normalized[metric.id]),
|
||||
VECTOR_METRICS.map((metric) => feature.normalized[metric.id] ?? 0),
|
||||
);
|
||||
expect(feature.vector).toHaveLength(12);
|
||||
expect(feature.vector).toHaveLength(VECTOR_METRICS.length);
|
||||
expect(feature.featureSchemaVersion).toBe(FEATURE_SCHEMA_VERSION);
|
||||
expect(feature.confidence).toBe(1);
|
||||
});
|
||||
|
||||
@@ -35,7 +35,7 @@ function createFeature(
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: 1,
|
||||
timelineProcessed: false,
|
||||
timelineProcessed: true,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
@@ -87,13 +87,16 @@ describe('ProfileBuilderService', () => {
|
||||
|
||||
expect(profile.mainRole).toBe('MIDDLE');
|
||||
expect(profile.sampleGameCount).toBe(2);
|
||||
for (const metric of METRICS) {
|
||||
for (const metric of METRICS.filter((metric) => metric.kind === 'scalar')) {
|
||||
expect(profile.profile[metric.id]).toBeCloseTo(
|
||||
(firstNormalized[metric.id] + secondNormalized[metric.id] * 0.5) / 1.5,
|
||||
);
|
||||
}
|
||||
for (const metric of METRICS.filter((metric) => metric.kind === 'ratio')) {
|
||||
expect(profile.profile[metric.id]).toBeUndefined();
|
||||
}
|
||||
expect(profile.vector).toEqual(
|
||||
VECTOR_METRICS.map((metric) => profile.profile[metric.id]),
|
||||
VECTOR_METRICS.map((metric) => profile.profile[metric.id] ?? 0),
|
||||
);
|
||||
expect(profile.championPool).toEqual([
|
||||
{ championId: 103, games: 1, wins: 1 },
|
||||
@@ -115,6 +118,20 @@ describe('ProfileBuilderService', () => {
|
||||
).toThrow('Cannot build a profile without match features.');
|
||||
});
|
||||
|
||||
it('discounts profile confidence when timeline metrics are missing', () => {
|
||||
const profile = service.buildProfile({
|
||||
features: [
|
||||
createFeature({ timelineProcessed: true }),
|
||||
createFeature({ matchId: 'KR_2', timelineProcessed: false }),
|
||||
],
|
||||
isSeed: false,
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
});
|
||||
|
||||
expect(profile.confidence).toBeCloseTo(0.34);
|
||||
});
|
||||
|
||||
it('aggregates ratio metrics from raw numerator and denominator counts', () => {
|
||||
const metrics: MetricDefinition[] = [
|
||||
{
|
||||
|
||||
@@ -18,6 +18,7 @@ type ProfileSourceFeature = Pick<
|
||||
| 'normalized'
|
||||
| 'patch'
|
||||
| 'role'
|
||||
| 'timelineProcessed'
|
||||
| 'win'
|
||||
>;
|
||||
|
||||
@@ -37,7 +38,7 @@ function toFiniteMetricValue(value: number | undefined): number {
|
||||
function aggregateScalarMetric(
|
||||
features: readonly ProfileSourceFeature[],
|
||||
metricId: string,
|
||||
): number {
|
||||
): number | undefined {
|
||||
let weightedSum = 0;
|
||||
let confidenceSum = 0;
|
||||
|
||||
@@ -52,7 +53,7 @@ function aggregateScalarMetric(
|
||||
}
|
||||
|
||||
if (confidenceSum <= 0) {
|
||||
return 0;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
return weightedSum / confidenceSum;
|
||||
@@ -61,7 +62,7 @@ function aggregateScalarMetric(
|
||||
function aggregateRatioMetric(
|
||||
features: readonly ProfileSourceFeature[],
|
||||
metricId: string,
|
||||
): number {
|
||||
): number | undefined {
|
||||
const numeratorKey = `${metricId}Numerator`;
|
||||
const denominatorKey = `${metricId}Denominator`;
|
||||
const numerator = features.reduce(
|
||||
@@ -75,7 +76,7 @@ function aggregateRatioMetric(
|
||||
);
|
||||
|
||||
if (denominator <= 0) {
|
||||
return 0;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
return numerator / denominator;
|
||||
@@ -88,10 +89,13 @@ export function buildProfileMetricValues(
|
||||
const profile: Record<string, number> = {};
|
||||
|
||||
for (const metric of metrics) {
|
||||
profile[metric.id] =
|
||||
const metricValue =
|
||||
metric.kind === 'ratio'
|
||||
? aggregateRatioMetric(features, metric.id)
|
||||
: aggregateScalarMetric(features, metric.id);
|
||||
if (metricValue !== undefined) {
|
||||
profile[metric.id] = metricValue;
|
||||
}
|
||||
}
|
||||
|
||||
return profile;
|
||||
@@ -151,6 +155,11 @@ export class ProfileBuilderService {
|
||||
params.features.length / 5,
|
||||
1,
|
||||
);
|
||||
const timelineCoverageMultiplier =
|
||||
0.7 +
|
||||
0.3 *
|
||||
(params.features.filter((feature) => feature.timelineProcessed).length /
|
||||
params.features.length);
|
||||
|
||||
return {
|
||||
puuid: params.puuid,
|
||||
@@ -168,7 +177,10 @@ export class ProfileBuilderService {
|
||||
vector: VECTOR_METRICS.map((metric) => profile[metric.id] ?? 0),
|
||||
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: averageConfidence * sampleSizeConfidenceMultiplier,
|
||||
confidence:
|
||||
averageConfidence *
|
||||
sampleSizeConfidenceMultiplier *
|
||||
timelineCoverageMultiplier,
|
||||
patches: [
|
||||
...new Set(params.features.map((feature) => feature.patch)),
|
||||
].sort(),
|
||||
|
||||
@@ -0,0 +1,342 @@
|
||||
import { VECTOR_METRICS } from '@persona-lenz/shared';
|
||||
import type { ExtractedPlayerMatchFeature } from './analysis.types';
|
||||
import { TimelineMetricService } from './timeline-metric.service';
|
||||
|
||||
function createBaseFeature(): ExtractedPlayerMatchFeature {
|
||||
return {
|
||||
matchId: 'KR_1',
|
||||
puuid: 'target-puuid',
|
||||
queueId: 420,
|
||||
role: 'MIDDLE',
|
||||
championId: 103,
|
||||
gameCreation: 1_700_000_000_000,
|
||||
gameDurationSec: 1_800,
|
||||
win: true,
|
||||
patch: '26.13',
|
||||
features: {
|
||||
kda: 3,
|
||||
},
|
||||
normalized: {
|
||||
kda: 0.5,
|
||||
},
|
||||
vector: [],
|
||||
featureSchemaVersion: 2,
|
||||
normalizationMethod: 'registry-baseline',
|
||||
confidence: 1,
|
||||
timelineProcessed: false,
|
||||
laneOpponent: {
|
||||
puuid: 'enemy-mid-puuid',
|
||||
championId: 134,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function createRawMatch() {
|
||||
return {
|
||||
metadata: {
|
||||
matchId: 'KR_1',
|
||||
},
|
||||
info: {
|
||||
participants: [
|
||||
{
|
||||
participantId: 1,
|
||||
puuid: 'target-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'MIDDLE',
|
||||
},
|
||||
{
|
||||
participantId: 2,
|
||||
puuid: 'ally-jungle-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'JUNGLE',
|
||||
},
|
||||
{
|
||||
participantId: 3,
|
||||
puuid: 'ally-top-puuid',
|
||||
teamId: 100,
|
||||
teamPosition: 'TOP',
|
||||
},
|
||||
{
|
||||
participantId: 6,
|
||||
puuid: 'enemy-mid-puuid',
|
||||
teamId: 200,
|
||||
teamPosition: 'MIDDLE',
|
||||
},
|
||||
{
|
||||
participantId: 7,
|
||||
puuid: 'enemy-jungle-puuid',
|
||||
teamId: 200,
|
||||
teamPosition: 'JUNGLE',
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function participantFrame(overrides: Record<string, unknown>) {
|
||||
return {
|
||||
jungleMinionsKilled: 0,
|
||||
minionsKilled: 0,
|
||||
position: { x: 0, y: 0 },
|
||||
timeEnemySpentControlled: 0,
|
||||
totalGold: 0,
|
||||
xp: 0,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function createTimeline() {
|
||||
return {
|
||||
info: {
|
||||
frames: [
|
||||
{
|
||||
timestamp: 8 * 60_000,
|
||||
events: [],
|
||||
participantFrames: {
|
||||
'1': participantFrame({ position: { x: 4_000, y: 4_000 } }),
|
||||
'2': participantFrame({ position: { x: 5_000, y: 4_000 } }),
|
||||
'3': participantFrame({ position: { x: 10_000, y: 4_000 } }),
|
||||
},
|
||||
},
|
||||
{
|
||||
timestamp: 10 * 60_000,
|
||||
events: [
|
||||
{
|
||||
type: 'CHAMPION_KILL',
|
||||
timestamp: 100_000,
|
||||
killerId: 1,
|
||||
victimId: 6,
|
||||
assistingParticipantIds: [2],
|
||||
},
|
||||
{
|
||||
type: 'CHAMPION_KILL',
|
||||
timestamp: 200_000,
|
||||
killerId: 2,
|
||||
victimId: 7,
|
||||
assistingParticipantIds: [1],
|
||||
},
|
||||
{
|
||||
type: 'CHAMPION_KILL',
|
||||
timestamp: 300_000,
|
||||
killerId: 2,
|
||||
victimId: 7,
|
||||
assistingParticipantIds: null,
|
||||
victimDamageReceived: [{ participantId: 1 }],
|
||||
},
|
||||
{
|
||||
type: 'CHAMPION_KILL',
|
||||
timestamp: 400_000,
|
||||
killerId: 6,
|
||||
victimId: 1,
|
||||
assistingParticipantIds: [],
|
||||
},
|
||||
{
|
||||
type: 'WARD_PLACED',
|
||||
timestamp: 500_000,
|
||||
creatorId: 1,
|
||||
},
|
||||
],
|
||||
participantFrames: {
|
||||
'1': participantFrame({
|
||||
jungleMinionsKilled: 5,
|
||||
minionsKilled: 75,
|
||||
position: { x: 4_000, y: 4_000 },
|
||||
timeEnemySpentControlled: 10_000,
|
||||
totalGold: 4_000,
|
||||
xp: 5_000,
|
||||
}),
|
||||
'2': participantFrame({ position: { x: 4_800, y: 4_000 } }),
|
||||
'3': participantFrame({ position: { x: 9_000, y: 4_000 } }),
|
||||
'6': participantFrame({
|
||||
jungleMinionsKilled: 0,
|
||||
minionsKilled: 70,
|
||||
totalGold: 3_500,
|
||||
xp: 4_500,
|
||||
}),
|
||||
},
|
||||
},
|
||||
{
|
||||
timestamp: 14 * 60_000,
|
||||
events: [
|
||||
{
|
||||
type: 'WARD_PLACED',
|
||||
timestamp: 830_000,
|
||||
creatorId: 1,
|
||||
},
|
||||
],
|
||||
participantFrames: {
|
||||
'1': participantFrame({
|
||||
position: { x: 4_000, y: 4_000 },
|
||||
timeEnemySpentControlled: 30_000,
|
||||
totalGold: 6_000,
|
||||
}),
|
||||
'2': participantFrame({ position: { x: 5_500, y: 4_000 } }),
|
||||
'3': participantFrame({ position: { x: 11_000, y: 4_000 } }),
|
||||
'6': participantFrame({
|
||||
totalGold: 6_200,
|
||||
}),
|
||||
},
|
||||
},
|
||||
{
|
||||
timestamp: 15 * 60_000,
|
||||
events: [
|
||||
{
|
||||
type: 'WARD_PLACED',
|
||||
timestamp: 850_000,
|
||||
creatorId: 1,
|
||||
},
|
||||
{
|
||||
type: 'ELITE_MONSTER_KILL',
|
||||
timestamp: 900_000,
|
||||
killerId: 2,
|
||||
killerTeamId: 100,
|
||||
monsterType: 'DRAGON',
|
||||
assistingParticipantIds: [1],
|
||||
},
|
||||
],
|
||||
participantFrames: {},
|
||||
},
|
||||
{
|
||||
timestamp: 20 * 60_000,
|
||||
events: [],
|
||||
participantFrames: {
|
||||
'1': participantFrame({
|
||||
position: { x: 4_000, y: 4_000 },
|
||||
timeEnemySpentControlled: 60_000,
|
||||
}),
|
||||
'2': participantFrame({ position: { x: 7_000, y: 4_000 } }),
|
||||
'3': participantFrame({ position: { x: 12_000, y: 4_000 } }),
|
||||
},
|
||||
},
|
||||
{
|
||||
timestamp: 30 * 60_000,
|
||||
events: [],
|
||||
participantFrames: {
|
||||
'1': participantFrame({
|
||||
timeEnemySpentControlled: 90_000,
|
||||
}),
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('TimelineMetricService', () => {
|
||||
const service = new TimelineMetricService();
|
||||
|
||||
it('extracts timeline vector metrics and ratio counts', () => {
|
||||
const feature = createBaseFeature();
|
||||
const result = service.extractTimelineMetrics(
|
||||
feature,
|
||||
createRawMatch(),
|
||||
createTimeline(),
|
||||
{
|
||||
advantageEvents: [],
|
||||
deathEvents: [
|
||||
{
|
||||
t: 400_000,
|
||||
victimParticipantId: 1,
|
||||
x: 4_000,
|
||||
y: 4_000,
|
||||
zone: 'middleLane',
|
||||
shutdownBountyGiven: 300,
|
||||
nearestAllyDistanceApprox: 1_500,
|
||||
},
|
||||
{
|
||||
t: 1_000_000,
|
||||
victimParticipantId: 1,
|
||||
x: 4_000,
|
||||
y: 4_000,
|
||||
zone: 'middleLane',
|
||||
shutdownBountyGiven: 0,
|
||||
nearestAllyDistanceApprox: 1_500,
|
||||
},
|
||||
],
|
||||
fightClusters: [
|
||||
{
|
||||
startTimeMs: 100_000,
|
||||
endTimeMs: 130_000,
|
||||
killCount: 3,
|
||||
participantIds: [1, 2, 6, 7],
|
||||
openerParticipantIds: [1],
|
||||
cleanupParticipantIds: [2],
|
||||
isTeamfight: true,
|
||||
},
|
||||
{
|
||||
startTimeMs: 600_000,
|
||||
endTimeMs: 640_000,
|
||||
killCount: 3,
|
||||
participantIds: [1, 2, 6, 7],
|
||||
openerParticipantIds: [2],
|
||||
cleanupParticipantIds: [1],
|
||||
isTeamfight: true,
|
||||
},
|
||||
],
|
||||
objectiveWindows: [
|
||||
{
|
||||
objectiveTimeMs: 900_000,
|
||||
startTimeMs: 780_000,
|
||||
endTimeMs: 930_000,
|
||||
killerParticipantId: 2,
|
||||
killerTeamId: 100,
|
||||
monsterType: 'DRAGON',
|
||||
},
|
||||
],
|
||||
roamFrames: [],
|
||||
},
|
||||
);
|
||||
|
||||
expect(result.features).toMatchObject({
|
||||
goldDiffAt10: 500,
|
||||
goldDiffAt14: -200,
|
||||
csDiffAt10: 10,
|
||||
xpDiffAt10: 500,
|
||||
deathsBefore14: 1,
|
||||
killParticipationBefore14: 1,
|
||||
earlyWardsPerMin: 2 / 14,
|
||||
objectivePreWardRateNumerator: 1,
|
||||
objectivePreWardRateDenominator: 1,
|
||||
eliteObjectiveParticipationRateNumerator: 1,
|
||||
eliteObjectiveParticipationRateDenominator: 1,
|
||||
teamfightFirstEngagementParticipationRateNumerator: 1,
|
||||
teamfightFirstEngagementParticipationRateDenominator: 2,
|
||||
teamfightCleanupKillParticipationRateNumerator: 1,
|
||||
teamfightCleanupKillParticipationRateDenominator: 2,
|
||||
deathWithShutdownBountyGivenRateNumerator: 1,
|
||||
deathWithShutdownBountyGivenRateDenominator: 2,
|
||||
ccTimePerMinute: 3,
|
||||
});
|
||||
expect(result.features.isolationTendency).toBeCloseTo(
|
||||
(1_000 + 800 + 1_500 + 3_000) / 4,
|
||||
);
|
||||
expect(result.normalized.objectivePreWardRate).toBe(1);
|
||||
expect(result.normalized.eliteObjectiveParticipationRate).toBe(1);
|
||||
expect(result.normalized.teamfightFirstEngagementParticipationRate).toBe(
|
||||
0.5,
|
||||
);
|
||||
expect(result.vector).toHaveLength(VECTOR_METRICS.length);
|
||||
expect(
|
||||
result.vector[
|
||||
VECTOR_METRICS.findIndex((metric) => metric.id === 'goldDiffAt10')
|
||||
],
|
||||
).toBeCloseTo(result.normalized.goldDiffAt10);
|
||||
expect(
|
||||
result.vector[
|
||||
VECTOR_METRICS.findIndex(
|
||||
(metric) => metric.id === 'objectivePreWardRate',
|
||||
)
|
||||
],
|
||||
).toBe(1);
|
||||
expect(
|
||||
result.vector[
|
||||
VECTOR_METRICS.findIndex(
|
||||
(metric) => metric.id === 'deathWithShutdownBountyGivenRate',
|
||||
)
|
||||
],
|
||||
).toBe(0.5);
|
||||
expect(result.vector[VECTOR_METRICS.length - 1]).toBe(
|
||||
result.normalized.ccTimePerMinute,
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,735 @@
|
||||
import {
|
||||
METRICS,
|
||||
VECTOR_METRICS,
|
||||
type MetricDefinition,
|
||||
type Role,
|
||||
} from '@persona-lenz/shared';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { ExtractedPlayerMatchFeature } from './analysis.types';
|
||||
import type {
|
||||
TimelineDeathEvent,
|
||||
TimelineDerivedData,
|
||||
TimelineFightCluster,
|
||||
TimelineObjectiveWindow,
|
||||
} from './timeline-derived.service';
|
||||
|
||||
interface TimelinePosition {
|
||||
x: number;
|
||||
y: number;
|
||||
}
|
||||
|
||||
interface MatchParticipant {
|
||||
participantId: number;
|
||||
puuid?: string;
|
||||
teamId?: 100 | 200;
|
||||
teamPosition?: string;
|
||||
}
|
||||
|
||||
interface TimelineParticipantFrame {
|
||||
participantId: number;
|
||||
position?: TimelinePosition;
|
||||
totalGold?: number;
|
||||
xp?: number;
|
||||
minionsKilled?: number;
|
||||
jungleMinionsKilled?: number;
|
||||
timeEnemySpentControlled?: number;
|
||||
}
|
||||
|
||||
interface TimelineFrame {
|
||||
timestamp: number;
|
||||
events: Record<string, unknown>[];
|
||||
participantFrames: Map<number, TimelineParticipantFrame>;
|
||||
}
|
||||
|
||||
interface TimelineMetricContext {
|
||||
allyParticipantIds: number[];
|
||||
derived: TimelineDerivedData;
|
||||
feature: ExtractedPlayerMatchFeature;
|
||||
frames: TimelineFrame[];
|
||||
gameMinutes: number;
|
||||
laneOpponentParticipantId?: number;
|
||||
participantId: number;
|
||||
participants: MatchParticipant[];
|
||||
teamId: 100 | 200;
|
||||
}
|
||||
|
||||
export interface TimelineMetricExtractionResult {
|
||||
features: Record<string, number>;
|
||||
normalized: Record<string, number>;
|
||||
vector: number[];
|
||||
}
|
||||
|
||||
const TEN_MINUTES_MS = 10 * 60_000;
|
||||
const FOURTEEN_MINUTES_MS = 14 * 60_000;
|
||||
const TWENTY_MINUTES_MS = 20 * 60_000;
|
||||
const FRAME_MATCH_TOLERANCE_MS = 30_000;
|
||||
const OBJECTIVE_PRE_WARD_WINDOW_MS = 60_000;
|
||||
const OBJECTIVE_MONSTER_TYPES = new Set([
|
||||
'DRAGON',
|
||||
'RIFTHERALD',
|
||||
'BARON_NASHOR',
|
||||
]);
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> {
|
||||
if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
return {};
|
||||
}
|
||||
|
||||
function asArray(value: unknown): unknown[] {
|
||||
return Array.isArray(value) ? value : [];
|
||||
}
|
||||
|
||||
function asNumber(value: unknown): number | undefined {
|
||||
return typeof value === 'number' && Number.isFinite(value)
|
||||
? value
|
||||
: undefined;
|
||||
}
|
||||
|
||||
function asString(value: unknown): string | undefined {
|
||||
return typeof value === 'string' ? value : undefined;
|
||||
}
|
||||
|
||||
function asParticipantId(value: unknown): number | undefined {
|
||||
const participantId = asNumber(value);
|
||||
return participantId !== undefined && participantId > 0
|
||||
? participantId
|
||||
: undefined;
|
||||
}
|
||||
|
||||
function asTeamId(value: unknown): 100 | 200 | undefined {
|
||||
const teamId = asNumber(value);
|
||||
return teamId === 100 || teamId === 200 ? teamId : undefined;
|
||||
}
|
||||
|
||||
function asParticipantIds(value: unknown): number[] {
|
||||
return asArray(value).flatMap((item) => {
|
||||
const participantId = asParticipantId(item);
|
||||
return participantId === undefined ? [] : [participantId];
|
||||
});
|
||||
}
|
||||
|
||||
function victimDamageReceivedParticipantIds(value: unknown): number[] {
|
||||
return asArray(value).flatMap((item) => {
|
||||
const participantId = asParticipantId(asRecord(item).participantId);
|
||||
return participantId === undefined ? [] : [participantId];
|
||||
});
|
||||
}
|
||||
|
||||
function parsePosition(value: unknown): TimelinePosition | undefined {
|
||||
const position = asRecord(value);
|
||||
const x = asNumber(position.x);
|
||||
const y = asNumber(position.y);
|
||||
if (x === undefined || y === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
return { x, y };
|
||||
}
|
||||
|
||||
function parseParticipants(
|
||||
rawMatch: Record<string, unknown>,
|
||||
): MatchParticipant[] {
|
||||
const info = asRecord(rawMatch.info);
|
||||
return asArray(info.participants)
|
||||
.map(asRecord)
|
||||
.flatMap((participant) => {
|
||||
const participantId = asParticipantId(participant.participantId);
|
||||
if (participantId === undefined) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return [
|
||||
{
|
||||
participantId,
|
||||
puuid: asString(participant.puuid),
|
||||
teamId: asTeamId(participant.teamId),
|
||||
teamPosition: asString(participant.teamPosition),
|
||||
},
|
||||
];
|
||||
});
|
||||
}
|
||||
|
||||
function parseFrames(timeline: Record<string, unknown>): TimelineFrame[] {
|
||||
const info = asRecord(timeline.info);
|
||||
return asArray(info.frames)
|
||||
.map(asRecord)
|
||||
.flatMap((frame) => {
|
||||
const timestamp = asNumber(frame.timestamp);
|
||||
if (timestamp === undefined) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const participantFrames = new Map<number, TimelineParticipantFrame>();
|
||||
for (const [participantIdValue, participantFrameValue] of Object.entries(
|
||||
asRecord(frame.participantFrames),
|
||||
)) {
|
||||
const participantId = asParticipantId(Number(participantIdValue));
|
||||
if (participantId === undefined) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const participantFrame = asRecord(participantFrameValue);
|
||||
participantFrames.set(participantId, {
|
||||
participantId,
|
||||
position: parsePosition(participantFrame.position),
|
||||
totalGold: asNumber(participantFrame.totalGold),
|
||||
xp: asNumber(participantFrame.xp),
|
||||
minionsKilled: asNumber(participantFrame.minionsKilled),
|
||||
jungleMinionsKilled: asNumber(participantFrame.jungleMinionsKilled),
|
||||
timeEnemySpentControlled: asNumber(
|
||||
participantFrame.timeEnemySpentControlled,
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
return [
|
||||
{
|
||||
timestamp,
|
||||
events: asArray(frame.events).map(asRecord),
|
||||
participantFrames,
|
||||
},
|
||||
];
|
||||
})
|
||||
.sort((left, right) => left.timestamp - right.timestamp);
|
||||
}
|
||||
|
||||
function normalizeMetric(
|
||||
metric: MetricDefinition,
|
||||
role: Role,
|
||||
rawValue: number,
|
||||
): number {
|
||||
const baseline = metric.baseline?.[role];
|
||||
if (!baseline) {
|
||||
return Math.max(0, Math.min(1, rawValue));
|
||||
}
|
||||
return Math.max(
|
||||
0,
|
||||
Math.min(1, (rawValue - baseline.min) / (baseline.max - baseline.min)),
|
||||
);
|
||||
}
|
||||
|
||||
function normalizationRole(role: ExtractedPlayerMatchFeature['role']): Role {
|
||||
return role === 'UNKNOWN' ? 'MIDDLE' : role;
|
||||
}
|
||||
|
||||
function findMetric(metricId: string): MetricDefinition | undefined {
|
||||
return METRICS.find((metric) => metric.id === metricId);
|
||||
}
|
||||
|
||||
function findClosestFrame(
|
||||
frames: TimelineFrame[],
|
||||
timestampMs: number,
|
||||
): TimelineFrame | undefined {
|
||||
let selected: TimelineFrame | undefined;
|
||||
let selectedDistance = Number.POSITIVE_INFINITY;
|
||||
|
||||
for (const frame of frames) {
|
||||
const distanceMs = Math.abs(frame.timestamp - timestampMs);
|
||||
if (distanceMs < selectedDistance) {
|
||||
selected = frame;
|
||||
selectedDistance = distanceMs;
|
||||
}
|
||||
}
|
||||
|
||||
return selectedDistance <= FRAME_MATCH_TOLERANCE_MS ? selected : undefined;
|
||||
}
|
||||
|
||||
function participantTeamId(
|
||||
participants: MatchParticipant[],
|
||||
participantId: number | undefined,
|
||||
): 100 | 200 | undefined {
|
||||
if (participantId === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
return participants.find(
|
||||
(participant) => participant.participantId === participantId,
|
||||
)?.teamId;
|
||||
}
|
||||
|
||||
function eventTeamId(
|
||||
event: Record<string, unknown>,
|
||||
participants: MatchParticipant[],
|
||||
): 100 | 200 | undefined {
|
||||
return (
|
||||
asTeamId(event.killerTeamId) ??
|
||||
participantTeamId(participants, asParticipantId(event.killerId))
|
||||
);
|
||||
}
|
||||
|
||||
function eventInvolvesParticipant(
|
||||
event: Record<string, unknown>,
|
||||
participantId: number,
|
||||
): boolean {
|
||||
return (
|
||||
asParticipantId(event.killerId) === participantId ||
|
||||
asParticipantIds(event.assistingParticipantIds).includes(participantId) ||
|
||||
victimDamageReceivedParticipantIds(event.victimDamageReceived).includes(
|
||||
participantId,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function isChampionKillBefore14(event: Record<string, unknown>): boolean {
|
||||
return (
|
||||
asString(event.type) === 'CHAMPION_KILL' &&
|
||||
(asNumber(event.timestamp) ?? Number.POSITIVE_INFINITY) <
|
||||
FOURTEEN_MINUTES_MS
|
||||
);
|
||||
}
|
||||
|
||||
function isObjectiveMonsterEvent(event: Record<string, unknown>): boolean {
|
||||
return (
|
||||
asString(event.type) === 'ELITE_MONSTER_KILL' &&
|
||||
OBJECTIVE_MONSTER_TYPES.has(asString(event.monsterType) ?? '')
|
||||
);
|
||||
}
|
||||
|
||||
function distance(left: TimelinePosition, right: TimelinePosition): number {
|
||||
return Math.hypot(left.x - right.x, left.y - right.y);
|
||||
}
|
||||
|
||||
function csAt(frame: TimelineParticipantFrame | undefined): number | undefined {
|
||||
if (!frame) {
|
||||
return undefined;
|
||||
}
|
||||
return (frame.minionsKilled ?? 0) + (frame.jungleMinionsKilled ?? 0);
|
||||
}
|
||||
|
||||
function objectiveWindowTeamId(
|
||||
window: TimelineObjectiveWindow,
|
||||
participants: MatchParticipant[],
|
||||
): 100 | 200 | undefined {
|
||||
return (
|
||||
asTeamId(window.killerTeamId) ??
|
||||
participantTeamId(participants, window.killerParticipantId)
|
||||
);
|
||||
}
|
||||
|
||||
function scoreParticipantDeath(event: TimelineDeathEvent): number {
|
||||
return event.shutdownBountyGiven > 0 ? 1 : 0;
|
||||
}
|
||||
|
||||
function finalParticipantFrame(
|
||||
frames: TimelineFrame[],
|
||||
participantId: number,
|
||||
): TimelineParticipantFrame | undefined {
|
||||
for (let index = frames.length - 1; index >= 0; index -= 1) {
|
||||
const frame = frames[index].participantFrames.get(participantId);
|
||||
if (frame) {
|
||||
return frame;
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class TimelineMetricService {
|
||||
public extractTimelineMetrics(
|
||||
feature: ExtractedPlayerMatchFeature,
|
||||
rawMatch: Record<string, unknown>,
|
||||
timeline: Record<string, unknown>,
|
||||
derived: TimelineDerivedData,
|
||||
): TimelineMetricExtractionResult {
|
||||
const participants = parseParticipants(rawMatch);
|
||||
const participant = participants.find(
|
||||
(candidate) => candidate.puuid === feature.puuid,
|
||||
);
|
||||
if (!participant?.participantId || !participant.teamId) {
|
||||
return this.emptyResult(feature.normalized);
|
||||
}
|
||||
|
||||
const context: TimelineMetricContext = {
|
||||
allyParticipantIds: participants
|
||||
.filter(
|
||||
(candidate) =>
|
||||
candidate.teamId === participant.teamId &&
|
||||
candidate.participantId !== participant.participantId,
|
||||
)
|
||||
.map((candidate) => candidate.participantId),
|
||||
derived,
|
||||
feature,
|
||||
frames: parseFrames(timeline),
|
||||
gameMinutes: Math.max(feature.gameDurationSec / 60, 1),
|
||||
laneOpponentParticipantId: feature.laneOpponent
|
||||
? participants.find(
|
||||
(candidate) => candidate.puuid === feature.laneOpponent?.puuid,
|
||||
)?.participantId
|
||||
: undefined,
|
||||
participantId: participant.participantId,
|
||||
participants,
|
||||
teamId: participant.teamId,
|
||||
};
|
||||
|
||||
const features: Record<string, number> = {};
|
||||
const normalized: Record<string, number> = {};
|
||||
|
||||
this.addEarlyLaneMetrics(context, features, normalized);
|
||||
this.addEarlyEventMetrics(context, features, normalized);
|
||||
this.addObjectiveMetrics(context, features, normalized);
|
||||
this.addIsolationMetric(context, features, normalized);
|
||||
this.addTeamfightMetrics(context, features, normalized);
|
||||
this.addDeathRiskMetric(context, features, normalized);
|
||||
this.addCrowdControlMetric(context, features, normalized);
|
||||
|
||||
const mergedNormalized = { ...feature.normalized, ...normalized };
|
||||
return {
|
||||
features,
|
||||
normalized,
|
||||
vector: VECTOR_METRICS.map((metric) => mergedNormalized[metric.id] ?? 0),
|
||||
};
|
||||
}
|
||||
|
||||
private emptyResult(
|
||||
existingNormalized: Record<string, number>,
|
||||
): TimelineMetricExtractionResult {
|
||||
return {
|
||||
features: {},
|
||||
normalized: {},
|
||||
vector: VECTOR_METRICS.map(
|
||||
(metric) => existingNormalized[metric.id] ?? 0,
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
private addScalarMetric(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
metricId: string,
|
||||
rawValue: number | undefined,
|
||||
): void {
|
||||
if (rawValue === undefined || !Number.isFinite(rawValue)) {
|
||||
return;
|
||||
}
|
||||
|
||||
const metric = findMetric(metricId);
|
||||
if (!metric) {
|
||||
return;
|
||||
}
|
||||
|
||||
features[metricId] = rawValue;
|
||||
normalized[metricId] = normalizeMetric(
|
||||
metric,
|
||||
normalizationRole(context.feature.role),
|
||||
rawValue,
|
||||
);
|
||||
}
|
||||
|
||||
private addRatioMetric(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
metricId: string,
|
||||
numerator: number,
|
||||
denominator: number,
|
||||
): void {
|
||||
features[`${metricId}Numerator`] = numerator;
|
||||
features[`${metricId}Denominator`] = denominator;
|
||||
if (denominator <= 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
const metric = findMetric(metricId);
|
||||
if (!metric) {
|
||||
return;
|
||||
}
|
||||
|
||||
normalized[metricId] = normalizeMetric(
|
||||
metric,
|
||||
normalizationRole(context.feature.role),
|
||||
numerator / denominator,
|
||||
);
|
||||
}
|
||||
|
||||
private addEarlyLaneMetrics(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
if (!context.laneOpponentParticipantId) {
|
||||
return;
|
||||
}
|
||||
|
||||
const frameAt10 = findClosestFrame(context.frames, TEN_MINUTES_MS);
|
||||
const participantAt10 = frameAt10?.participantFrames.get(
|
||||
context.participantId,
|
||||
);
|
||||
const opponentAt10 = frameAt10?.participantFrames.get(
|
||||
context.laneOpponentParticipantId,
|
||||
);
|
||||
const frameAt14 = findClosestFrame(context.frames, FOURTEEN_MINUTES_MS);
|
||||
const participantAt14 = frameAt14?.participantFrames.get(
|
||||
context.participantId,
|
||||
);
|
||||
const opponentAt14 = frameAt14?.participantFrames.get(
|
||||
context.laneOpponentParticipantId,
|
||||
);
|
||||
const playerCsAt10 = csAt(participantAt10);
|
||||
const opponentCsAt10 = csAt(opponentAt10);
|
||||
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'goldDiffAt10',
|
||||
participantAt10?.totalGold !== undefined &&
|
||||
opponentAt10?.totalGold !== undefined
|
||||
? participantAt10.totalGold - opponentAt10.totalGold
|
||||
: undefined,
|
||||
);
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'goldDiffAt14',
|
||||
participantAt14?.totalGold !== undefined &&
|
||||
opponentAt14?.totalGold !== undefined
|
||||
? participantAt14.totalGold - opponentAt14.totalGold
|
||||
: undefined,
|
||||
);
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'csDiffAt10',
|
||||
playerCsAt10 !== undefined && opponentCsAt10 !== undefined
|
||||
? playerCsAt10 - opponentCsAt10
|
||||
: undefined,
|
||||
);
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'xpDiffAt10',
|
||||
participantAt10?.xp !== undefined && opponentAt10?.xp !== undefined
|
||||
? participantAt10.xp - opponentAt10.xp
|
||||
: undefined,
|
||||
);
|
||||
}
|
||||
|
||||
private addEarlyEventMetrics(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const earlyKillEvents = context.frames
|
||||
.flatMap((frame) => frame.events)
|
||||
.filter(isChampionKillBefore14);
|
||||
const teamEarlyKillEvents = earlyKillEvents.filter(
|
||||
(event) => eventTeamId(event, context.participants) === context.teamId,
|
||||
);
|
||||
const earlyKillParticipationCount = teamEarlyKillEvents.filter((event) =>
|
||||
eventInvolvesParticipant(event, context.participantId),
|
||||
).length;
|
||||
const deathsBefore14 = earlyKillEvents.filter(
|
||||
(event) => asParticipantId(event.victimId) === context.participantId,
|
||||
).length;
|
||||
const earlyWardCount = context.frames
|
||||
.flatMap((frame) => frame.events)
|
||||
.filter(
|
||||
(event) =>
|
||||
asString(event.type) === 'WARD_PLACED' &&
|
||||
(asNumber(event.timestamp) ?? Number.POSITIVE_INFINITY) <
|
||||
FOURTEEN_MINUTES_MS &&
|
||||
asParticipantId(event.creatorId) === context.participantId,
|
||||
).length;
|
||||
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'deathsBefore14',
|
||||
deathsBefore14,
|
||||
);
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'killParticipationBefore14',
|
||||
teamEarlyKillEvents.length > 0
|
||||
? earlyKillParticipationCount / teamEarlyKillEvents.length
|
||||
: undefined,
|
||||
);
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'earlyWardsPerMin',
|
||||
earlyWardCount / 14,
|
||||
);
|
||||
}
|
||||
|
||||
private addObjectiveMetrics(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const events = context.frames.flatMap((frame) => frame.events);
|
||||
const wardEvents = events.filter(
|
||||
(event) =>
|
||||
asString(event.type) === 'WARD_PLACED' &&
|
||||
asParticipantId(event.creatorId) === context.participantId,
|
||||
);
|
||||
const ownObjectiveWindows = context.derived.objectiveWindows.filter(
|
||||
(window) =>
|
||||
objectiveWindowTeamId(window, context.participants) === context.teamId,
|
||||
);
|
||||
const objectivePreWardCount = ownObjectiveWindows.filter((window) =>
|
||||
wardEvents.some((event) => {
|
||||
const timestamp = asNumber(event.timestamp);
|
||||
return (
|
||||
timestamp !== undefined &&
|
||||
timestamp >= window.objectiveTimeMs - OBJECTIVE_PRE_WARD_WINDOW_MS &&
|
||||
timestamp <= window.objectiveTimeMs
|
||||
);
|
||||
}),
|
||||
).length;
|
||||
|
||||
const ownEliteObjectiveEvents = events.filter(
|
||||
(event) =>
|
||||
isObjectiveMonsterEvent(event) &&
|
||||
eventTeamId(event, context.participants) === context.teamId,
|
||||
);
|
||||
const eliteObjectiveParticipationCount = ownEliteObjectiveEvents.filter(
|
||||
(event) => eventInvolvesParticipant(event, context.participantId),
|
||||
).length;
|
||||
|
||||
this.addRatioMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'objectivePreWardRate',
|
||||
objectivePreWardCount,
|
||||
ownObjectiveWindows.length,
|
||||
);
|
||||
this.addRatioMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'eliteObjectiveParticipationRate',
|
||||
eliteObjectiveParticipationCount,
|
||||
ownEliteObjectiveEvents.length,
|
||||
);
|
||||
}
|
||||
|
||||
private addIsolationMetric(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const nearestDistances = context.frames.flatMap((frame) => {
|
||||
if (frame.timestamp < 8 * 60_000 || frame.timestamp > TWENTY_MINUTES_MS) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const participantPosition = frame.participantFrames.get(
|
||||
context.participantId,
|
||||
)?.position;
|
||||
if (!participantPosition) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const allyDistances = context.allyParticipantIds.flatMap((allyId) => {
|
||||
const allyPosition = frame.participantFrames.get(allyId)?.position;
|
||||
return allyPosition
|
||||
? [distance(participantPosition, allyPosition)]
|
||||
: [];
|
||||
});
|
||||
if (allyDistances.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return [Math.min(...allyDistances)];
|
||||
});
|
||||
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'isolationTendency',
|
||||
nearestDistances.length > 0
|
||||
? nearestDistances.reduce((sum, value) => sum + value, 0) /
|
||||
nearestDistances.length
|
||||
: undefined,
|
||||
);
|
||||
}
|
||||
|
||||
private addTeamfightMetrics(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const teamfights = context.derived.fightClusters.filter(
|
||||
(cluster: TimelineFightCluster) => cluster.isTeamfight,
|
||||
);
|
||||
const firstEngagementCount = teamfights.filter((cluster) =>
|
||||
cluster.openerParticipantIds.includes(context.participantId),
|
||||
).length;
|
||||
const cleanupCount = teamfights.filter((cluster) =>
|
||||
cluster.cleanupParticipantIds.includes(context.participantId),
|
||||
).length;
|
||||
|
||||
this.addRatioMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'teamfightFirstEngagementParticipationRate',
|
||||
firstEngagementCount,
|
||||
teamfights.length,
|
||||
);
|
||||
this.addRatioMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'teamfightCleanupKillParticipationRate',
|
||||
cleanupCount,
|
||||
teamfights.length,
|
||||
);
|
||||
}
|
||||
|
||||
private addDeathRiskMetric(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const ownDeaths = context.derived.deathEvents.filter(
|
||||
(event) => event.victimParticipantId === context.participantId,
|
||||
);
|
||||
const shutdownDeaths = ownDeaths.reduce(
|
||||
(sum, event) => sum + scoreParticipantDeath(event),
|
||||
0,
|
||||
);
|
||||
|
||||
this.addRatioMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'deathWithShutdownBountyGivenRate',
|
||||
shutdownDeaths,
|
||||
ownDeaths.length,
|
||||
);
|
||||
}
|
||||
|
||||
private addCrowdControlMetric(
|
||||
context: TimelineMetricContext,
|
||||
features: Record<string, number>,
|
||||
normalized: Record<string, number>,
|
||||
): void {
|
||||
const finalFrame = finalParticipantFrame(
|
||||
context.frames,
|
||||
context.participantId,
|
||||
);
|
||||
const controlledMs = finalFrame?.timeEnemySpentControlled;
|
||||
|
||||
this.addScalarMetric(
|
||||
context,
|
||||
features,
|
||||
normalized,
|
||||
'ccTimePerMinute',
|
||||
controlledMs === undefined
|
||||
? undefined
|
||||
: controlledMs / 1_000 / context.gameMinutes,
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -25,24 +25,76 @@ const MVP_1_METRIC_IDS = [
|
||||
'objectiveParticipation',
|
||||
'soloKills',
|
||||
];
|
||||
const MVP_2_TIMELINE_METRIC_IDS = [
|
||||
'goldDiffAt10',
|
||||
'goldDiffAt14',
|
||||
'csDiffAt10',
|
||||
'xpDiffAt10',
|
||||
'deathsBefore14',
|
||||
'killParticipationBefore14',
|
||||
'earlyWardsPerMin',
|
||||
'objectivePreWardRate',
|
||||
'eliteObjectiveParticipationRate',
|
||||
'isolationTendency',
|
||||
'teamfightFirstEngagementParticipationRate',
|
||||
'teamfightCleanupKillParticipationRate',
|
||||
'deathWithShutdownBountyGivenRate',
|
||||
'ccTimePerMinute',
|
||||
];
|
||||
const MVP_2_METRIC_IDS = [...MVP_1_METRIC_IDS, ...MVP_2_TIMELINE_METRIC_IDS];
|
||||
const MVP_2_TIMELINE_METRIC_CONTRACTS = [
|
||||
{ id: 'goldDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
{ id: 'goldDiffAt14', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
{ id: 'csDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
{ id: 'xpDiffAt10', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
{ id: 'deathsBefore14', kind: 'scalar', direction: 'lowerIsBetter' },
|
||||
{
|
||||
id: 'killParticipationBefore14',
|
||||
kind: 'scalar',
|
||||
direction: 'higherIsBetter',
|
||||
},
|
||||
{ id: 'earlyWardsPerMin', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
{ id: 'objectivePreWardRate', kind: 'ratio', direction: 'higherIsBetter' },
|
||||
{
|
||||
id: 'eliteObjectiveParticipationRate',
|
||||
kind: 'ratio',
|
||||
direction: 'higherIsBetter',
|
||||
},
|
||||
{ id: 'isolationTendency', kind: 'scalar', direction: 'lowerIsBetter' },
|
||||
{
|
||||
id: 'teamfightFirstEngagementParticipationRate',
|
||||
kind: 'ratio',
|
||||
direction: 'higherIsBetter',
|
||||
},
|
||||
{
|
||||
id: 'teamfightCleanupKillParticipationRate',
|
||||
kind: 'ratio',
|
||||
direction: 'higherIsBetter',
|
||||
},
|
||||
{
|
||||
id: 'deathWithShutdownBountyGivenRate',
|
||||
kind: 'ratio',
|
||||
direction: 'lowerIsBetter',
|
||||
},
|
||||
{ id: 'ccTimePerMinute', kind: 'scalar', direction: 'higherIsBetter' },
|
||||
] as const;
|
||||
|
||||
describe('shared feature registry', () => {
|
||||
it('defines MVP 1 vector metrics in the documented order', () => {
|
||||
expect(FEATURE_SCHEMA_VERSION).toBe(1);
|
||||
expect(METRICS.map((metric) => metric.id)).toEqual(MVP_1_METRIC_IDS);
|
||||
expect(VECTOR_DIMENSION).toBe(12);
|
||||
it('defines MVP 2 vector metrics in the documented order', () => {
|
||||
expect(FEATURE_SCHEMA_VERSION).toBe(2);
|
||||
expect(METRICS.map((metric) => metric.id)).toEqual(MVP_2_METRIC_IDS);
|
||||
expect(VECTOR_DIMENSION).toBe(26);
|
||||
expect(METRICS.filter((metric) => metric.includeInVector)).toHaveLength(
|
||||
VECTOR_DIMENSION,
|
||||
);
|
||||
});
|
||||
|
||||
it('keeps metric ids unique and every MVP 1 metric normalizable by role', () => {
|
||||
it('keeps metric ids unique and every vector metric normalizable by role', () => {
|
||||
const metricIds = METRICS.map((metric) => metric.id);
|
||||
|
||||
expect(new Set(metricIds).size).toBe(metricIds.length);
|
||||
for (const metric of METRICS) {
|
||||
expect(metric.label).toBeTruthy();
|
||||
expect(metric.kind).toBe('scalar');
|
||||
expect(metric.includeInVector).toBe(true);
|
||||
expect(metric.baseline).toBeDefined();
|
||||
expect(Object.keys(metric.baseline ?? {}).sort()).toEqual([
|
||||
@@ -63,6 +115,29 @@ describe('shared feature registry', () => {
|
||||
expect(
|
||||
METRICS.find((metric) => metric.id === 'deathsPerMin')?.direction,
|
||||
).toBe('lowerIsBetter');
|
||||
expect(
|
||||
METRICS.find((metric) => metric.id === 'deathWithShutdownBountyGivenRate')
|
||||
?.direction,
|
||||
).toBe('lowerIsBetter');
|
||||
});
|
||||
|
||||
it('defines MVP 2 timeline metric aggregation contracts', () => {
|
||||
expect(
|
||||
MVP_2_TIMELINE_METRIC_IDS.map((metricId) => {
|
||||
const metric = METRICS.find((candidate) => candidate.id === metricId);
|
||||
return {
|
||||
id: metric?.id,
|
||||
kind: metric?.kind,
|
||||
direction: metric?.direction,
|
||||
includeInVector: metric?.includeInVector,
|
||||
};
|
||||
}),
|
||||
).toEqual(
|
||||
MVP_2_TIMELINE_METRIC_CONTRACTS.map((metric) => ({
|
||||
...metric,
|
||||
includeInVector: true,
|
||||
})),
|
||||
);
|
||||
});
|
||||
|
||||
it('defines shared advantage event weights for timeline-derived metrics', () => {
|
||||
@@ -127,7 +202,7 @@ describe('shared DTO contracts', () => {
|
||||
status: 'queued',
|
||||
};
|
||||
const playstyle = Object.fromEntries(
|
||||
MVP_1_METRIC_IDS.map((metricId) => [metricId, 0.5]),
|
||||
MVP_2_METRIC_IDS.map((metricId) => [metricId, 0.5]),
|
||||
) as PlayerAnalysisDto['profile']['playstyle'];
|
||||
const analysis: PlayerAnalysisDto = {
|
||||
account: {
|
||||
|
||||
Reference in new issue
Block a user