save

dox/conf.py

@@ -37,6 +37,7 @@ extensions = [
     # "sphinx.ext.coverage",
     # "sphinx.ext.mathjax",
     # "sphinx.ext.ifconfig",
+    "sphinx.ext.autosectionlabel",
 
     # link source code
     "sphinx.ext.viewcode",
@@ -57,6 +58,8 @@ automodsumm_inherited_members = True
 automodapi_inheritance_diagram = False
 automodapi_toctreedirnm = '_api'
 # automodsumm_writereprocessed = True
+autosectionlabel_prefix_document = True
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

dox/index.rst

@@ -17,22 +17,24 @@ the class :class:`dios.DictOfSeries`. See
 
 For some recipes and advanced usage see:
 
+.. toctree::
+
+   indexingDocs
+
 .. toctree::
 
    cookbook
-   indexing_help
 
 For full module api documentation see:
 
 .. toctree::
    :maxdepth: 2
 
-   autodoc_diosapi
+   _diosApi
 
 or browse the Index..
 
 .. toctree::
-   :hidden:
 
    genindex
 

dox/indexing_help.md → dox/indexingDocs.md

-Indexing with .aloc
-===================
+Pandas-like indexing
+====================
+
+`[]` and `.loc[]`, `.iloc[]` and `.at[]`, `.iat[]` - should behave exactly like 
+their counter-parts from pandas.DataFrame. They can take as indexer 
+- lists, array-like objects and in general all iterables 
+- boolean lists and iterables
+- slices
+- scalars and any hashable object
+
+Most indexers are directly passed to the underling columns-series or row-series depending 
+on the position of the indexer and the complexity of the operation. For `.loc`, `.iloc`, `.at` 
+and `iat` the first position is the *row indexer*, the second the *column indexer*. The second 
+can be omitted and will default to `slice(None)`. Examples:
+- `di.loc[[1,2,3], ['a']]` : select labels 1,2,3 from column a
+- `di.iloc[[1,2,3], [0,3]]` : select positions 1,2,3 from the columns 0 and 3
+- `di.loc[:, 'a':'c']` : select all rows from columns a to d 
+- `di.at[4,'c']` : select the elements with label 4 in column c
+- `di.loc[:]` -> `di.loc[:,:]` : select everything. 
+
+Scalar indexing always return a pandas Series if the other indexer is a non-scalar. If both indexer
+are scalars, the element itself is returned. In all other cases a dios is returned. 
+For more pandas-like indexing magic and the differences between the indexers, 
+see the [pandas documentation](https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html).
 
-Purpose
---------
-- select gracefully, so rows or columns, that was given as indexer, but doesn't exist, not raise an error
+>**Note:**
+>
+>In contrast to pandas.DataFrame, `.loc[:]` and `.loc[:, :]` always behaves identical. Same apply for `iloc` and
+>[`aloc`](#the-special-indexer-aloc). For example, two pandas.DataFrames `df1` and `df2` with different columns,
+>does align columns with `df1.loc[:, :] = df2` , but does **not** with `df1.loc[:] = df2`. 
+>
+>If this is the desired behavior or a bug, i couldn't verify so far. -- Bert Palm 
+
+**2D-indexer**
+
+`dios[boolean dios-like]` (as single key) -  dios accept boolean 2D-indexer (boolean pandas.Dataframe 
+or boolean Dios). 
+
+Columns and rows from the indexer align with the dios. 
+This means that only matching columns selected and in this columns rows are selected where 
+i) indices are match and ii) the value is True in the indexer-bool-dios. There is no difference between
+missing indices and present indices, but False values.
+
+Values from unselected rows and columns are dropped, but empty columns are still preserved, 
+with the effect that the resulting Dios always have the same column dimension than the initial dios. 
+
+>**Note:**
+>This is the exact same behavior like pandas.DataFrame's handling of 2D-indexer, despite that pandas.DataFrame 
+>fill numpy.nan's at missing locations and therefore also fill-up, whole missing columns with numpy.nan's.
+
+**setting values**
+
+Setting values with `[]` and `.loc[]`, `.iloc[]` and `.at[]`, `.iat[]` works like in pandas. 
+With `.at`/`.iat` only single items can be set, for the other the
+right hand side values can be:
+ - *scalars*: these are broadcasted to the selected positions
+ - *lists*: the length the list must match the number of indexed columns. The items can be everything that 
+    can applied to a series, with the respective indexing method (`loc`, `iloc`, `[]`).
+ - *dios*: the length of the columns must match the number of indexed columns - columns does *not* align, 
+    they are just iterated. 
+    Rows do align. Rows that are present on the right but not on the left are ignored. 
+    Rows that are present on the left (bear in mind: these rows was explicitly chosen for write!), but not present
+    on the right, are filled with `NaN`s, like in pandas.
+ - *pandas.Series*: column indexer must be a scalar(!), the series is passed down, and set with `loc`, `iloc` or `[]` 
+    by pandas Series, where it maybe align, depending on the method. 
+
+**Examples:**
+
+- `dios.loc[2:5, 'a'] = [1,2,3]` is the same as `a=dios['a']; a.loc[2:5]=[1,2,3]; dios['a']=a`
+- `dios.loc[2:5, :] = 99` : set 99 on rows 2 to 5 on all columns
+
+Special indexer `.aloc`
+========================
+
+Additional to the pandas like indexers we have a `.aloc[..]` (align locator) indexing method. 
+Unlike `.iloc` and `.loc` indexers fully align if possible and 1D-array-likes can be broadcast 
+to multiple columns at once. This method also handle missing indexer-items gracefully. 
+It is used like `.loc`, so a single indexer (`.aloc[indexer]`) or a tuple of row-indexer and 
+column-indexer (`.aloc[row-indexer, column-indexer]`) can be given. Also it can handle boolean and *non-bolean*
+2D-Indexer.
+
+The main **purpose** of `.aloc` is:
+- to select gracefully, so rows or columns, that was given as indexer, but doesn't exist, not raise an error
 - align series/dios-indexer 
-- setting multiple columns at once with a list-like value
+- vertically broadcasting aka. setting multiple columns at once with a list-like value
+
+Aloc usage
+----------
 
-Overview
---------
 `aloc` is *called* like `loc`, with a single key, that act as row indexer `aloc[rowkey]` or with a tuple of
 row indexer and column indexer `aloc[rowkey, columnkey]`. Also 2D-indexer (like dios or df) can be given, but 
 only as a single key, like `.aloc[2D-indexer]` or with the special column key `...`, 
@@ -90,8 +168,8 @@ Values that are list- or array-like, which includes pd.Series, are set on all se
 like `s1.loc[:] = s2` do. See also the [cookbook](/docs/cookbook.md#broadcast-array-likes-to-multiple-columns).
 
 
-Indexer Table
--------------
+Aloc overiew table
+---------------------
 
 | example | type | on  | like `.loc` | handling | conditions / hints | link |
 | ------- | ---- | --- | ----------- | -------- | ------------------ | ---- |
@@ -147,9 +225,7 @@ Looks like so:
 Select columns, gracefully
 ---------------------------
 
-**Single columns**
-
-Use `.aloc[:, key]` to select a single column gracefully. 
+One can use `.aloc[:, key]` to select **single columns** gracefully. 
 The underling pandas.Series is returned, if the key exist. 
 Otherwise a empty pandas.Series with `dtype=object` is returned.