update from master

Author: xtonev

topicnet/.gitignore

@@ -23,4 +23,3 @@
 *.pyc
 
 bigartm*
-.DS_Store

topicnet/README-rus.md

@@ -0,0 +1,23 @@
+## TopicNet 
+[English version](README.md)
+
+Библиотека ```topicnet``` создана для автоматизации и унификации практик тематического моделирования. Она помогает снять с пользователя заботу о рутинной составляющей моделирования, освободив время для творческого процесса подбора функционала отвечающего критериям задачи.
+На данный момент библиотека представлена тремя модулями:
+
+
+* ```cooking_machine``` - отвечает за логирование эксперимента по построению тематических моделей и связь между сущностями образующими эксперимент.
+
+
+* ```viewers``` - помогает визуализовать информацию о полученной тематической модели в доступном для экспериментатора формате.
+
+
+* ```tests``` - помогает проверить правильность установки библиотеки TopicNet и содержит примеры работы с кодом библиотеки.
+
+---
+### Описание
+Важно отметить, что на каждом шаге эксперимента используется один и тот же кубик для дальнейшей настройки моделей.
+Если для разным тематических моделей после очередного этапа обучения применяются разные кубики, то эксперимент разделяется на два отдельных эксперимента, которые отличаются данным и последующими этапами обучения, иными словами последовательностями применения кубиков с соответствующими им параметрам.
+Объект эксперимента содержит всю необходимую информацию для воспроизведения данного эксперимента с нуля и изменяется в процессе добавления кубиков пользователя.  
+При использовании кубиков также изменяется информация о моделях и их описание, создаются новые модели копии основной, которые соответствуют перебираемым внутри кубика параметрам.  
+Описание моделей также позволяет построить их по описанию и создать скрипт их создания и обучения.
+Таким образом, ключевым объектом - является кубик, а точнее их последовательность, которые взаимодействуют с объектами модель и эксперимент.

topicnet/README.md

@@ -1,3 +1,22 @@
-## TopicNet 
-
-Модуль ```topicnet``` предоставляет многосторонний подход к тематическому моделированию.
+## TopicNet 
+[Русская версия](README-rus.md)
+
+```topicnet```  library was created to assist in the task of building topic models. It aims to automate away many routine tasks related to topic model training, allowing a user to focus on the task at hand. Also, it provides additional tools to construct advanced topic models.
+The library consists of three modules:
+
+
+* ```cooking_machine``` - a module providing tools to design a topic model construction pipeline, or experiment with regularizers fitting
+
+
+* ```viewers``` - provides information about the topic model in an accessible format.
+
+
+* ```tests``` - provides a user with means to test library functionality and contains examples of intended library usage.
+
+---
+###  Project description
+In TopicNet framework, advanced topic models are build using Experiment class.
+An experiment consists of stages (that we call "cubes") which perform actions over the "models" which are objects of the Experiment. The experiment instance of Experiment class contains all the information about the experiment process and automatically updates its log when a cube is applied to the last level models.
+It is worth noting that the experiment is linear, meaning it does not support multiple different cubes at the same stage of the experiment. If that need arises one is recommended to create a new experiment with a new cube on the last level.
+The experiment instance of Experiment class contains all the information about the *experiment process* and automatically updates its log when the cube is applied to the last level models.
+Summarizing: the key entity Experiment is a sequence of cubes that produce models on each stage of the *experiment process*

topicnet/cooking_machine/README-rus.md

@@ -0,0 +1,38 @@
+# Cooking Machine
+[English version](README.md)
+
+### Общее описание
+Эксперимент состоит из моделей и кубиков, которые добавляют в эти модели новые регуляризаторы и осущеcтвляют подбор различных параметров тематичеcких моделей на каждом этапе обучения.
+
+
+#### Кубик
+Кубик -- это сущность, задающая некоторое преобразование над моделями ("инКУБатор"). Обычно это преобразование параметрическое, и эти параметры перебираются по сетке; на выходе кубика -- семейство новых моделей (копии основной), которые соответствуют перебираемым внутри кубика параметрам.
+
+**Вход:** модель или модели, регуляризатор или регуляризаторы, параметры перебора (сетка), число итераций или метод выбора числа итераций, внешние метрики (которых нет в BigArtm, опционально).  
+**Выход:** модели (их число совпадает с числом параметров в сетке или наборов параметров, если сетка многомерная).  
+**Тело:** внутри себя содержит функциональные действия с `artm` моделью, вносить изменения в объект модели, создает модели, вносит изменения в объект эксперимента.
+
+#### Модель
+Смысловая единица хранения модели и ее описания:
+
+* хранит своё описание;
+* выводит описание в human-readable виде;
+* преобразует описание модели в скрипт создания этой модели;
+* не дает с собой ничего сделать, кроме как подгрузить и сделать свою копию (immutable), сама artm-модель хранится как атрибут этой модели, для ее изменения, ее нужно достать и самой модели, а после изменения заложить обратно;
+* хранит id эксперимента;
+* хранит id модели-родителя (если это пустая модель, то None);
+* хранит имена тем;
+* хранит список регуляризаторов с коэффициентами и другими параметрами;
+* хранит список модальностей с весами;
+* хранит пути к данным и сохраненной модели и информации о ней;
+* хранит значения метрик;
+* хранит результаты обучения.
+
+#### Эксперимент
+Объект Experiment содержит всю необходимую информацию для воспроизведения данного эксперимента с нуля и изменяется в процессе добавления кубиков пользователя. 
+
+* хранит своё описание;
+* выводит описание в human-readable виде;
+* хранит описание стратегии обучения;
+* проверяет свою целостность при считывании;
+* делает свою копию, копию части себя.

topicnet/cooking_machine/README.md

@@ -1,44 +1,32 @@
 # Cooking Machine
-
-### Общее описание
-Эксперимент состоит из моделей и кубиков, которые добавляют в эти модели новые регуляризаторы и осущетвляют подбор различных параметров тематичеких моделей на каждом этапе обучения.
-
-Важно отметить, что на каждом шаге эксперимента используется один и тот же кубик для дальнейшей настройки моделей.
-Если для разным тематических моделей после очередного этапа обучения применяются разные кубики, то эксперимент разделяется на два отдельных эксперимента, которые отличаются данным и последующими этапами обучения, иными словами последовательностями применения кубиков с соответствующими им параметрам.
-Объект эксперимента содержит всю необходимую информацию для воспроизведения данного эксперимента с нуля и изменяется в процессе добавления кубиков пользователя.
-При использовании кубиков также изменяется информация о моделях и их описание, создаются новые модели копии основной, которые соответствуют перебираемым внутри кубика параметрам.
-Описание моделей также позволяет построить их по описанию и создать скрипт их создания и обучения.
-Таким образом, ключевым объектом - является кубик, а точнее их последовательность, которые взаимодействуют с объектами модель и эксперимент.
-
-#### Кубик
-Смысловая единица обучения модели, которая вводит регуляризатор/регуляризаторы и перебирает его/их коэффициенты по сетке.
-Внутри себя кубик вносит изменения в объекты модель (он еще и создает новые модели) и в объект эксперимент.
-
-**Вход:** модель или модели, регуляризатор или регуляризаторы, параметры перебора (сетка), число итераций или метод выбора числа итераций, внешние метрики (которых нет в BigArtm, опционально).  
-**Выход:** модели (их число совпадает с числом параметров в сетке или наборов параметров, если сетка многомерная).  
-**Тело:** внутри себя содержит функциональные действия с `artm` моделью, вносить изменения в объект модели, создает модели, вносит изменения в объект эксперимента.
-
-#### Модель
-Смысловая единица хранения модели и ее описания:
-
-* хранит своё описание;
-* выводит описание в human-readable виде;
-* преобразует описание модели в скрипт создания этой модели;
-* не дает с собой ничего сделать, кроме как подгрузить и сделать свою копию (immutable), сама artm-модель хранится как атрибут этой модели, для ее изменения, ее нужно достать и самой модели, а после изменения заложить обратно;
-* хранит id эксперимента;
-* хранит id модели-родителя (если это пустая модель, то None);
-* хранит имена тем;
-* хранит список регуляризаторов с коэффициентами и другими параметрами;
-* хранит список модальностей с весами;
-* хранит пути к данным и сохраненной модели и информации о ней;
-* хранит значения метрик;
-* хранит результаты обучения.
-
-#### Эксперимент
-Смысловая единица описания эксперимента с обучением тематических моделей:
-
-* хранит своё описание;
-* выводит описание в human-readable виде;
-* хранит описание стратегии обучения;
-* проверяет свою целостность при считывании;
-* делает свою копию, копию части себя.
+[Русская версия](README-rus.md)
+
+#### Cube
+A unit of model training pipeline. This unit encapsulates an action over one or many model hyperparameters. This action and hyperparameter space are stored as cube properties and then saved in Experiment. 
+
+**Input:** model or list of models, regularizer or list of them, hyperparameter search sapce(grid), iterations number or a function defining it, custom metrics.  
+**Output:** models.  
+**Body:** performs actions over `artm` model. Can modify, create new models and alter their Experiment.
+
+#### Model
+A class containing Topic Model and its description:
+
+* stores topic model description;
+* outputs the description in human-readable form;
+* the model can only load and copy itself, the artm-model is an attribute and in order to change it is should be extracted, modified and put back;
+* stores experiment id;
+* stores parent model id;
+* stores model topic names;
+* stores regularizers list with their parameters;
+* stores modality weights;
+* stores save path for data, model and model information;
+* stores training metric values.
+
+#### Experiment
+Class providing experiment infrastructure:
+
+* keeps the description of all actions on the models;
+* provides human-readable log of experiment;
+* keeps the model training sequence in memory;
+* automaticly runs integrity check;
+* able to copy itself.