Merge pull request #10 from ajdapretnar/documentation

Updated documentation for k-Means and PolyReg

doc/widgets/images/interactive-kmeans-tags.txt

@@ -0,0 +1,4 @@
+0	139	38
+1	154	86
+2	154	182
+3	154	592

doc/widgets/images/polynomial-regression-tags.txt

@@ -0,0 +1,3 @@
+0	182	34
+1	182	87
+2	182	482

doc/widgets/kmeans.rst

@@ -1,86 +1,104 @@
 Interactive k-means
 ===================
 
-.. figure:: icons/mywidget.png
+.. figure:: icons/interactive-kmeans.png
 
-Educational widgets that shows working of a k-means clustering.
+Educational widget that shows the working of a k-means clustering.
 
 Signals
 -------
-Inputs
-~~~~~~
-- **Data**
+
+**Inputs**:
+
+-  **Data**
+
 Input data set.
 
-Outputs
-~~~~~~~
+**Outputs**:
+
+-  **Data**
 
-- **Data**
-Data set with clusters labels annotation.
+Data set with cluster annotation.
 
-- **Centroids**
-Centroids position
+-  **Centroids**
+
+Centroids position.
 
 Description
 -----------
 
-The aim of this widget is to show the working of a k-means clustering algorithm on two attributes from data set.
-Widget applies k-means clustering to the selected two attributes step by step. User can step through the algorithm and
-see how the algorithm works.
+The aim of this widget is to show the working of a `k-means clustering algorithm <https://en.wikipedia.org/wiki/K-means_clustering>`__
+on two attributes from a data set. The widget applies k-means clustering to the selected two attributes step by step. Users can step 
+through the algorithm and see how it works.
+
+.. figure:: images/interactive-kmeans-stamped.png
+
+1. Select attributes for **x** and **y** axis.
 
-.. figure:: images/kmeanswidget1.png
+2. *Number of centroids*: set the number of centroids.
 
-1. Select attribute for **x** axis and attribute for **y** axis.
+   *Randomize*: randomly assigns position of centroids. If you want to add centroid on a particular position in the graph,
+   click on this position. If you want to move the centroid, drag and drop it on the desired position.
 
-2. Select number of centroids in the spinner. If you want new random positions of the centroids or restart the algorithm
-   in any point, you can click on **Randomize** button. If you want to add centroid on particular position in the graph
-   just click on this position. If you want to move centroid, grab it and drop it on the desired position.
+   *Show membership lines*: if ticked, connection between data points and closest centroids are shown. 
 
-3. Step through the algorithm with **Recompute centroids** and **Reassign membership**. If you want to make step back
-   use **Step back** button. You can also step automatically with pressing on **Run** button. **Speed** spinner can be used
-   to set the speed of automatic stepping.
+3. **Recompute centroids** or **Reassign membership**: step through different stages of the algoritm. *Recompute centroids* moves centroids to new positions, based on the most central position of the data assigned to the centroid. *Reassign membership* reassigns data points to the centroid they are the closest to.
+
+   **Step back**: make a step back in the algorithm.
+
+   **Run**: step through the algorithm automatically. 
+
+   **Speed**: set the speed of automatic stepping.
+
+4. *Save Image* saves the image to the computer in a .svg or .png
+   format.
 
 
 Example
 -------
 
-Here are two possible schemas that shows how the **Interactive k-Menas** widget can be used. You can load data form
-**File** or use any other data source, such as **Paint Data**. Interactive k-Menas widget also produce the data table
-with results of clustering and table with centroids positions. That can be inspected with **Data Table** widget or andy
-other widgets (e.g. Scatter Plot).
+Here are two possible schemas that show how the **Interactive k-Means** widget can be used. You can load the data from
+**File** or use any other data source, such as 
+**Paint Data**. Interactive k-Means widget also produces a data table
+with results of clustering and a table with centroids positions. These data can be inspected with the
+**Data Table** widget.
+
+.. figure:: images/interactive-kmeans-input.png
+
+Let us demonstrate the working of the widget on *Iris* data set.
 
-.. figure:: images/orangekmeans1.png
+We provide the data using **File**. 
+Then we open **Interactive k-Means**. Say, we will demonstrate k-Means on *petal length* and *petal width* attributes, 
+so we set them as *X* and *Y* parameters. We also decided to perform clustering for 3 clusters. This is set as the 
+*Number of centroids*.
 
-Let us demonstrate the working of the widget on *Iris Dataset*.
+.. figure:: images/interactive-kmeans-step1.png
 
-We provide data from data set using **File widget**. Then we open **Interactive k-Means** widget. We decided that we
-will demonstrate k-Menas on *petal length* and *petal width* attributes, so we set them as *X* and *Y* parameters.
-We also decided to perform a clustering in 3 clusters. This is set as *Number of centroids*. After that we get this
-figure.
+If we are not satisfied with positions of centroids we can change them with a click on the **Randomize** button. Then we
+perform the first recomputing of centroids with a click on the **Recompute centroids**. We get the following image.
 
-.. figure:: images/kmeansstep1.png
+.. figure:: images/interactive-kmeans-step2.png
 
-If we are not satisfied with positions of centroids we can change it with click on **Randomize** button. Then we
-perform first recomputing of centroids with click on **Recompute centroids** button. We get following image.
+The next step is to reassign membership of all points to the closest centroid. This is performed with a click on
+the **Reasign membership** button.
 
-.. figure:: images/kmeansstep2.png
+.. figure:: images/interactive-kmeans-step3.png
 
-The next step is to reassign membership of point to the closest centroid. It is performed with click on
-**Reasign membership** button.
+Then we repeat these two steps until the algorithm converges. This is the final result.
 
-.. figure:: images/kmeansstep3.png
+.. figure:: images/interactive-kmeans-step4.png
 
-Then we repeat that two steps until algorithm converges. It is final result.
+Perhaps we are not satisfied with the result because we noticed that maybe classification into 4 clusters would be better.
+So we decided to add a new centroid. We can do this by increasing the number of centroids in the control menu or with a click on
+the position in the graph where we want to place the centroid. We decided to add it with a click. The new centroid is the orange one.
 
-.. figure:: images/kmeanssteplast.png
+.. figure:: images/interactive-kmeans-step5.png
 
-But we are not satisfied with result because we noticed that maybe classification in 4 clusters would be better.
-So we decided to add a new centroid. We can make it with increasing number of centroids in left menu or with click on
-position in graph where we want to place the centroid. We decided to add it with click. New centroid is red one.
+Now we can repeat running the algorithm until it converges again, but before that we will move the new centroid to 
+change the behavior of the algorithm. We grabbed the orange centroid and moved it to the desired position.
 
-.. figure:: images/kmeansnewcentroid.png
+.. figure:: images/interactive-kmeans-step6.png
 
-Now we can repeat some steps that algorithm converges again, but before we will move green centroid to change the
-behavior of the algorithm. We grab green centroid and moved it to desired position.
+Then we press *Run* and observe the centroids while the algorithm converges again.
 
-.. figure:: images/kmeansstepmovedc.png
+.. figure:: images/interactive-kmeans-step7.png

doc/widgets/univariatepolynomialregression.rst

@@ -3,27 +3,26 @@ Polynomial Regression
 
 .. figure:: icons/polynomialregression.png
 
-Educational widgets that interactively shows what regression line is provided for with different regressors.
+Educational widget that interactively shows regression line for different regressors.
 
 Signals
 -------
-Inputs
-~~~~~~
+
+**Inputs**:
 
 - **Data**
 
-Input data set.
+Input data set. It needs at least two continuous attributes.
 
 - **Preprocessor**
 
 Data preprocessors.
 
 - **Learner**
 
-Regression algorithm used in the widget.
+Regression algorithm used in the widget. Default set to Linear Regression.
 
-Outputs
-~~~~~~~
+**Outputs**:
 
 - **Learner**
 
@@ -40,40 +39,45 @@ Regressor coefficients if it has them.
 Description
 -----------
 
-This widget interactively shows regression line using different regressors from Orange3 Regression module provided on
-the input. In widget **Polynomial expansion** can be set. Polynomial expansion is regulation of the degree
-of polynom that is used to transform input data and has an effect on the shape of a curve. If polynomial expansion is
-set to 1 it means that untransformed data are used in regression.
+This widget interactively shows regression line using any of the regressors from *Orange3 Regression* module. 
+In the widget, `polynomial expansion <https://en.wikipedia.org/wiki/Polynomial_expansion>`__ can be set. 
+Polynomial expansion is a regulation of the degree of polynom that is used to transform the input data and has an effect 
+on the shape of a curve. If polynomial expansion is set to 1 it means that untransformed data are used in the regression.
 
-.. figure:: images/polyregressionmain.png
+.. figure:: images/polynomial-regression-stamped.png
 
-1. Provide data with at least two continuous attributes on input. Also provide any regression learner on input (if
-   not provided *Linear Regression* is used.
+1. Regressor name.
 
-3. Open widget and select **Imput** and **Target** feature in a dropdown menu.
+2. *Input*: independent variable on axis x.
 
-2. Select the degree of a polynomial expansion. With changing it you can see the difference between the
-   regression lines with different degree.
+   *Polynomial expansion*: degree of polynomial expansion.
 
-3. **Apply** button chan be used to submit changes on output.
+   *Target*: dependent variable on axis y.
+
+3. *Save Image* saves the image to the computer in a .svg or .png
+   format.
+
+   *Report* includes widget parameters and visualization in the report.
 
 Example
 -------
 
-With *File* widget we loaded *Iris* data set. We also connect *Linear Regression* learner as show on figure above.
-In widget we selected *petal length* as an **Input** feature and *petal width* as a **Target**.
-We set **Polynomial expansion** to 1 what gives us linear regression line. Result is show on the figure below.
+.. figure:: images/polyregressionmain.png
+
+We loaded *iris* data set with the **File** widget. 
+Then we connected **Linear Regression** learner to the **Polynomial Regression** widget.
+In the widget we selected *petal length* as our *Input* variable and *petal width* as our *Target* variable.
+We set *Polynomial expansion* to 1 which gives us a linear regression line. The result is shown on the figure below.
 
-.. figure:: images/polyregression1.png
+.. figure:: images/polynomial-regression-exp1.png
 
-We noticed that line can fit better if we increase **Polynomial expansion** parameter. We set it to 3.
+The line can fit better if we increase the **Polynomial expansion** parameter. Say, we set it to 3.
 
-.. figure:: images/polyregression2.png
+.. figure:: images/polynomial-regression-exp3.png
 
-We decided that results that we got with *Linear Regression* does not satisfy us so we changed the learner with
-*Regression Tree* learner.
+To observe different results, change **Linear Regression** to any other regression learner from Orange. Example below is done with **Regression Tree** learner.
 
 .. figure:: images/polyregressiontree1.png
 
-.. figure:: images/polyregressiontree2.png
+.. figure:: images/polynomial-regression-tree-exp1.png