Flight Data Analysis API — README

Участники

• journey_to_the_stars (Student 1: Specification Engineer)

• Axwell (Student 2: Developer)

• mas562 (Student 3: Code Reviewer)

• Роль Student 2 выполнял у Axwell

Описание

Этот модуль реализует набор функций для анализа данных о рейсах: вычисление средней задержки, процента рейсов вовремя, анализ маршрутов и месяцев, часы пиковых задержек и сезонные паттерны. Модуль спроектирован как stateless — все функции получают pandas.DataFrame и возвращают стандартные JSON-подобные словари (dict). Машинного обучения не используется.

Требования

• Python 3.8+
• Библиотеки: pandas, numpy

Пример установки:

pip install pandas numpy

(Опционально: для ускорения при больших данных — Polars или Dask.)

Структура репозитория

• flight_analysis.py — основной модуль с реализацией функций.
• README.md — этот файл.
• tests/ — (рекомендация) место для unit-тестов (не включены).

Быстрый старт

1. Подготовьте CSV с колонками:
   • carrier, flight_number, origin, destination, departure_time, arrival_time, air_time, delay_minutes, distance, date
   • Время — HH:MM, date — YYYY-MM-DD
2. Загрузите DataFrame:

3. Вызов:

Описание функций и формат выходных данных

Общие правила:

• Все функции принимают pandas.DataFrame как первый аргумент.
• Возвращают словарь, совместимый с JSON (числа, строки, списки, вложенные объекты).
• Пропущенные delay_minutes заполняются нулём.

get_carrier_statistics(df, carrier, start_date=None, end_date=None)

Анализ по авиакомпании.

Вход:

• df — DataFrame с полями, указанными в спецификации.
• carrier — код авиакомпании (строка).
• start_date, end_date — опциональные фильтры YYYY-MM-DD.

Выход (пример):

Поведение при отсутствии данных: возвращается объект с нулевыми/пустыми значениями.

get_route_analysis(df, origin, destination, start_date=None, end_date=None)

Анализ конкретного маршрута.

Вход:

• origin, destination — коды аэропортов (3 символа). Валидируются.

Выход (пример):

Если маршрут не найден, возвращается {"error": "Маршрут не найден"}.

get_peak_delay_hours(df)

Анализ задержек по часам суток.

Возвращает:

Реализовано быстро через groupby по извлечённому departure_hour.

get_seasonal_patterns(df, year=None)

Анализ по месяцам; при указании year — фильтрация по году.

Возвращает:

Требует наличия колонки date в DataFrame.

filter_flights_by_date(df, start_date, end_date)

Возвращает DataFrame, отфильтрованный по inclusive диапазону дат.

Валидация и обработка пропусков

• delay_minutes: пропущенные значения заполняются 0.0.
• departure_time/arrival_time: заполняются '00:00' при отсутствии.
• date: для функций, использующих месяц/год, колонка date обязательна и должна быть преобразована pd.to_datetime.
• airport code: проверка длины 3 символа для origin/destination.

Производительность и масштабирование

• Операции агрегирования выполнены через pandas.groupby, что быстро для средних наборов данных (~0.5–2M строк на машинах с достат. RAM).
• Целевое время ответа < 1s для типичных запросов при размерах, описанных в спецификации. Для больших данных:
  • использовать Polars (faster) или Dask для распределённой обработки;
  • предагрегировать данные в хранилище (например, hourly/day aggregates);
  • хранить сокращённые таблицы (carrier-route-hour) для быстрых lookups.

Кеширование

В модуле показана идея использования lru_cache; реальное кеширование следует реализовать внешне:

• кешировать результаты запросов по ключам: (фингерпринт данных, функция, параметры).
• для часто используемых запросов (carrier stats, peak hours) использовать in-memory или redis.

Ограничения и предположения

• Модуль не сохраняет состояние между вызовами (stateless).
• Не используются ML модели — только описательная статистика.
• Предпочтение: дата должна быть в колонке
  date
  . В противном случае сезонные и месячные расчёты недоступны.
• distance выбирается как мода по маршруту, иначе среднее округлённое.
• На вход ожидается корректный формат времени (HH:MM). Неправильные строки приводят к 0-му часу в текущей реализации.

Предложения по доработке

• Добавить FastAPI/Flask обёртку с endpoint'ами и встроенным кешем.
• Подключить Polars для ускорения агрегаций на больших объемах.
• Добавить unit-тесты (pytest) с фикстурами и тестовыми сценариями из acceptance-criteria.
• Добавить опции агрегации по зонам времени и корректировку на cross-midnight рейсы.
• Добавить параметризированную пагинацию/фильтрацию для больших ответов.

Тестирование

Рекомендуемые проверки:

• Unit-тесты на функции с искусственными DataFrame, включающие:
  • отрицательные delay_minutes (ранние прилёты),
  • отсутствующие значения,
  • маршруты без данных,
  • фильтрацию по датам.
• Performance test: измерить время выполнения get_peak_delay_hours на полных данных (assert < 1s на целевом hw).

Контакты / дополнительные услуги

Готов помочь:

• обёрнуть функции в REST API (FastAPI) с примерами запросов,
• добавить тесты и CI,
• портировать на Polars/Dask для масштабирования.