Educational Data Analysis API

Проект по анализу образовательных данных студентов, реализованный в рамках подхода VibeCode для совместной разработки.

Участники проекта

• Student 1 (Specification Engineer): Lunya
• Student 2 (Developer): sharkiss - Роль выполнена с использованием Cursor AI Assistant
• Student 3 (Code Reviewer): Foutx

Описание проекта

Данный проект представляет собой REST API для анализа успеваемости студентов на основе данных из CSV файлов. API позволяет анализировать данные по предметам, семестрам, уровням сложности и корреляции между посещаемостью и успеваемостью.

Основные возможности

1. Анализ успеваемости по предметам (
   get_subject_statistics
   ) - статистика по каждому предмету за указанный год
2. Анализ влияния посещаемости (
   analyze_attendance_impact
   ) - корреляция между посещаемостью и оценками
3. Сравнение уровней сложности (
   compare_difficulty_levels
   ) - сравнение успеваемости по уровням сложности для конкретного предмета

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

Team_coding/
├── spec/
│   └── codex.md              # Системная спецификация (Student 1)
├── dev/
│   ├── solution.py           # Основное решение (Student 2)
│   └── generate_test_data.py # Скрипт генерации тестовых данных
├── data/
│   ├── student_performance_2020.csv
│   ├── student_performance_2021.csv
│   └── student_performance_2022.csv
├── demo/
│   ├── api_test_results.json # Результаты тестирования API
│   └── example_responses.md  # Примеры ответов API
├── requirements.txt          # Зависимости проекта
└── README.md                 # Документация проекта

Технологический стек

• Python 3.8+
• FastAPI - веб-фреймворк для создания API
• pandas - обработка и анализ данных
• numpy - математические операции
• scipy - статистические тесты (корреляция Пирсона, ANOVA)
• uvicorn - ASGI сервер для запуска приложения

Установка и запуск

1. Установка зависимостей

2. Генерация тестовых данных

Это создаст три CSV файла в папке

3. Запуск API сервера

Или с использованием uvicorn напрямую:

API будет доступен по адресу:

4. Документация API

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

• Swagger UI:
  http://localhost:8000/docs
• ReDoc:
  http://localhost:8000/redoc

Описание API endpoints

GET

/

Корневой endpoint с информацией об API.

Ответ:

GET

/subject-statistics/{year}

Получить статистику по предметам за указанный год.

Параметры:

• year
  (int): Год для анализа (2020, 2021, 2022)

Пример запроса:

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

GET

/attendance-impact

Анализ корреляции между посещаемостью и успеваемостью.

Пример запроса:

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

GET

/difficulty-comparison/{subject}

Сравнение успеваемости по уровням сложности для конкретного предмета.

Параметры:

• subject
  (string): Название предмета (Math, Physics, Chemistry, Biology, History)

Пример запроса:

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

Описание реализации

Основные компоненты

1. Загрузка данных (

load_data

)

Функция загружает CSV файлы из папки

2. Анализ по предметам (

get_subject_statistics

)

Функция выполняет агрегацию данных по предметам за указанный год:

• Расчет среднего балла и процента сдачи
• Распределение по уровням успеваемости (excellent, good, satisfactory, fail)
• Сравнение успеваемости по семестрам
• Определение размера когорты

3. Анализ влияния посещаемости (

analyze_attendance_impact

)

Функция анализирует корреляцию между посещаемостью и успеваемостью:

• Общая корреляция Пирсона
• Корреляция по каждому предмету отдельно
• Анализ влияния посещаемости на успеваемость (high/medium/low)
• Проверка статистической значимости

4. Сравнение уровней сложности (

compare_difficulty_levels

)

Функция сравнивает успеваемость по уровням сложности (beginner, intermediate, advanced):

• Средний балл и процент сдачи для каждого уровня
• Размер когорты для каждого уровня
• Статистический тест ANOVA для проверки значимости различий

Обработка ошибок

Код включает обработку следующих граничных случаев:

• Отсутствие файлов данных
• Некорректные параметры (год, предмет)
• Пустые датасеты
• Некорректные диапазоны значений

Соответствие спецификации

✅ Все три функции реализованы и работают корректно
✅ Корреляции вычислены с использованием корректных статистических методов (Пирсон)
✅ Группировка по предметам охватывает все доступные предметы
✅ Персональные данные студентов (student_id) не раскрываются в выходных данных
✅ API возвращает данные в указанном JSON формате
✅ Включены размеры когорт и показатели статистической значимости
✅ Код соответствует PEP8 стилю кодирования
✅ Обработаны возможные ошибки и граничные случаи
✅ Логирование ключевых операций

Процесс разработки

Этап 1: Спецификация (Student 1)

Student 1 создал системную спецификацию в файле

• System Prompt с описанием задачи и ограничений
• Описание структуры данных
• Функциональные требования для трех основных функций
• Ограничения и условия использования
• Критерии приёмки

Этап 2: Реализация (Student 2)

Student 2 реализовал решение на основе спецификации, используя Cursor AI Assistant:

• Создан модуль
  dev/solution.py
  с FastAPI приложением
• Реализованы все три функции анализа
• Добавлена обработка ошибок и валидация данных
• Создан скрипт для генерации тестовых данных
• Код соответствует PEP8 стандартам

Этап 3: Code Review (Student 3)

Student 3 провел анализ кода на соответствие спецификации и качество реализации.

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

Для тестирования API можно использовать:

1. Интерактивную документацию Swagger UI:
   http://localhost:8000/docs
2. Команды curl (примеры приведены выше)
3. Python скрипты с использованием библиотеки
   requests

Пример тестового скрипта:

Лицензия

Этот проект создан в образовательных целях в рамках практического занятия по совместной разработке.

Моя работы в роли student2

• У пользователя Foutx
• Ссылка на репозиторий