Further improvements to the documentation.

biolab · sstanovnik · Jun 10, 2016 · Jun 17, 2016 · Jun 17, 2016 · Jun 22, 2016
commit b561d2fd4e68b9480cbc1dc500cd2269c47e8d76
diff --git a/doc/data-mining-library/source/reference/data.domain.rst b/doc/data-mining-library/source/reference/data.domain.rst
@@ -157,7 +157,7 @@ Domain conversion
     In a typical scenario, we may want to discretize some continuous data before
     inducing a model. Discretizers (:mod:`Orange.preprocess`)
     construct a new data table with attribute descriptors
-    (:class:`Orange.data.variable`), that include the corresponding functions
+    (:class:`Orange.data.Variable`), that include the corresponding functions
     for conversion from continuous to discrete values. The trained model stores
     this domain descriptor and uses it to convert instances from the original
     domain to the discretized one at prediction phase.

diff --git a/doc/data-mining-library/source/reference/data.rst b/doc/data-mining-library/source/reference/data.rst
@@ -24,26 +24,23 @@ variable's name, symbolic values, number of decimals in printouts and similar.
 
 The data is divided into attributes (features, independent variables), class
 variables (classes, targets, outcomes, dependent variables) and meta
-attributes. This division applies to domain descriptions, data storages that
-contain separate arrays for each of the three parts of the data and data
-instances.
+attributes. This division applies to domain descriptions, which logically separate
+a :obj:`Orange.data.Table` into three parts, corresponding to the roles.
 
 Attributes and classes are represented with numeric values and are used in
 modelling. Meta attributes contain additional data which may be of any type.
 (Currently, only string values are supported in addition to continuous and
 numeric.)
 
-In indexing, columns can be referred to by their names,
-descriptors or an integer index. For example, if `inst` is a data instance
-and `var` is a descriptor of type :obj:`~Orange.data.Continuous`, referring to
-the first column in the data, which is also names "petal length", then
-`inst[var]`, `inst[0]` and `inst["petal length"]` refer to the first value
-of the instance. Negative indices are used for meta attributes, starting with
--1.
-
-Continuous and discrete values can be represented by any numerical type; by
-default, Orange uses double precision (64-bit) floats. Discrete values are
-represented by whole numbers.
+Indexing is inherited from :obj:`pandas`. This means using `.loc` and `.iloc`
+to access rows and slice the table, the same as :obj:`pandas` does. The only
+difference is that Orange uses globally unique indexing, where different instances
+of :obj:`Orange.data.Table` have different :obj:`pandas` indices, used with `.loc`.
+Columns are accessed either with domain variables or their names.
+
+Orange stores data directly in the :obj:`Orange.data.Table` exactly like `pandas` does,
+and the `.X`, `.Y` and `.metas` descriptors convert the raw data into a float format,
+suitable for learning. Columns with :obj:`Orange.data.StringVariable` remain as strings.
 
 .. toctree::
     :maxdepth: 2

diff --git a/doc/data-mining-library/source/reference/data.table.rst b/doc/data-mining-library/source/reference/data.table.rst
@@ -7,63 +7,34 @@ Data Table (``table``)
 .. autoclass:: Orange.data.Table
     :members: columns
 
-    Stores data instances as a set of 2d tables representing the independent
+    Stores data instances in a dense :obj:`pandas.DataFrame` representing the independent
     variables (attributes, features) and dependent variables
     (classes, targets), and the corresponding weights and meta attributes.
 
-    The data is stored in 2d numpy arrays :obj:`X`, :obj:`Y`, :obj:`W`,
-    :obj:`metas`. The arrays may be dense or sparse. All arrays have the same
+    2D numpy arrays :obj:`X`, :obj:`Y`, :obj:`W`, :obj:`metas` can be generated.
+    The arrays may be dense or sparse. All arrays have the same
     number of rows. If certain data is missing, the corresponding array has
     zero columns.
 
     Arrays can be of any type; default is `float` (that is, double precision).
-    Values of discrete variables are stored as whole numbers.
     Arrays for meta attributes usually contain instances of `object`.
 
     The table also stores the associated information about the variables
     as an instance of :obj:`Domain`. The number of columns must match the
     corresponding number of variables in the description.
 
-    There are multiple ways to get values or entire rows of the table.
+    Indexing the table works the same as in `pandas`. In a nutshell
 
-    - The index can be an int, e.g. `table[7]`; the corresponding row is
-      returned as an instance of :obj:`RowInstance`.
+    - Use `table.iloc[i]` for position-based indexing.
+    - Use `table.loc[i]` for index-based indexing.
+    - Both accept tuples of `(row_index, column_name)` or slices where appropriate.
+    - Use table[colname] to get columns.
 
-    - The index can be a slice or a sequence of ints (e.g. `table[7:10]` or
-      `table[[7, 42, 15]]`, indexing returns a new data table with the
-      selected rows.
+    One-domensional alternatives are called `Series`.
 
-    - If there are two indices, where the first is an int (a row number) and
-      the second can be interpreted as columns, e.g. `table[3, 5]` or
-      `table[3, 'gender']` or `table[3, y]` (where `y` is an instance of
-      :obj:`~Orange.data.Variable`), a single value is returned as an instance
-      of :obj:`~Orange.data.Value`.
-
-    - In all other cases, the first index should be a row index, a slice or
-      a sequence, and the second index, which represent a set of columns,
-      should be an int, a slice, a sequence or a numpy array. The result is
-      a new table with a new domain.
-
-    Rules for setting the data are as follows.
-
-    - If there is a single index (an `int`, `slice`, or a sequence of row
-      indices) and the value being set is a single scalar, all
-      attributes (not including the classes) are set to that value. That
-      is, `table[r] = v` is equivalent to `table.X[r] = v`.
-
-    - If there is a single index and the value is a data instance
-      (:obj:`Orange.data.Instance`), it is converted into the table's domain
-      and set to the corresponding rows.
-
-    - Final option for a single index is that the value is a sequence whose
-      length equals the number of attributes and target variables. The
-      corresponding rows are set; meta attributes are set to unknowns.
-
-    - For two indices, the row can again be given as a single `int`, a
-       `slice` or a sequence of indices. Column indices can be a single
-       `int`, `str` or :obj:`Orange.data.Variable`, a sequence of them,
-       a `slice` or any iterable. The value can be a single value, or a
-       sequence of appropriate length.
+    Setting data works the same as in `pandas`. The only thing you need to be careful
+    of is that chaining indexers, as in `table.iloc[0].iloc[0]` won't work and
+    shouldn't be used, use `table.iloc[0, 0]` instead.
 
     .. attribute:: domain
 
@@ -79,23 +50,40 @@ The preferred way to construct a table is to invoke a named constructor.
 
 .. automethod:: Table.from_domain
 .. automethod:: Table.from_table
+.. automethod:: Table.from_dataframe
 .. automethod:: Table.from_numpy
+.. automethod:: Table.from_list
 .. automethod:: Table.from_file
+.. automethod:: Table.from_url
+
+Getting Data
+------------
+.. automethod:: Table.X
+.. automethod:: Table.Y
+.. automethod:: Table.metas
+.. automethod:: Table.weights
 
 Inspection
 ----------
 
+.. automethod:: Table.has_weights
+.. automethod:: Table.approx_len
+.. automethod:: Table.exact_len
 .. automethod:: Table.has_missing
-.. automethod:: Table.has_missing_class
+.. automethod:: Table.density
+.. automethod:: Table.is_dense
+.. automethod:: Table.is_sparse
 
-Row manipulation
-----------------
+Manipulation
+------------
 
-.. automethod:: Table.clear
+.. automethod:: Table.concatenate
+.. automethod:: Table.merge
 
 Weights
 -------
 
+.. automethod:: Table.weights
 .. automethod:: Table.set_weights
 
 Aggregators