Files
persona-lenz/apps/api/src/modules/analysis/metric-normalization.service.ts
T

167 lines
4.8 KiB
TypeScript

import { Injectable } from '@nestjs/common';
import { FEATURE_SCHEMA_VERSION, VECTOR_METRICS } from '@persona-lenz/shared';
import { ConnectionService } from '../global/database/connection.service';
import type {
BaselineCohort,
MetricBaseline,
TeamPosition,
} from '../global/database/schemas';
import type { ExtractedPlayerMatchFeature } from './analysis.types';
interface NormalizeFeatureOptions {
cohort?: BaselineCohort;
}
const BASELINE_PERCENTILE_RANKS = Array.from(
{ length: 19 },
(_, index) => (index + 1) * 0.05,
);
const TEAM_POSITIONS = ['TOP', 'JUNGLE', 'MIDDLE', 'BOTTOM', 'UTILITY'];
function isTeamPosition(value: unknown): value is TeamPosition {
return typeof value === 'string' && TEAM_POSITIONS.includes(value);
}
function finiteNumber(value: unknown): number | undefined {
return typeof value === 'number' && Number.isFinite(value)
? value
: undefined;
}
function percentileRank(
rawValue: number,
percentileBreakpoints: number[],
): number {
const breakpoints = percentileBreakpoints.filter((value) =>
Number.isFinite(value),
);
if (breakpoints.length !== BASELINE_PERCENTILE_RANKS.length) {
return Number.NaN;
}
if (breakpoints[0] === breakpoints[breakpoints.length - 1]) {
return 0.5;
}
if (rawValue < (breakpoints[0] ?? 0)) {
return 0;
}
if (rawValue > (breakpoints[breakpoints.length - 1] ?? 0)) {
return 1;
}
for (let index = 0; index < breakpoints.length; index += 1) {
const currentBreakpoint = breakpoints[index] ?? 0;
const currentRank = BASELINE_PERCENTILE_RANKS[index] ?? 0;
if (rawValue === currentBreakpoint) {
return currentRank;
}
if (rawValue < currentBreakpoint) {
const previousBreakpoint = breakpoints[index - 1] ?? currentBreakpoint;
const previousRank = BASELINE_PERCENTILE_RANKS[index - 1] ?? 0;
if (currentBreakpoint === previousBreakpoint) {
return currentRank;
}
return (
previousRank +
((rawValue - previousBreakpoint) /
(currentBreakpoint - previousBreakpoint)) *
(currentRank - previousRank)
);
}
}
return 1;
}
@Injectable()
export class MetricNormalizationService {
constructor(private readonly connectionService: ConnectionService) {}
public async normalizeFeature(
feature: ExtractedPlayerMatchFeature,
options: NormalizeFeatureOptions = {},
): Promise<ExtractedPlayerMatchFeature> {
if (!isTeamPosition(feature.role)) {
return feature;
}
const observedMetricIds = Object.keys(feature.normalized).filter(
(metricId) => finiteNumber(feature.features[metricId]) !== undefined,
);
if (observedMetricIds.length === 0) {
return feature;
}
const baselinesByMetricId = await this.findBaselinesByMetricId({
cohort: options.cohort ?? 'MASTER_PLUS',
metricIds: observedMetricIds,
patch: feature.patch,
role: feature.role,
});
if (
observedMetricIds.some(
(metricId) => baselinesByMetricId.get(metricId) === undefined,
)
) {
return feature;
}
const normalized = { ...feature.normalized };
for (const metricId of observedMetricIds) {
const rawValue = finiteNumber(feature.features[metricId]);
const baseline = baselinesByMetricId.get(metricId);
if (rawValue === undefined || !baseline) {
return feature;
}
const normalizedValue = percentileRank(
rawValue,
baseline.percentileBreakpoints,
);
if (!Number.isFinite(normalizedValue)) {
return feature;
}
normalized[metricId] = Math.max(0, Math.min(1, normalizedValue));
}
return {
...feature,
normalized,
vector: VECTOR_METRICS.map((metric) => normalized[metric.id] ?? 0),
normalizationMethod: 'population-percentile',
};
}
private async findBaselinesByMetricId(params: {
cohort: BaselineCohort;
metricIds: string[];
patch: string;
role: TeamPosition;
}): Promise<Map<string, MetricBaseline>> {
const metricBaselineModel =
await this.connectionService.getModel('metricBaseline');
const baselines = await metricBaselineModel
.find({
metricId: {
$in: params.metricIds,
},
role: params.role,
cohort: params.cohort,
patch: {
$in: [params.patch, 'ALL'],
},
featureSchemaVersion: FEATURE_SCHEMA_VERSION,
})
.lean<MetricBaseline[]>()
.exec();
const baselinesByMetricId = new Map<string, MetricBaseline>();
for (const baseline of baselines) {
const existingBaseline = baselinesByMetricId.get(baseline.metricId);
if (!existingBaseline || baseline.patch === params.patch) {
baselinesByMetricId.set(baseline.metricId, baseline);
}
}
return baselinesByMetricId;
}
}