{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Собираем словари со-встречаемостей"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Данный notebook содержит примеры команд и скриптов, с помощью которых можно собрать словари со-встречаемостей. Все необходимые для запуска файлы находятся в https://github.com/bigartm/bigartm-book/tree/master/junk/cooc_dictionary. Просьба прочитать для начала разделы в документации по сборке файлов со-встречаемостей:\n",
    "- http://docs.bigartm.org/en/stable/tutorials/bigartm_cli.html\n",
    "- http://docs.bigartm.org/en/stable/tutorials/python_userguide/coherence.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Предположим, мы склонировали репозиторий и находимся в дирректории с файлами (важно использовать последнюю версию master, иначе если использовать слишком старую версию, результаты могут быть другими). Посмотрим, что у нас есть:\n",
    "```bash\n",
    "ls -l\n",
    "-rwxrwxrwx 1 root root     91 Jul  8 22:15 clean.sh\n",
    "-rwxrwxrwx 1 root root  42383 Jul  8 22:32 cooc_df_\n",
    "-rwxrwxrwx 1 root root  42383 Jul  8 22:32 cooc_tf_\n",
    "-rwxrwxrwx 1 root root 163798 Jul  8 22:19 dictionary.txt\n",
    "-rwxrwxrwx 1 root root  32617 Jul  8 22:34 example_of_gathering.ipynb\n",
    "-rwxrwxrwx 1 root root   2557 Jul  8 22:19 get_vocab.ipynb\n",
    "-rwxrwxrwx 1 root root    199 Jul  8 22:32 launch.sh\n",
    "-rwxrwxrwx 1 root root  46099 Jul  8 22:32 ppmi_df_\n",
    "-rwxrwxrwx 1 root root  54793 Jul  8 22:32 ppmi_tf_\n",
    "-rwxrwxrwx 1 root root  64380 Jul  8 22:19 vocab.txt\n",
    "-rwxrwxrwx 1 root root  95266 May 10 20:22 vw.txt\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- `vw.txt` $-$ коллекция в Vowpal Wabbit формате, в этом файле каждая документ записан в отдельной строке, первый токен в строке - название документа, далее в произвольных местах могут находиться токены, начинающиеся с символа '|', они обозначают модальность. Все последующие токены в документе (которые не начинаются с '|') относятся к этой модальности. Дефолтная модальность обозначается |@default_class. Если в документе не была указана модальность, то считается, что токены относятся к дефолтной модальности;\n",
    "- `vocab.txt` $-$ словарь валидных токенов, со-встречаемости которых будут подсчитаны. Пока что со-встречаемости считаются только внутри модальностей, то есть если 2 токена из разных модальностей, такие со-встречаемости учитываться не будут. Если токен не принадлежит дефолтной модальности (т.е. @default_class), его модальность необходимо указать в `vocab.txt`. Стоит обратить внимание, что в vocab модальность указывется без символа '|', к примеру, @default_class;\n",
    "- ноутбук `get_vocab.ipynb` позволяет получить `vocab.txt` по `vw.txt`, в него записываются все уникальные токены коллекции (за исключением токенов модальностей). Обратите внимание, ноутбук пишет `vocab.txt` и `dictionary.txt` в папку `batches`;\n",
    "- `dictionary.txt` $-$ artm dictionary, собранный по `vw.txt`, побочный результат работы `get_vocab.ipynb`, в принципе может пригодиться для дальнейших экспериментов с коллекцией;\n",
    "- скрипт `clean.sh` производит очистку текущей дирректории от промежуточных файлов (необязателен, но с ним удобнее);\n",
    "- файлы `cooc_tf_`, `cooc_df_`, `ppmi_tf_`, `ppmi_df_` $-$ файлы со-встречаемостей и посчитанные по ним PPMI, результат работы алгоритма;\n",
    "- `launch.sh` $-$ скрипт для запуска утилиты подсчёта со-встречаемостей и PPMI."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Заглянем внутрь `launch.sh`:\n",
    "```bash\n",
    "#! /bin/bash\n",
    "\n",
    "bigartm -c vw.txt -v vocab.txt --cooc-window 10 --cooc-min-tf 5 --write-cooc-tf cooc_tf_\n",
    "--cooc-min-df 5 --write-cooc-df cooc_df_ --write-ppmi-tf ppmi_tf_ --write-ppmi-df \n",
    "ppmi_df_\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Что данные ключи значат, по порядку:\n",
    "- `-c` $-$ прочитать коллекцию;\n",
    "- `-v` $-$ прочитать vocab;\n",
    "- `--cooc-window` $-$ задать ширину окна (со-встречаемость токенов учитывается только внутри некоторого окна);\n",
    "- `--cooc-min-tf` $-$ задать минимальное значение cooc TF (значение ниже данного порога не будут писаться в выходной файл);\n",
    "- `--cooc-min-df` $-$ аналогично предыдущему, только для cooc DF;\n",
    "- `--write-cooc-tf` $-$ записать файл с cooc TF по заданному пути, далее указывается путь;\n",
    "- `--write-cooc-df`, `--write-ppmi-tf`, `--write-ppmi-df` $-$ аналогично для файлов cooc DF, PPMI TF, PPMI DF."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Сейчас те, кто не прочитал документацию, могут не понять, что такое cooc TF, какие-то PPMI, дублируем:\n",
    "\n",
    "#### positive PMI: $PPMI(u,v)=\\left[\\log\\cfrac{n(u,v)n}{n(u)n(v)}\\right]_{+}$;\n",
    "\n",
    "#### Cooc TF: $n(u, v) = \\sum_{d = 1}^{|D|}$ $\\sum_{i = 1}^{N_d}$ $\\sum_{j = 1}^{N_d}$ $[0 < |i - j| \\leq k]$ $[w_{di} = u]$ $[w_{dj} = v]$;\n",
    "\n",
    "#### Cooc DF: $n(u, v) = \\sum_{d = 1}^{|D|} [\\, \\exists \\, i, j : w_{di} = u, w_{dj} = v, 0 < |i - j| \\leq k]$.\n",
    "\n",
    "По сути cooc TF означает сколько раз пара встретилась в коллекции внутри окна заданной ширины, а cooc DF $-$ в скольких документах она встретилась хотя бы раз в окне."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В данном примере коллекция взята довольно маленькая $-$ просто, чтоб показать, как всё работает.\n",
    "Конечно, по таким маленьким коллекциях оценивать близость пар слов - не самая лучшая идея, их надо оценивать на больших коллекциях типа Википедии, на которых дисперсия оценки вероятностей относительно маленькая."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Часто задаваемые вопросы и ошибки\n",
    "\n",
    "- Почему утилита отработала, а никакие файлы не создались. **Ответ**: такое может быть только в случае, если утилита не нашла ни 1 со-встречаемости. Возожно, в vocab неправильно указаны модальности (или не указаны вовсе, но в тексте коллекции все слова в недефолтной модальности) или выбран слишком высокий порог, так что со-встречаемость всех пар оказалась ниже порога."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}