Upload folder using huggingface_hub

README.md

@@ -0,0 +1,151 @@
+---
+language: en
+license: mit
+tags:
+- music
+- audio-features
+- popularity-prediction
+- random-forest
+- regression
+- spotify
+library_name: sklearn
+pipeline_tag: tabular-regression
+---
+
+# 🎵 Acoustic Hit Predictor v1.0
+
+Модель машинного обучения для прогнозирования популярности музыкальных треков на основе акустических характеристик из Spotify API.
+
+## 📊 Описание модели
+
+**Random Forest Regressor** обученная на 114,000 треков для предсказания популярности (0-100).
+
+### Параметры модели:
+- `n_estimators`: 50
+- `max_depth`: 30
+- `min_samples_split`: 5
+- `min_samples_leaf`: 2
+- `max_features`: 'sqrt'
+
+## 📈 Метрики качества
+
+| Метрика | Train | Test | Оценка |
+|---------|-------|------|--------|
+| MAE | 6.40 | 11.44 | ✅ Хорошо |
+| R² | - | 0.52 | ⚠️ Средне |
+| Стабильность CV | 0.98% | - | ✅ Отлично |
+
+**Погрешность:** ±11 пунктов популярности в среднем
+
+## 🎯 Основные характеристики
+
+- ⚡ **Быстрый инференс:** ~1ms на трек
+- 📊 **Признаков:** 30 (оригинальные + производные)
+- ⏱️ **Время обучения:** 67.3 минуты
+- 💾 **Размер:** 231 MB
+
+## 🔍 Feature Importance
+
+### Топ-5 факторов популярности:
+1. **Danceability** — главный драйвер (среднее: 0.68)
+2. **Energy** — умеренное влияние (среднее: 0.58)
+3. **Valence** — позитивность (среднее: 0.47)
+4. **Loudness** — технический фактор
+5. **Tempo** — оптимально 110-130 BPM
+
+## 💪 Сильные стороны
+
+- ✅ Стабильная работа на средних значениях популярности (40-65)
+- ✅ Хорошая генерализация (MAE 10.74 vs 11.44)
+- ✅ Правильное понимание роли танцевальности
+- ✅ Быстрая batch-обработка
+
+## ⚠️ Слабые стороны
+
+- Консервативность (редко предсказывает > 65)
+- Проблемы с мега-хитами (popularity > 80)
+- Систематическая недооценка в 70% случаев
+- Не учитывает временной и культурный контекст
+
+## 📥 Использование
+
+```python
+import pickle
+import pandas as pd
+
+# Загрузка модели
+with open('final_random_forest_model.pkl', 'rb') as f:
+    model = pickle.load(f)
+
+# Подготовка данных (пример)
+features = pd.DataFrame({
+    'danceability': [0.7],
+    'energy': [0.8],
+    'loudness': [-5.0],
+    'speechiness': [0.05],
+    'acousticness': [0.1],
+    'instrumentalness': [0.0],
+    'liveness': [0.1],
+    'valence': [0.6],
+    'tempo': [120.0],
+    'duration_ms': [200000],
+    'key': [5],
+    'mode': [1],
+    'time_signature': [4]
+    # + производные признаки (см. feature engineering)
+})
+
+# Предсказание
+popularity = model.predict(features)
+print(f"Предсказанная популярность: {popularity[0]:.1f}/100")
+```
+
+## 🎯 Интерпретация результатов
+
+```
+Предсказанная популярность:
+  0-30  → ❌ Слабый потенциал
+  30-50 → ⚠️ Средний потенциал
+  50-70 → ✅ Хороший потенциал
+  70+   → 🎯 Высокий потенциал (модель редко так предсказывает)
+```
+
+## ✅ Подходит для:
+- **Независимых артистов** — первичная оценка потенциала трека
+- **Продюсеров** — сравнение разных версий композиции
+- **A&R менеджеров** — скрининг демо-материалов
+- **Исследователей** — анализ факторов популярности
+
+## 🚫 Ограничения:
+- Не предсказывает мега-хиты (80+)
+- Не учитывает маркетинг и промо
+- Не заменяет экспертное мнение
+- Работает только на аудио-характеристиках
+
+## 📚 Дополнительные ресурсы
+
+- **GitHub репозиторий:** [Acoustic-Hit-Predictor](https://github.com/mmobik/Acoustic-Hit-Predictor-From-Audio-Features-to-Chart-Success)
+- **Детальный анализ:** См. `reports/model_analysis.md` в репозитории
+- **Техническая спецификация:** См. `TECHNICAL_SPECIFICATION.md`
+
+## 📄 Лицензия
+
+MIT License
+
+## 👨‍💻 Автор
+
+**mmobik**
+- GitHub: [@mmobik](https://github.com/mmobik)
+
+## 📅 Версия
+
+- **Дата обучения:** Декабрь 2024
+- **Версия:** 1.0
+- **Статус:** MVP (Minimum Viable Product)
+
+## 🔄 Планируемые улучшения
+
+1. Добавление большего количества треков с popularity > 80
+2. Калибровка предсказаний для крайних значений
+3. Временные признаки (год релиза, сезонность)
+4. Метаданные (жанр, лейбл, популярность артиста)

final_random_forest_model.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0b37f50b223c82612e45147ce4a8aad896545cb8930a53114bf3425f3e0017e1
+size 242313937