hampel

Author: jycouet

app/components/Package/TrendsChart.vue

@@ -18,6 +18,7 @@ import type {
   YearlyDataPoint,
 } from '~/types/chart'
 import { DATE_INPUT_MAX } from '~/utils/input'
+import { applyDownloadFilter } from '~/utils/chart-filters'
 
 const props = withDefaults(
   defineProps<{
@@ -50,6 +51,7 @@ const props = withDefaults(
 
 const { locale } = useI18n()
 const { accentColors, selectedAccentColor } = useAccentColor()
+const { settings } = useSettings()
 const colorMode = useColorMode()
 const resolvedMode = shallowRef<'light' | 'dark'>('light')
 const rootEl = shallowRef<HTMLElement | null>(null)
@@ -926,15 +928,27 @@ watch(
 
 const effectiveDataSingle = computed<EvolutionData>(() => {
   const state = activeMetricState.value
+  let data: EvolutionData
   if (
     selectedMetric.value === DEFAULT_METRIC_ID &&
     displayedGranularity.value === DEFAULT_GRANULARITY &&
     props.weeklyDownloads?.length
   ) {
-    if (isWeeklyDataset(state.evolution) && state.evolution.length) return state.evolution
-    return props.weeklyDownloads
+    data =
+      isWeeklyDataset(state.evolution) && state.evolution.length
+        ? state.evolution
+        : props.weeklyDownloads
+  } else {
+    data = state.evolution
+  }
+
+  if (isDownloadsMetric.value && data.length) {
+    return applyDownloadFilter(
+      data as Array<{ value: number }>,
+      settings.value.chartFilter,
+    ) as EvolutionData
   }
-  return state.evolution
+  return data
 })
 
 /**
@@ -968,7 +982,13 @@ const chartData = computed<{
   const pointsByPackage = new Map<string, Array<{ timestamp: number; value: number }>>()
 
   for (const pkg of names) {
-    const data = state.evolutionsByPackage[pkg] ?? []
+    let data = state.evolutionsByPackage[pkg] ?? []
+    if (isDownloadsMetric.value && data.length) {
+      data = applyDownloadFilter(
+        data as Array<{ value: number }>,
+        settings.value.chartFilter,
+      ) as EvolutionData
+    }
     const points = extractSeriesPoints(granularity, data)
     pointsByPackage.set(pkg, points)
     for (const p of points) timestampSet.add(p.timestamp)
@@ -1583,6 +1603,9 @@ const chartConfig = computed<VueUiXyConfig>(() => {
   }
 })
 
+const isDownloadsMetric = computed(() => selectedMetric.value === 'downloads')
+const showFilterControls = shallowRef(false)
+
 // Trigger data loading when the metric is switched
 watch(selectedMetric, value => {
   if (!isMounted.value) return
@@ -1671,6 +1694,66 @@ watch(selectedMetric, value => {
         </button>
       </div>
 
+      <!-- Download filter controls -->
+      <div v-if="isDownloadsMetric" class="flex flex-col gap-2">
+        <button
+          type="button"
+          class="self-start flex items-center gap-1 text-2xs font-mono text-fg-subtle hover:text-fg transition-colors"
+          @click="showFilterControls = !showFilterControls"
+        >
+          <span
+            class="w-3.5 h-3.5 transition-transform"
+            :class="showFilterControls ? 'i-lucide:chevron-down' : 'i-lucide:chevron-right'"
+            aria-hidden="true"
+          />
+          Filters
+        </button>
+        <div v-if="showFilterControls" class="grid grid-cols-1 sm:grid-cols-3 gap-3">
+          <label class="flex flex-col gap-1">
+            <span class="text-2xs font-mono text-fg-subtle tracking-wide uppercase">
+              Hampel window
+              <span class="text-fg-muted">({{ settings.chartFilter.hampelWindow }})</span>
+            </span>
+            <input
+              v-model.number="settings.chartFilter.hampelWindow"
+              type="range"
+              min="0"
+              max="13"
+              step="1"
+              class="accent-[var(--accent-color,var(--fg-subtle))]"
+            />
+          </label>
+          <label class="flex flex-col gap-1">
+            <span class="text-2xs font-mono text-fg-subtle tracking-wide uppercase">
+              Outlier threshold
+              <span class="text-fg-muted">({{ settings.chartFilter.hampelThreshold }})</span>
+            </span>
+            <input
+              v-model.number="settings.chartFilter.hampelThreshold"
+              type="range"
+              min="0"
+              max="10"
+              step="0.5"
+              class="accent-[var(--accent-color,var(--fg-subtle))]"
+            />
+          </label>
+          <label class="flex flex-col gap-1">
+            <span class="text-2xs font-mono text-fg-subtle tracking-wide uppercase">
+              Smoothing (tau)
+              <span class="text-fg-muted">({{ settings.chartFilter.smoothingTau }})</span>
+            </span>
+            <input
+              v-model.number="settings.chartFilter.smoothingTau"
+              type="range"
+              min="0"
+              max="26"
+              step="1"
+              class="accent-[var(--accent-color,var(--fg-subtle))]"
+            />
+          </label>
+        </div>
+      </div>
+
       <p v-if="skippedPackagesWithoutGitHub.length > 0" class="text-2xs font-mono text-fg-subtle">
         {{ $t('package.trends.contributors_skip', { count: skippedPackagesWithoutGitHub.length }) }}
         {{ skippedPackagesWithoutGitHub.join(', ') }}

app/composables/useSettings.ts

@@ -38,6 +38,11 @@ export interface AppSettings {
     collapsed: string[]
     animateSparkline: boolean
   }
+  chartFilter: {
+    hampelWindow: number
+    hampelThreshold: number
+    smoothingTau: number
+  }
 }
 
 const DEFAULT_SETTINGS: AppSettings = {
@@ -55,6 +60,11 @@ const DEFAULT_SETTINGS: AppSettings = {
     collapsed: [],
     animateSparkline: true,
   },
+  chartFilter: {
+    hampelWindow: 4,
+    hampelThreshold: 2,
+    smoothingTau: 1,
+  },
 }
 
 const STORAGE_KEY = 'npmx-settings'

app/utils/chart-filters.ts

@@ -0,0 +1,95 @@
+/**
+ * Hampel filter: replaces outlier values with the local median.
+ * Uses Median Absolute Deviation (MAD) to detect outliers.
+ *
+ * @param data - array of objects with a `value` property
+ * @param windowSize - half-window size (0 = disabled)
+ * @param threshold - number of MADs above which a value is considered an outlier
+ * @returns a new array with outlier values replaced by the local median
+ */
+export function hampelFilter<T extends { value: number }>(
+  data: T[],
+  windowSize: number,
+  threshold: number,
+): T[] {
+  if (windowSize <= 0 || data.length === 0) return data
+
+  const result = data.map(d => ({ ...d }))
+  const n = data.length
+
+  for (let i = 0; i < n; i++) {
+    const lo = Math.max(0, i - windowSize)
+    const hi = Math.min(n - 1, i + windowSize)
+
+    const windowValues: number[] = []
+    for (let j = lo; j <= hi; j++) {
+      windowValues.push(data[j]!.value)
+    }
+    windowValues.sort((a, b) => a - b)
+
+    const median = windowValues[Math.floor(windowValues.length / 2)]!
+    const deviations = windowValues.map(v => Math.abs(v - median)).sort((a, b) => a - b)
+    const mad = deviations[Math.floor(deviations.length / 2)]!
+
+    // 1.4826 converts MAD to an estimate of the standard deviation
+    const scaledMad = 1.4826 * mad
+
+    if (scaledMad > 0 && Math.abs(data[i]!.value - median) > threshold * scaledMad) {
+      result[i]!.value = median
+    }
+  }
+
+  return result
+}
+
+/**
+ * Low-pass (exponential smoothing) filter.
+ *
+ * @param data - array of objects with a `value` property
+ * @param tau - smoothing time constant (0 = disabled, higher = smoother)
+ * @returns a new array with smoothed values
+ */
+export function lowPassFilter<T extends { value: number }>(data: T[], tau: number): T[] {
+  if (tau <= 0 || data.length === 0) return data
+
+  const result = data.map(d => ({ ...d }))
+  const alpha = 1 / (1 + tau)
+
+  result[0]!.value = data[0]!.value
+  for (let i = 1; i < data.length; i++) {
+    result[i]!.value = alpha * data[i]!.value + (1 - alpha) * result[i - 1]!.value
+  }
+
+  return result
+}
+
+export interface ChartFilterSettings {
+  hampelWindow: number
+  hampelThreshold: number
+  smoothingTau: number
+}
+
+/**
+ * Applies Hampel filter then low-pass smoothing in sequence.
+ */
+export function applyDownloadFilter<T extends { value: number }>(
+  data: T[],
+  settings: ChartFilterSettings,
+): T[] {
+  if (data.length < 2) return data
+
+  const firstValue = data[0]!.value
+  const lastValue = data[data.length - 1]!.value
+
+  let result = data
+  result = hampelFilter(result, settings.hampelWindow, settings.hampelThreshold)
+  result = lowPassFilter(result, settings.smoothingTau)
+
+  // Preserve original first and last values
+  if (result !== data) {
+    result[0]!.value = firstValue
+    result[result.length - 1]!.value = lastValue
+  }
+
+  return result
+}