Random Effects Service

FastAPI-сервис для оценки модели Random Effects на панельных данных.

Сервис принимает файл в формате CSV или XLSX, проверяет структуру панельных данных и возвращает коэффициенты модели, стандартные ошибки, t-статистики, p-value, доверительные интервалы и основные метрики качества модели.

Стек

• Python
• FastAPI
• Pydantic
• Dishka
• pandas
• linearmodels
• pytest
• uv

Архитектура

Проект разделён на четыре основных модуля:

• domain.py — доменные сущности, ошибки, правила валидации и контракт статистического метода;
• application.py — Pydantic-схемы и use case оценки модели;
• infrastructure.py — чтение CSV/XLSX и adapter для linearmodels;
• presentation.py — FastAPI endpoint и преобразование ошибок в HTTP-ответы.

Библиотека linearmodels изолирована в infrastructure-слое и не используется напрямую в domain/application.

Конкретные реализации зависимостей передаются через Dishka.

Установка

uv sync --all-groups

Запуск

uv run uvicorn random_effects_service.main:app --reload

Swagger UI:

http://127.0.0.1:8000/docs

API

POST /random-effects

Запрос отправляется в формате multipart/form-data.

Параметры:

• file — файл .csv или .xlsx;
• entity_variable — идентификатор объекта панели;
• time_variable — временная переменная;
• dependent_variable — зависимая переменная Y;
• independent_variables — независимые переменные X, перечисленные через запятую;
• covariance_type — тип ковариационной матрицы: unadjusted, robust или clustered;
• significance_level — уровень значимости, по умолчанию 0.05;
• add_constant — добавлять ли константу в модель.

Пример входных данных:

company	year	y	x1	x2
A	2020	10.2	5.1	2.0
A	2021	11.0	5.5	2.2
B	2020	8.1	4.0	1.7
B	2021	8.8	4.3	1.9

Пример ответа

{
  "coefficients": [
    {
      "variable": "x1",
      "coefficient": 0.81,
      "std_error": 0.14,
      "t_statistic": 5.6,
      "p_value": 0.0001,
      "ci_lower": 0.52,
      "ci_upper": 1.10
    }
  ],
  "metrics": {
    "n_observations": 100,
    "n_entities": 20,
    "n_periods": 5,
    "r_squared": 0.62,
    "f_statistic": 24.7,
    "f_p_value": 0.00001,
    "df_model": 3,
    "df_residual": 97
  },
  "warnings": []
}

Дополнительно возвращаются r_squared_within, r_squared_between и r_squared_overall, если соответствующие значения доступны.

Валидация

Перед оцениванием модели проверяются:

• наличие выбранных переменных;
• отсутствие пропусков и бесконечных значений;
• числовой тип Y и X;
• уникальность пары entity-time;
• наличие минимум двух объектов и двух временных периодов;
• достаточное число наблюдений;
• отсутствие константности зависимой переменной;
• полный ранг матрицы регрессоров.

Несбалансированная панель допускается. Информация об этом добавляется в warnings.

Ошибки

• 400 — некорректные данные или структура панели;
• 422 — некорректные параметры HTTP-запроса;
• 500 — ошибка оценивания модели или внутренняя ошибка сервиса.

Тесты

uv run pytest

Пример клиента

request_example.ipynb отправляет пример CSV-файла в запущенный сервис и выводит полученный JSON-ответ.