Flight Data Analysis API — README

Участники

mas562 — Student 1: Specification Engineer
Axwell — Student 2: Developer
journey_to_the_stars — Student 3: Code Reviewer

✅ Роль Student 2 (Developer) выполнил

Axwell

.

Описание

Модуль предоставляет набор функций для анализа данных о авиарейсах: расчёт средней задержки, процента своевременных рейсов, анализ маршрутов, месячной и часовой динамики задержек, а также выявление сезонных паттернов.
Вся логика реализована как stateless: функции принимают

Требования

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

Установка:

pip install pandas numpy

💡 Для обработки очень больших объёмов данных рекомендуется использовать Polars или Dask, хотя текущая реализация полностью основана на

pandas

.

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

• 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
   • Дата в формате
     YYYY-MM-DD

2. Загрузите данные и вызовите нужные функции:

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

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

• Все функции принимают
  pandas.DataFrame
  первым аргументом.
• Возвращаемые значения — словари, совместимые с JSON.
• Отсутствующие значения в
  delay_minutes
  автоматически заменяются на
  0.0
  .

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

Возвращает статистику по заданной авиакомпании.

Вход:

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

Пример результата:

{
  "carrier": "AA",
  "avg_delay": 12.5,
  "on_time_percentage": 78.3,
  "total_flights": 15420,
  "most_common_routes": [
    {"route": "JFK-LAX", "flights": 542}
  ],
  "delay_by_month": {"1": 15.2, "2": 12.1}
}

Если данные отсутствуют, возвращается объект с нулевыми или пустыми значениями (ошибки не возникает).

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

Анализирует заданный маршрут между двумя аэропортами.

Вход:

• origin
  ,
  destination
  — трёхсимвольные IATA-коды аэропортов (валидируются)

Пример результата:

{
  "route": "JFK-LAX",
  "avg_delay": 14.2,
  "on_time_percentage": 75.8,
  "carriers_on_route": [
    {"carrier": "AA", "flights": 254, "avg_delay": 12.1},
    {"carrier": "DL", "flights": 187, "avg_delay": 16.3}
  ],
  "best_time_to_fly": {"hour": 8, "avg_delay": 6.2},
  "distance": 2475
}

Если маршрут не найден, возвращается:

get_peak_delay_hours(df)

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

Пример результата:

{
  "delay_by_hour": {"0": 8.1, "1": 7.5, ..., "23": 15.8},
  "peak_delay_hours": [{"hour": 18, "avg_delay": 22.4}],
  "best_hours": [{"hour": 6, "avg_delay": 5.2}]
}

Реализовано эффективно через

get_seasonal_patterns(df, year=None)

Анализ задержек по месяцам. При указании

Пример результата:

{
  "monthly_avg_delay": {"1": 12.3, "6": 8.2},
  "worst_month": {"month": 12, "avg_delay": 18.5},
  "best_month": {"month": 6, "avg_delay": 8.2}
}

Требуется наличие колонки

filter_flights_by_date(df, start_date, end_date)

Возвращает подмножество DataFrame, отфильтрованное по включающему диапазону дат.

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

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

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

• Агрегации реализованы через
  pandas.groupby
  — эффективно для датасетов до ~2 млн строк.
• Целевое время выполнения — менее 1 секунды на типичных запросах.
• Для больших объёмов рекомендуется:
  • перейти на Polars или Dask,
  • использовать предварительно вычисленные агрегаты (например, по часам/дням),
  • хранить сводные таблицы (
    carrier-route-hour
    ) для быстрых запросов.

Кеширование

Хотя в модуле упоминается

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

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

• Модуль stateless: нет сохранения состояния между вызовами.
• Нет ML: используется только описательная статистика.
• Колонка
  date
  обязательна для сезонного и месячного анализа.
• Расстояние (
  distance
  ) рассчитывается как медиана по маршруту (устойчивее к выбросам).
• Ожидается корректный формат времени (
  HH:MM
  ). Ошибки парсинга приводят к исключению записи из часовой статистики.

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

• Обернуть функции в REST API (FastAPI/Flask) с endpoint’ами и встроенным кэшированием.
• Перейти на Polars для ускорения агрегаций на больших данных.
• Добавить unit-тесты (pytest) с фикстурами и edge-case сценариями.
• Добавить поддержку часовых поясов и коррекцию для cross-midnight рейсов.
• Реализовать пагинацию и расширенную фильтрацию для больших ответов.

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

Рекомендуется проверить:

• Обработку отрицательных задержек (ранние прилёты)
• Работу с пропущенными значениями
• Поведение при отсутствии данных по маршруту или авиакомпании
• Корректность фильтрации по датам

Также стоит провести тест производительности:

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

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

• Обёрткой функций в REST API (FastAPI) с примерами запросов
• Добавлением автоматических тестов и настройкой CI
• Портированием на Polars или Dask для масштабирования