Від сирих даних до KPI: конвеєр ETL

Що робимо сьогодні

Модуль I · IT Skills (Cloud Services & Documents) · тема 6, урок 1 з 2 · 120 хвилин

Сьогодні ти пишеш build_dash.py. Цей скрипт бере сирі відповіді з твоєї форми і перетворює їх на п'ять чисел. Завтра ці числа покаже дашборд.

У темі 2 ти зібрав ~/data/responses.csv. Це сирі дані — такі, як їх записав сервер, без жодної обробки.

Відкрий цей файл, і побачиш безлад. Кілька клітинок порожні. Два рядки однакові. Хтось написав, що робить домашку 999 хвилин. А Grist, grist і GRIST лежать як три різні відповіді, хоча інструмент один і той самий.

Дашборд не вміє з цим працювати. Йому потрібні готові числа. Між сирим CSV і готовим числом стоїть скрипт — і саме він сьогодні головний герой.

Після уроку ти вмієш

• розкладати роботу з даними на три кроки — узяти, почистити, покласти — і пояснювати, навіщо їх розділяють;
• чистити дані: обробляти пропуски, знаходити дублікати, помічати викиди;
• рахувати середнє й медіану й показувати числами, чому медіана стійкіша;
• формулювати показник як відповідь на чиєсь питання, а не як просто число;
• читати CSV у Python через csv.DictReader і писати data.json через json.dump.

Слова ETL, KPI і викид поки нічого не означають. Розберемо їх по черзі, кожне після конкретного прикладу.

Де що виконується

Хід уроку

Три кроки роботи з даними: E, T, L

Не назва програми, а спосіб розкласти роботу на три кроки, кожен з яких можна перевірити окремо.

Уяви, що готуєш вечерю. Спершу приносиш продукти з магазину. Потім миєш, чистиш і ріжеш. І аж тоді ставиш готове на стіл. Три різні дії й три різні місця: ніхто не чистить картоплю в тарілці гостя.

З даними так само — теж три кроки. Їхні англійські назви скоротили до перших літер, і вийшло слово ETL.

Extract — узяти сирі дані звідти, де вони лежать. Відкрити файл, прочитати рядки, перетворити текст на записи. На цьому кроці нічого не рахують і нічого не виправляють: завдання — просто дістати.

Transform — почистити й порахувати. Викинути сміття, звести різні написання до одного, вирішити, що робити з порожніми клітинками, і вже потім рахувати показники.

Load — покласти результат туди, звідки його читає дашборд. У нашому випадку це один файл ~/www/dash/data.json.

Навіщо розділяти, а не робити все в одному місці

Спокуса зробити все однією функцією велика: відкрив файл, тут-таки порахував, тут-таки намалював. Так теж працює — рівно до першої зміни.

Головне: між кроками з'являється видимий проміжний результат. Помилку видно на тому кроці, де вона сталася, а не в кінці, коли графік «якийсь дивний».

Чому дашборд не рахує сам

Найчастіше питання на цьому уроці: «а навіщо взагалі проміжний файл, хай браузер прочитає CSV і порахує». Є три відповіді, і кожна сама по собі достатня.

Перша: дашборд має відкриватися миттєво

Дашборд дивляться між справами: зайшов, побачив, пішов. Якщо сторінка спершу тягне весь CSV, а потім рахує медіану, людина бачить білий екран. Скрипт рахує один раз на сервері — сторінка тільки читає результат.

Друга: знімок показників не має мінятися сам собою

Сирі дані живі: кожні кілька хвилин приходить нова відповідь. Уяви, що дашборд рахує на льоту. Ти дивишся на нього з телефона, сусід — з ноутбука. У вас на екранах різні числа, і поговорити про них ви вже не можете.

Тому скрипт робить знімок: рахує один раз і кладе результат у data.json. Усередині є мітка часу generated_at — видно, о котрій знімок зроблено. Сперечаються саме про нього.

Третя, найважливіша: приватність

responses.csv лежить у теці ~/data/. По HTTP ця тека не віддається: з інтернету її не відкрити ніяк.

Тримає цю межу число 750 — код прав на теку. Читають його по одній цифрі, зліва направо. Перша цифра — про тебе, власника теки. Друга — про твою групу. Третя — про всіх решту.

7 означає «власник може все»: заходити, читати, створювати файли. 5 — «група може зайти й прочитати, але не міняти». 0 — «решта не може нічого». Вебсервер працює саме від «решти». Тому він і не має шансів віддати цей файл комусь у браузер.

Якщо змусити браузер читати CSV, файл доведеться покласти в ~/www/. А це означає віддати сирі відповіді однокласників усьому інтернету. Агрегат у data.json віддавати можна: там числа, а не люди.

Брудні дані: пропуски, дублікати, викиди

Дані, зібрані від людей, ніколи не бувають чистими. Чистка — не косметика, а місце, де ти приймаєш рішення, і кожне з них видно в підсумковому числі.

Пропущені значення

Хтось не відповів на питання про час. У CSV це порожня клітинка. Що з нею робити — не технічне питання, а змістовне: різні рішення дають різні числа і різні висловлювання про клас.

Правильний за замовчуванням варіант — другий. І обов'язково винести в data.json число rows_used: скільки записів реально пішло в розрахунок.

Дублікати

Дублікат — це не «два однакові числа». Дублікат — це один і той самий факт, записаний двічі: людина двічі натиснула «Надіслати», або форму перезавантажили, або сервер повторив запит.

Як його виявити: шукаєш записи, у яких збігається ключ, що мав би бути унікальним. У твоїй формі це session_id.

А от якщо збігається лише набір відповідей, а session_id різні — це двоє різних людей, які просто відповіли однаково. Викидати їх не можна.

Перша колонка — session_id. uniq -d показує тільки ті значення, що трапилися більше одного разу. Порожній вивід — дублікатів немає.

Викиди

Викид — значення, яке різко випадає з решти. Найчастіше це не злодійство. Це жарт («999 годин»). Або помилка одиниць: «2» замість «120», бо людина писала години. Або просто промах по клавіші.

Одного викиду досить, щоб зламати середнє. Не «трохи змістити» — саме зламати: середнє почне показувати число, якого немає ні в кого.

Чому медіана стійкіша

Вишикуй клас за зростом. Той, хто стоїть точно посередині шеренги, — це медіана. Прийде в клас баскетболіст на два метри — він просто стане скраю, а посередині лишиться той самий учень.

Із середнім інакше. Його рахують так: складають усі зрости й ділять на кількість людей. Ті два метри піднімуть число одразу для всіх.

З хвилинами на домашку те саме. Кожне значення тягне середнє на себе, а величезне тягне сильно. Медіані байдуже, наскільки велике крайнє число, — важливо лише, що воно крайнє.

Тому правило: показуй обидва. Якщо середнє й медіана близькі — розподіл рівний. Якщо різко різні — щось перекошує картину, і це саме по собі новина.

Різні написання одного й того самого

Цю пастку ти вже бачив в уроці 3. Grist, grist, GRIST і  Grist з пробілом — це чотири різні значення для комп'ютера. Для людини — одне.

Лікується двома викликами. .strip() прибирає пробіли з країв, .lower() зводить регістр.

Симулятор конвеєра

Ось 12 рядків із сирими проблемами. Тисни кнопки по порядку і дивись, що саме змінюється на кожному кроці. Підсвічені рядки — ті, до яких скрипт щось зробив.

Мітка generated_at у прикладі фіксована, щоб файл не мінявся від перезавантаження сторінки. Твій скрипт має ставити реальний час запуску.

Що таке KPI і чим він відрізняється від просто числа

KPI — key performance indicator, ключовий показник. Ключове слово тут не «показник», а «ключовий»: він має відповідати на питання, яке хтось справді ставить.

Уяви стрілку бензину в машині. На неї дивляться не заради цифри, а щоб вирішити: заїжджати на заправку чи їхати далі. Це й є ключовий показник — число, від якого залежить чиясь дія.

Перевірка проста. Назви показник уголос і спитай себе: яке рішення зміниться, якщо це число буде іншим? Якщо жодне — це не KPI, це просто цифра на екрані.

«Кількість» проти «частки»

Це найчастіша помилка шкільних дашбордів. Кількість — скільки штук. Частка — скільки штук зі скількох можливих. Кількість без знаменника нічого не означає.

«Відповіли 18 людей» — це багато чи мало? Якщо в класі 28 — це 64%, нормально. Якщо опитування було на паралель зі 120 учнів — це 15%, і за такими даними висновків про паралель робити не можна.

Метрика і вимір

Метрика — те, що ми міряємо числом: кількість, середнє, медіана, частка. Вимір — розріз, у якому дивимось на метрику: за днями, за класом, за інструментом.

Один KPI = одна метрика + нуль або один вимір. «Медіана хвилин» — метрика без виміру, одне число. «Медіана хвилин за днями» — та сама метрика в розрізі днів, уже часовий ряд. Плутанина тут — головна причина, чому дашборд виходить нечитабельним: люди беруть три виміри одразу.

Конструктор KPI: від питання до коду

Обери метрику, вимір і умову — і подивись, який фрагмент build_dash.py це дає і яке число виходить на даних симулятора.

Python по-шкільному: п'ять інструментів

Усе, що треба сьогодні, є в стандартній поставці Python 3, яка вже стоїть на сервері.

Для роботи з таблицями дорослі аналітики зазвичай докачують окрему бібліотеку — вона зветься pandas і вміє багато чого одним рядком. Сьогодні вона нам не потрібна: п'яти вбудованих інструментів вистачить на весь конвеєр. Заразом ти побачиш, що всередині таких бібліотек немає жодної магії.

1. Прочитати CSV: csv.DictReader

Він читає перший рядок як заголовок і повертає кожен наступний рядок як словник: {'ts': '...', 'minutes': '45', ...}. Звертатися можна за назвою колонки, а не за номером — код лишається читабельним.

import csv

with open(SRC, newline='', encoding='utf-8-sig') as f:
    rows = list(csv.DictReader(f))

print(rows[0]['minutes'])   # '45' — рядок, не число!

2. Словники як записи

Кожен рядок — словник. Додавати в нього свої поля можна прямо на місці: r['date'] = r['ts'][:10]. Перші 10 символів ISO-дати — це рівно 2026-02-02, тобто день без часу.

clean, seen = [], set()
for r in rows:
    if None in r or None in r.values():
        continue                       # поламана кількість колонок
    if r['session_id'] in seen:
        continue                       # дублікат
    seen.add(r['session_id'])
    r['tool'] = r['tool'].strip().lower()
    r['date'] = r['ts'][:10]
    m = r['minutes'].strip()
    r['minutes'] = int(m) if m.isdigit() else None
    clean.append(r)

m.isdigit() тут не прикраса: саме він рятує від ValueError на порожній клітинці. int('') завжди падає, а перевірити перед перетворенням — один рядок.

3. Порахувати категорії: collections.Counter

Counter — це словник, який сам рахує, скільки разів трапилося кожне значення. Метод .most_common() віддає пари «значення — скільки», відсортовані за спаданням.

from collections import Counter

by_tool = Counter(r['tool'] for r in clean)
print(by_tool)                     # Counter({'grist': 5, 'google таблиці': 2, ...})
print(by_tool.most_common(1))      # [('grist', 5)]

4. Середнє й медіана: statistics

Обидві функції беруть список чисел. Порожній список їм не можна — буде помилка, тому перед викликом завжди перевіряй, що список не порожній.

from statistics import mean, median

vals = [r['minutes'] for r in clean
        if r['minutes'] is not None and r['minutes'] <= 180]

avg = round(mean(vals), 1) if vals else None
med = median(vals) if vals else None

median для парної кількості значень повертає півсуму двох середніх: для восьми відповідей це може бути 37.5, і це нормальне число, а не помилка.

5. Записати JSON: json.dump

import json

with open(DST, 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

ensure_ascii=False лишає українські слова літерами. Без нього "grist" не зміниться, а "таблиці" перетвориться на "\u0442\u0430\u0431\u043b\u0438\u0446\u0456". Такий запис браузер прочитає, а ти — ні.

indent=2 розставляє відступи. Файл стає придатним для читання очима — а він саме для очей і потрібен: це ж контракт.

Повний скелет build_dash.py

#!/usr/bin/env python3
# ~/bin/build_dash.py — конвеєр ETL для дашборда
import csv, json, os
from collections import Counter
from datetime import datetime, timezone
from statistics import mean, median

SRC = os.path.expanduser('~/data/responses.csv')
DST = os.path.expanduser('~/www/dash/data.json')

# ── EXTRACT ──────────────────────────────────────
with open(SRC, newline='', encoding='utf-8-sig') as f:
    rows = list(csv.DictReader(f))

# ── TRANSFORM ────────────────────────────────────
clean, seen = [], set()
for r in rows:
    if None in r or None in r.values():
        continue
    if r['session_id'] in seen:
        continue
    seen.add(r['session_id'])
    r['tool'] = r['tool'].strip().lower()
    r['date'] = r['ts'][:10]
    m = r['minutes'].strip()
    r['minutes'] = int(m) if m.isdigit() else None
    clean.append(r)

vals = [r['minutes'] for r in clean
        if r['minutes'] is not None and r['minutes'] <= 180]
by_day  = Counter(r['date'] for r in clean)
by_tool = Counter(r['tool'] for r in clean)

# ── LOAD ─────────────────────────────────────────
data = {
    'generated_at': datetime.now(timezone.utc).astimezone().isoformat(timespec='seconds'),
    'source': {'file': os.path.basename(SRC),
               'rows_read': len(rows), 'rows_used': len(clean)},
    'metrics': {
        'responses_total': len(clean),
        'avg_minutes':     round(mean(vals), 1) if vals else None,
        'median_minutes':  median(vals) if vals else None,
        'share_over_45':   round(sum(1 for v in vals if v > 45) / len(vals), 3) if vals else None,
        'top_tool':        by_tool.most_common(1)[0][0] if by_tool else None,
    },
    'series':  [{'date': d, 'responses': by_day[d]} for d in sorted(by_day)],
    'by_tool': dict(by_tool.most_common()),
}

os.makedirs(os.path.dirname(DST), exist_ok=True)
with open(DST, 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
print('ok:', data['metrics']['responses_total'], 'записів →', DST)

data.json як контракт

Контракт — це домовленість між скриптом і сторінкою: скрипт обіцяє класти дані саме в такі поля, сторінка обіцяє читати саме звідти. Хто перший порушить — той і зламав дашборд.

Три правила контракту

1. Назви полів не міняються без попередження. Перейменував avg_minutes на average — і картка на сторінці показує undefined.
2. Тип поля сталий. Якщо median_minutes одного разу число, а іншого разу рядок "37,5" з комою — графік упаде. У JSON десятковий роздільник — крапка, завжди.
3. Порожньо — це null, а не «0» і не «—». Нуль означає «порахували, вийшло нуль». null означає «порахувати не було з чого». Це різні висловлювання.

Дати в series

У часовому ряді дати мають бути в ISO 8601: 2026-02-02. Причина не в красі: такий запис сортується як текст точно так само, як хронологічно. Рік, місяць, день — від більшого до меншого, кожне поле фіксованої ширини.

Практика: пишемо build_dash.py

Кроки 1—3 і 15 — на твоєму комп'ютері, кроки 4—14 — по SSH на сервері, крок 16 — по FTP. Галочки зберігаються, сторінку можна закрити.

Автоперевірка check 11

Чекер запускає твій скрипт у пісочниці, підсовує йому зіпсовані дані й перераховує контрольну метрику сам. Вигадані числа не сходяться. Спроби не обмежені.

Демонстраційний режим: результат згенеровано для показу. На сервері ця кнопка викликає POST /api/check, який запускає check 11 від імені учня.

Що вчитель дивиться на твоєму екрані

• ти запускаєш python3 ~/bin/build_dash.py при ньому, і в терміналі з'являється рядок з кількістю записів;
• ти відкриваєш data.json і показуєш, звідки взялося кожне з чотирьох чисел;
• учитель питає: що станеться, якщо в CSV трапиться порожня клітинка — ти показуєш рядок коду, який це обробляє;
• учитель питає, яку межу викиду ти взяв і чому саме таку;
• у README.md видно чотири пари «питання → метрика», і ти можеш пояснити, чиє це питання.

Шкала виконання

Це те, що бачить учитель, коли виставляє оцінку.

Чотири речення, які варто запам'ятати

• Extract бере, Transform чистить і рахує, Load кладе — і між кроками завжди є те, що можна побачити очима;
• дашборд читає готовий знімок, бо рахувати щоразу означає і чекати, і віддавати сирі відповіді назовні;
• одного «999» досить, щоб середнє показало число, якого немає ні в кого — медіана це переживає;
• KPI — це відповідь на чиєсь питання; число без бази порівняння не показник.

Де найчастіше помиляються

• скрипт падає на порожній клітинці — int('') без перевірки;
• дати в series як 01.02 — сортування ламається на другому місяці;
• у data.json потрапляють сирі відповіді з session_id — порушення приватності агрегатів;
• забуто ensure_ascii=False — файл нечитабельний для людини;
• порожні клітинки замінено нулями — середнє падає, і клас виглядає швидшим, ніж він є;
• дублікат не виявлено, бо шукали однакові рядки, а не однаковий session_id;
• метрики вписані в data.json руками, без скрипта. Сервер рахує кількість відповідей сам і звіряє зі здачею — розбіжність видно першою ж спробою.

Домашнє завдання

Додай п'ятий KPI, який не рахується «в лоб». Наприклад, частку відповідей за останні три дні від усіх. Або різницю медіан 9A і 9B.

Опиши його в README.md парою «питання → метрика». І поясни одним реченням, яке рішення міняється від цього числа.

Звідки взяті означення й приклади

Усе — з документації Python, стандартів і відкритих довідників. Перевіряти дозволено й корисно.

• Extract, transform, load — самі поняття і чому кроки розділяють. en.wikipedia.org/wiki/Extract,_transform,_load
• Data cleansing — типи дефектів даних: пропуски, дублікати, неузгоджені написання. en.wikipedia.org/wiki/Data_cleansing
• Missing data — чому заміна пропуску нулем чи середнім змінює висновок. en.wikipedia.org/wiki/Missing_data
• Outlier і Robust statistics — викид і стійкість медіани. en.wikipedia.org/wiki/Outlier, en.wikipedia.org/wiki/Robust_statistics
• Anscombe's quartet — чотири набори з однаковим середнім і зовсім різним змістом. en.wikipedia.org/wiki/Anscombe's_quartet
• Performance indicator (KPI) — показник як відповідь на питання. en.wikipedia.org/wiki/Performance_indicator
• csv — CSV File Reading and Writing: DictReader, restkey, вимога newline=''. docs.python.org/3/library/csv.html
• collections.Counter — підрахунок категорій, most_common(). docs.python.org/3/library/collections.html
• statistics — mean(), median() і поведінка на парній кількості значень. docs.python.org/3/library/statistics.html
• json — json.dump(), ensure_ascii, indent. docs.python.org/3/library/json.html
• datetime.isoformat() і timespec — як отримати коректний ISO-рядок. docs.python.org/3/library/datetime.html
• Кодек utf-8-sig — що це і навіщо при читанні файлів з BOM. docs.python.org/3/library/codecs.html
• RFC 4180 — формат CSV: кома, лапки, заголовок. datatracker.ietf.org/doc/html/rfc4180
• RFC 8259 — JSON: типи значень, чому крапка як десятковий роздільник. datatracker.ietf.org/doc/html/rfc8259
• ISO 8601 / RFC 3339 — запис дати й часу, що сортується як текст. en.wikipedia.org/wiki/ISO_8601, datatracker.ietf.org/doc/html/rfc3339

Повний список із поясненнями, що звідки взято, — у файлі urok-11-джерела.md поруч із цією сторінкою.