{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Руководство по использованию модели artm.LDA в библиотеке BigARTM."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Автор - **Мурат Апишев** (great-mel@yandex.ru)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Модель LDA модуля artm предназначена для использования пользователями с минимальными представлениями о тематическом моделировании и теории аддитивной регуляризации тематических моделей. Она представляет собой урезанную версию модели artm.ARTM с предопрделёнными регуляризаторами и метриками качества. Возможностей artm.LDA достаточно для обучения соответствующей модели с регуляризаторами сглаживания/разреживания матриц $\\Phi$ и $\\Theta$ с помощью оффлайнового или онлайнового алгоритмов и извлечения результатов в виде самих матриц, а также метрик перплексии, разреженностей матриц и наиболее вероятных слов в каждой теме."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Информацию об интерфейсе artm.LDA можно найти здесь: http://bigartm.readthedocs.org/en/master/python_interface/lda.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Проведём модельный эксперимент с использованием коллекции kos в формате UCI. О том, как пользоваться BatchVectorizer, что такое словари и т.п. можно прочесть по этой ссылке во вводном разделе: http://nbviewer.ipython.org/github/bigartm/bigartm-book/blob/master/ARTM_tutorial_RU.ipynb\n",
    "\n",
    "Скачать коллекцию kos можно тут: https://archive.ics.uci.edu/ml/machine-learning-databases/bag-of-words/\n",
    "\n",
    "Там же описано, что из себя представляет формат UCI Bag-Of-Words. Вам потребуются два файла: docword.kos.txt и vocab.kos.txt. Эти два файла надо положить в одну директорию с этим ноутбуком.\n",
    "\n",
    "Импортируем модуль artm, создадим BatchVectorizer и запустим внутри него сборку словаря (если Вас интересует, что это такое, то об этом можно прочесть по ссылке выше, для понимания описываемого кода достаточно знать, что словарь содержит список всех уникальных слов коллекции с некоторой информацией, и нужен для инициализации модели и корректного подсчёта перплексии):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1 . Самая базовая часть."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.8.0\n"
     ]
    }
   ],
   "source": [
    "import artm\n",
    "\n",
    "print artm.version()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "batch_vectorizer = artm.BatchVectorizer(data_path='.', data_format='bow_uci',\n",
    "                                        collection_name='kos', target_folder='kos_batches')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Теперь создадим саму тематическую модель, указав число тем и параметр числа прохода по документу, гиперпараметры сглаживания матриц $\\Phi$ и $\\Theta$, а также используемый словарь. Кроме того, попросим сохранять матрицу $\\Theta$, чтобы потом на неё можно было взглянуть.\n",
    "\n",
    "\n",
    "Здесь же можно указать параметр num_processors, отвечающий за число потоков, которые будут использованы для вычислений на машине."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "lda = artm.LDA(num_topics=15, alpha=0.01, beta=0.001,\n",
    "               num_document_passes=5, dictionary=batch_vectorizer.dictionary,\n",
    "               cache_theta=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Запустим процесс обучения с помощью оффлайнового алгоритма:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "lda.fit_offline(batch_vectorizer=batch_vectorizer, num_collection_passes=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Всё, на этом всё обучение окончено. Дальше можно повторять последнюю команду, редактировать параметры модели и т.п.\n",
    "\n",
    "Уже сейчас можно посмотреть на результаты моделирования. Например, на финальные значения разреженностей матриц:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "lda.sparsity_phi_last_value\n",
    "lda.sparsity_theta_last_value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Или на значения перпелексии на каждой итерации прохода по коллекции:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "lda.perplexity_value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Наконец, можно посмотреть на наиболее вероятные слова в каждой теме. Они выдаются в виде списка списков строк (каждый внутренний список соответствуюет одной теме, по порядку). Выведем их, предварительно отформатировав:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "top_tokens = lda.get_top_tokens(num_tokens=10)\n",
    "for i, token_list in enumerate(top_tokens):\n",
    "    print 'Topic #{0}: {1}'.format(i, token_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Можно получить доступ к матрицам с помощью следующих вызовов:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "phi = lda.phi_\n",
    "theta = lda.get_theta()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Чуть больше деталей."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Опишем ещё ряд возможностей модели artm.LDA.\n",
    "\n",
    "Во-первых - это построение матрицы $\\Theta$ для новых документов при наличии обученной модели:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "batch_vectorizer = artm.BatchVectorizer(data_path='kos_batches_test')\n",
    "theta_test = lda.transform(batch_vectorizer=test_batch_vectorizer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Во-вторых, в том случае, если требуется производить различную регуляризацию каждой из тем в матрице $\\Phi$, вместо скалярного значения beta можно задать список гиперпараметров, длиной в число тем, и каждая тема будет регуляризована со своим гиперпараметром:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "beta = [0.1] * num_topics  # change as you need\n",
    "lda = artm.LDA(num_topics=15, alpha=0.01, beta=beta, num_document_passes=5, dictionary=dictionary, cache_theta=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Заключение"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Эта модель - самый простой способ использования BigARTM. От Вас не требуется ничего, кроме преобразования данных в формат BigARTM с помощью BatchVectorizer, у которого есть подробное описание в руководстве и документации, и запуска нескольких описанных выше строк кода.\n",
    "\n",
    "В случае необходимости более продвинутого использования библиотеки, нужно воспользоваться модель artm.ARTM, подробное описание которой есть в основном руководстве."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}