Merge pull request #7 from ajdapretnar/docs-trans

Transform: Updated documentation

Author: janezd

source/widgets/data/aggregatecolumns.md

@@ -6,32 +6,42 @@ Compute a sum, max, min ... of selected columns.
 **Inputs**
 
 - Data: input dataset
+- Features: list of attributes
 
 **Outputs**
 
 - Data: extended dataset
 
 **Aggregate Columns** outputs an aggregation of selected columns, for example a sum, min, max, etc.
 
-![](images/AggregateColumns.png)
+![](images/AggregateColumns-stamped.png){width=70%}
 
 1. Selected attributes.
-2. Operator for aggregation:
+2. Operators for aggregation:
    - sum
    - product
    - min
    - max
    - mean
    - variance
    - median
-3. Set the name of the computed attribute.
-4. If *Apply automatically* is ticked, changes will be communicated automatically. Alternatively, click *Apply*.
 
-Example
--------
+   *Output variable name*: Set the name of the computed attribute.
+3. If *Apply automatically* is ticked, changes will be communicated automatically. Alternatively, click *Apply*.
+
+Examples
+--------
 
 We will use iris data from the [File](../data/file.md) widget for this example and connect it to **Aggregate Columns**.
 
-Say we wish to compute a sum of *sepal_length* and *sepal_width* attributes. We select the two attributes from the list.
+Say we wish to compute a sum of *sepal_length* and *sepal_width* attributes. We select the two attributes from the list and apply the sum aggregator.
+
+We can observe the output in a [Data Table](../data/datatable.md).
+
+![](images/AggregateColumns-Example1.png)
+
+It is possible to pass the list of features to Aggregate Columns via its *Features* input. Say we find a pair of informative features in a [Scatter Plot](../visualize/scatterplot.md) and we would like to compute their sum.
+
+Beside the *Data* input, we also pass the *Features* input from the Scatter Plot to Aggregate Columns. The widget will, by default, use the input signal for variable selection. We retain the sum operation and change the name of the output variable to *petal sum*.
 
-![](images/AggregateColumns-Example.png)
+![](images/AggregateColumns-Example2.png)

source/widgets/data/applydomain.md

@@ -14,24 +14,21 @@ Given dataset and template transforms the dataset.
 
 **Apply Domain** maps new data into a transformed space. For example, if we transform some data with PCA and wish to observe new data in the same space, we can use Apply Domain to map the new data into the PCA space created from the original data.
 
-![](images/ApplyDomain.png)
+![](images/ApplyDomain.png){width=70%}
 
 The widget receives a dataset and a template dataset used to transform the dataset.
 
-Side note
---------
-
-Domain transformation works by using information from the template data. For example, for PCA, Components are not enough. Transformation requires information on the center of each column, variance (if the data is normalized), and if and how the data was preprocessed (continuized, imputed, etc.).
+**Side note.** Domain transformation works by using information from the template data. For example, for PCA, Components are not enough. Transformation requires information on the center of each column, variance (if the data is normalized), and if and how the data was preprocessed (continuized, imputed, etc.).
 
 Example
 -------
 
-We will use iris data from the [File](../data/file.md) widget for this example. To create two separate data sets, we will use [Select Rows](../data/selectrows.md) and set the condition to *iris is one of iris-setosa, iris-versicolor*. This will output a data set with a 100 rows, half of them belonging to iris-setosa class and the other half to iris-versicolor.
+We will use *iris* data from the [File](../data/file.md) widget for this example. To create two separate data sets, we will use [Select Rows](../data/selectrows.md) and set the condition to *iris is one of iris-setosa, iris-versicolor*. This will output a data set with a 100 rows, half of them belonging to iris-setosa class and the other half to iris-versicolor.
 
-We will transform the data with [PCA](../unsupervised/PCA.md) and select the first two components, which explain 96% of variance. Now, we would like to apply the same preprocessing on the 'new' data, that is the remaining 50 iris virginicas. Send the unused data from **Select Rows** to **Apply Domain**. Make sure to use the *Unmatched Data* output from **Select Rows** widget. Then add the *Transformed data* output from **PCA**.
+We will transform the data with [PCA](../unsupervised/PCA.md) and select the first two components, which explain 96% of variance. Now, we would like to apply the same preprocessing on the 'new' data, that is the remaining 50 iris virginicas. Send the unused data from **Select Rows** to **Apply Domain**. Make sure to use the *Unmatched Data* from **Select Rows** widget and connect it to Apply Domain as *Data*. Then connect the *Transformed Data* as *Template Data* output from **PCA**.
 
 **Apply Domain** will apply the preprocessor to the new data and output it. To add the new data to the old data, use [Concatenate](../data/concatenate.md). Use *Transformed Data* output from **PCA** as *Primary Data* and *Transformed Data* from **Apply Domain** as *Additional Data*.
 
-Observe the results in a [Data Table](../data/datatable.md) or in a [Scatter Plot](../visualize/scatterplot.md) to see the new data in relation to the old one.
+Observe the results in a [Scatter Plot](../visualize/scatterplot.md) to see how the new data can be plotted next to the old data.
 
 ![](images/ApplyDomain-Example.png)

source/widgets/data/continuize.md

@@ -1,7 +1,7 @@
 Continuize
 ==========
 
-Turns discrete variables (attributes) into numeric ("continuous") dummy variables.
+Turns categorical variables (attributes) into numeric ("continuous") dummy variables.
 
 **Inputs**
 
@@ -11,59 +11,43 @@ Turns discrete variables (attributes) into numeric ("continuous") dummy variable
 
 - Data: transformed data set
 
-The **Continuize** widget receives a data set in the input and outputs the same data set in which some or all categorical variables are replaced with continuous ones and numeric variables are scaled.
+The **Continuize** widget receives a data set in the input and outputs the same data set in which some or all categorical variables are replaced with numeric (continuous) ones and numeric variables are scaled.
 
 ![](images/Continuize-stamped.png)
 
-1. Select a categorical attribute to define its specific treatmen, or click the "Deafult" option above to set the default treatment for all categorical attributes without specific settings.
-
-    Multiple attributes can be chosen.
-
+1. Select a categorical attribute to define its specific treatment, or click the "Use default setting" option above to set the default treatment for all categorical attributes without specific settings.
+   Multiple attributes can be chosen.
 2. Define the treatment of categorical variables.
-
-    Examples in this section will assume that we have a categorical attribute *status* with values *low*, *middle* and *high*, listed in that order. Options for their transformation are:
-
+   Examples in this section will assume that we have a categorical attribute *status* with values *low*, *middle* and *high*, listed in that order. Options for their transformation are:
    - **Use default setting**: use the default treatment.
-
    - **Leave categorical**: leave the attribute as it is.
-
    - **First value as base**: a N-valued categorical variable will be transformed into N-1 numeric variables, each serving as an indicator for one of the original values except for the base value. The base value is the first value in the list. By default, the values are ordered alphabetically; their order can be changed in [Edit Domain](../data/editdomain).
-
-       In the above case, the three-valued variable *status* is transformed into two numeric variables, *status=middle* with values 0 or 1 indicating whether the original variable had value *middle* on a particular example, and similarly, *status=high*.
-
+       In the above case, the three-valued variable *status* is transformed into two numeric variables, *status=middle* with values 0 or 1 indicating whether the original variable had value *middle* on a particular example, and similarly, *status=high*. *Status=low* is indicated by both values being 0.
    - **Most frequent value as base**: similar to the above, except that the most frequent value is used as a base. So, if the most frequent value in the above example is *middle*, then *middle* is considered as the base and the two newly constructed variables are *status=low* and *status=high*.
-
-   - **One-hot encoding**: this option constructs one numeric variable per each value of the original variable. In the above case, we would get variables *status=low*, *status=middle* and *status=high*.
-
-   - **Remove if more than 3 values**: removes non-binary categorical variables from the data.
-
+   - **One-hot encoding**: this option constructs one numeric variable per each value of the original variable. In the above case, we would get three variables, *status=low*, *status=middle* and *status=high*.
+   - **Remove if more than 2 values**: removes non-binary categorical variables from the data.
    - **Remove**: removes the attribute.
-
-   - **Treat as ordinal**: converts the variable into a single numeric variable enumerating the original values. In the above case, the new variable would have the value of 0 for *low*, 1 for *middle* and 2 for *high*. Again note that the order of values can be set in  [Edit Domain](../data/editdomain).
-
+   - **Treat as ordinal**: converts the variable into a single numeric variable enumerating the original values. In the above case, the new variable would have the value of 0 for *low*, 1 for *middle* and 2 for *high*. Again note that the order of values can be set in [Edit Domain](../data/editdomain).
    - **Treat as normalized ordinal**: same as above, except that values are normalized into range 0-1. In our example, the values of the new variable would be 0, 0.5 and 1.
-
-3. Select attributes to set individual treatments or click "Default" to set the default treatment for numeric attributes.
-
+3. Select attributes for individual treatment or click "Default" to set the default treatment for numeric attributes.
 4. Define the treatment of numeric attributes. 
-
-   - **Use default setting**: use the general default.
+   - **Use default setting**: use the default treatment.
    - **Leave as it is**: do not change anything.
    - **Standardize**: subtract the mean and divide by the standard deviation (not available for sparse data).
    - **Center**: subtract the mean (not available for sparse data).
    - **Scale**: divide by standard deviation.
    - **Normalize to interval [-1, 1]**: linearly scale the values into interval [-1, 1] (not available for sparse data)
    - **Normalize to interval [0, 1]**: linearly scale the values into interval [0, 1] (not available for sparse data)
- 
-5. If checked, the class attribute is converted in the same fashion as categorical attributes that are treated as ordinal (see above).
+5. *Reset All* resets all variables to default option.
+   If *Apply automatically* is ticked, changes will be communicated automatically. Alternatively, click *Apply*.
 
 Examples
 --------
 
-First, let's see what is the output of the **Continuize** widget. We feed the original data (the *Heart disease* data set) into the [Data Table](../data/datatable) and see how they look like. Then we continuize the discrete values using various options and observe them in another [Data Table](../data/datatable).
+First, let's see what is the output of the **Continuize** widget. We feed the *heart_disease* data from the [File](../data/file.md) into the [Data Table](../data/datatable) and see how it looks like. Then we continuize the categorical variables using various options and observe them in another [Data Table](../data/datatable).
 
 ![](images/Continuize-Example1.png)
 
-In the second example, we show a typical use of this widget - in order to properly plot the linear projection of the data, discrete attributes need to be converted to continuous ones and that is why we put the data through the **Continuize** widget before drawing it. Gender, for instance, is transformed into two attributes "*gender=female*" and *gender=male*.
+In the second example, we show a typical use of this widget - in order to properly plot the linear projection of the data with the [Linear Projection](../visualize/linearprojection.md) widget, categorical attributes need to be converted to numeric ones and that is why we put the data through the **Continuize** widget before drawing it. Gender, for instance, is transformed into two attributes "*gender=female*" and *gender=male*.
 
 ![](images/Continuize-Example2.png)

source/widgets/data/createclass.md

@@ -1,7 +1,7 @@
 Create Class
 ============
 
-Create class attribute from a string attribute.
+Create class attribute from a string or categorical attribute.
 
 **Inputs**
 
@@ -11,28 +11,30 @@ Create class attribute from a string attribute.
 
 - Data: dataset with a new class variable
 
-**Create Class** creates a new class attribute from an existing discrete or string attribute. The widget matches the string value of the selected attribute and constructs a new user-defined value for matching instances.
+**Create Class** creates a new class attribute from an existing categorical or text attribute. The widget matches the string value of the selected attribute and constructs a new user-defined value for matching instances.
 
-![](images/CreateClass-stamped.png)
+![](images/CreateClass-stamped.png){width=50%}
 
-1. The attribute the new class is constructed from.
-2. Matching:
-   - Name: the name of the new class value
-   - Substring: regex-defined substring that will match the values from the above-defined attribute
-   - Instances: the number of instances matching the substring
-   - Press '+' to add a new class value
-3. Name of the new class column.
-4. Match only at the beginning will begin matching from the beginning of the string. Case sensitive will match by case, too.
-5. Produce a report.
-6. Press *Apply* to commit the results.
+1. Name of the new class column.
+2. Match by Substring:
+   *From column*: The attribute the new class is constructed from.
+   *Name*: the name of the new class value
+   *Substring*: substring that will match the values from the above-defined attribute
+   *Count*: the number of instances matching the substring
+   Press '+' to add a new class value
+3. Options:
+   - *Use regular expressions* to match by [regular expressions](https://en.wikipedia.org/wiki/Regular_expression).
+   - *Match only at the beginning* will begin matching from the beginning of the string.
+   - *Case sensitive* will match by case, too.
+4. Press *Apply* to commit the results.
 
 Example
 -------
 
-Here is a simple example with the *auto-mpg* dataset. Pass the data to **Create Class**. Select *car_name* as a column to create the new class from. Here, we wish to create new values that match the car brand. First, we type *ford* as the new value for the matching strings. Then we define the substring that will match the data instances. This means that all instances containing *ford* in their *car_name*, will now have a value *ford* in the new class column. Next, we define the same for *honda* and *fiat*. The widget will tell us how many instance are yet unmatched (remaining instances). We will name them *other*, but you can continue creating new values by adding a condition with '+'.
+Here is a simple example with the *auto-mpg* dataset. Pass the data to **Create Class**. Select *car name* as a column to create the new class from. Here, we wish to create new values that match the car brand.
 
-We named our new class column *car_brand* and we matched at the beginning of the string.
+First, we type *ford* as the new value for the matching strings. Then we define the substring that will match the data instances. This means that all instances containing *ford* in their *car name*, will now have a value *ford* in the new class column. We define the same for *honda* and *fiat*. The widget will tell us how many instance are yet unmatched (remaining instances). It says 326, plus the already defined 72. We will name the remaining instances *other*, but you can continue creating new values by adding a condition with '+'.
 
 ![](images/CreateClass-example.png)
 
-Finally, we can observe the new column in a [Data Table](../data/datatable.md) or use the value as color in the [Scatter Plot](../visualize/scatterplot.md).
+Finally, we can observe the new column in a [Data Table](../data/datatable.md).

source/widgets/data/csvfileimport.md

@@ -12,7 +12,7 @@ The **CSV File Import** widget reads comma-separated files and sends the dataset
 
 *Data Frame* output can be used in the [Python Script](../data/pythonscript.md) widget by connecting it to the `in_object` input (e.g. `df = in_object`). Then it can be used a regular DataFrame.
 
-### Import Options
+## Import Options
 
 The import window where the user sets the import parameters. Can be re-opened by pressing *Import Options* in the widget.
 
@@ -41,7 +41,7 @@ Right click on the column name to set the column type. Right click on the row in
    - *Ignore*: do not output the column.
 4. Pressing *Reset* will return the settings to the previously set state (saved by pressing OK in the Import Options dialogue). *Restore Defaults* will set the settings to their default values. *Cancel* aborts the import, while *OK* imports the data and saves the settings.
 
-### Widget
+## Widget
 
 The widget once the data is successfully imported.
 
@@ -51,7 +51,7 @@ The widget once the data is successfully imported.
 2. Information on the imported data set. Reports on the number of instances (rows), variables (features or columns) and meta variables (special columns).
 3. *Import Options* re-opens the import dialogue where the user can set delimiters, encodings, text fields and so on. *Cancel* aborts data import. *Reload* imports the file once again, adding to the data any changes made in the original file.
 
-### Encoding
+## Encoding
 
 The dialogue for settings custom encodings list in the Import Options - Encoding dropdown. Select *Customize Encodings List...* to change which encodings appear in the list. To save the changes, simply close the dialogue. Closing and reopening Orange (even with Reset widget settings) will not re-set the list. To do this, press *Restore Defaults*. To have all the available encodings in the list, press *Select all*.