final touches on the changelog before the release

reordered by perceived importance, add a few links, remove broken links, etc.

Author: gdementen

doc/source/changes/version_0_30.rst.inc

@@ -4,114 +4,56 @@
 Syntax changes
 ^^^^^^^^^^^^^^
 
-* :py:obj:`LArray.as_table()` is deprecated. Please use :py:obj:`LArray.dump()` instead.
-
 * :py:obj:`stack()` ``axis`` argument was renamed to ``axes`` to reflect the fact that the function can now stack
   along multiple axes at once (see below).
 
+* to accommodate for the "simpler pattern language" now supported for those functions, using a regular expression in
+  :py:obj:`Axis.matching()` or :py:obj:`Group.matching()` now requires passing the pattern as an explicit ``regex``
+  keyword argument instead of just the first argument of those methods. For example ``my_axis.matching('test.*')``
+  becomes ``my_axis.matching(regex='test.*')``.
 
-Backward incompatible changes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* :py:obj:`LArray.equals()` now returns True for arrays even when axes are in a different order or some axes are
-  missing on either side (but the data is constant over that axis on the other side). To get back the old behavior, use
-  check_axes=True. Closes :issue:`237`.
-
-    >>> a = Axis('a=a0,a1')
-    >>> arr1 = ndtest(a)
-    >>> arr1
-    a  a0  a1
-        0   1
-
-    Identical arrays are (still) considered equal
-
-    >>> arr2 = arr1.copy()
-    >>> arr2.equals(arr1)
-    True
-
-    Arrays with different labels (for the same axes), are (still) not equal
-
-    >>> arr3 = arr1.set_labels('a', 'a8,a9')
-    >>> arr3
-    a  a8  a9
-        0   1
-    >>> arr3.equals(arr1)
-    False
-
-    Arrays with the same axes but different data, are (still) not equal
-
-    >>> arr4 = arr1.copy()
-    >>> arr4['a1'] = 42
-    >>> arr4
-    a  a0  a1
-        0  42
-    >>> arr4.equals(arr1)
-    False
-
-    Arrays with extra axes but the same data are now considered equal
+* ``LArray.as_table()`` is deprecated because it duplicated functionality found in :py:obj:`LArray.dump()`.
+  Please only use :py:obj:`LArray.dump()` from now on.
 
-    >>> arr5 = arr1.expand('b=b0..b2')
-    >>> arr5
-    a\b  b0  b1  b2
-     a0   0   0   0
-     a1   1   1   1
-    >>> arr5.equals(arr1)
-    True
-
-    Unless check_axes is True
-
-    >>> arr5.equals(arr1, check_axes=True)
-    False
-
-    Arrays with axes in a different order (but the same data) are also equal...
-
-    >>> arr6 = arr5.transpose()
-    >>> arr6
-    b\a  a0  a1
-     b0   0   1
-     b1   0   1
-     b2   0   1
-    >>> arr6.equals(arr5)
-    True
+* renamed ``a_min`` and ``a_max`` arguments of :py:obj:`LArray.clip()` to ``minval`` and ``maxval`` respectively
+  and made them optional (closes :issue:`747`).
 
-    Unless check_axes is True
 
-    >>> arr3.equals(arr4, check_axes=True)
-    False
+Backward incompatible changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* modified the behavior of the ``pattern`` argument of :py:obj:`Session.filter()` to work as the ``pattern``
-  argument of :py:obj:`Group.matching()`:
+* modified the behavior of the ``pattern`` argument of :py:obj:`Session.filter()` to actually support patterns instead
+  of only checking if the object names start with the pattern. Special characters include ``?`` for matching any single
+  character and ``*`` for matching any number of characters. Closes :issue:`703`.
 
-    >>> axis = Axis('a=a0..a2')
-    >>> group = axis['a0,a1'] >> 'a01'
-    >>> test1, zero1 = ndtest((2, 2)), zeros((3, 2))
-    >>> s = Session([('test1', test1), ('zero1', zero1), ('axis', axis), ('group', group)])
+  .. warning::
 
-    >>> # get all items with names ending with '1'
-    >>> s.filter(pattern='*1').names
-    ['test1', 'zero1']
+      If you were using Session.filter, you must add a ``*`` to your pattern to keep your code working.
+      For example, ``my_session.filter('test')`` must be changed to ``my_session.filter('test*')``.
 
-    >>> # get all items with names starting with letter in range a-k
-    >>> s.filter(pattern='[a-k]*').names
-    ['axis', 'group']
+* :py:obj:`LArray.equals()` now returns True for arrays even when axes are in a different order or some axes are
+  missing on either side (but the data is constant over that axis on the other side). Closes :issue:`237`.
 
-  Warning: to retrieve the previous behavior, add the character ``*`` to your pattern
-  (e.g. ``s.filter('test')`` becomes ``s.filter('test*')``).
+  .. warning::
 
-  Closes :issue:`703`.
+      If you were using :py:obj:`LArray.equals()` **and** want to keep the old, stricter, behavior, you must add
+      ``check_axes=True``.
 
 
 New features
 ^^^^^^^^^^^^
 
+* added :py:obj:`set_options()` and :py:obj:`get_options()` functions to respectively set and get options for larray.
+  Available options currently include ``display_precision`` for controlling the number of decimal digits used when
+  showing floating point numbers, ``display_maxlines`` to control the maximum number of lines to use when displaying
+  an array, etc. :py:obj:`set_options()` can used either like a normal function to set the options globally or within a
+  ``with`` block to set them only temporarily. Closes :issue:`274`.
+
 * implemented :py:obj:`read_stata()` and :py:obj:`LArray.to_stata()` to read arrays from and write arrays to Stata .dta
   files.
 
-* added :py:obj:`LArray.isin()` method to check whether each element of an array is contained in a list (or array) of
-  values.
-
-* implemented :py:obj:`LArray.keys()`, :py:obj:`LArray.values()` and :py:obj:`LArray.items()`
-  methods to respectively loop on an array labels, values or (key, value) pairs.
+* implemented :py:obj:`LArray.isin()` method to check whether each value of an array is contained in a list (or array)
+  of values.
 
 * implemented :py:obj:`LArray.unique()` method to compute unique values (or sub-arrays) for an array,
   optionally along axes.
@@ -123,19 +65,24 @@ New features
 * implemented :py:obj:`LArray.apply_map()` method to apply a transformation mapping to array elements. For example, this
   can be used to transform some numeric codes to labels.
 
+* implemented :py:obj:`LArray.reverse()` method to reverse one or several axes of an array (closes :issue:`631`).
+
+* implemented :py:obj:`LArray.roll()` method to roll the cells of an array n-times to the right along an axis. This is
+  similar to :py:obj:`LArray.shift()`, except that cells which are pushed "outside of the axis" are reintroduced on the
+  opposite side of the axis instead of being dropped.
+
 * implemented :py:obj:`Axis.apply()` method to transform an axis labels by a function and return a new Axis.
 
 * added :py:obj:`Session.update()` method to add and modify items from an existing session by passing
   either another session or a dict-like object or an iterable object with (key, value) pairs (closes :issue:`754`).
 
+* implemented :py:obj:`AxisCollection.rename()` to rename axes of an AxisCollection, independently of any array.
+
 * implemented :py:obj:`wrap_elementwise_array_func()` function to make a function defined in another library work with
   LArray arguments instead of with numpy arrays.
 
-* implemented :py:obj:`LArray.roll()` to roll the cells of an array n-times to the right along an axis. This is similar
-  to :py:obj:`LArray.shift()`, except that cells which are pushed "outside of the axis" are reintroduced on the opposite
-  side of the axis instead of being dropped.
-
-* implemented :py:obj:`AxisCollection.rename()` to rename axes of an AxisCollection, independently of any array.
+* implemented :py:obj:`LArray.keys()`, :py:obj:`LArray.values()` and :py:obj:`LArray.items()`
+  methods to respectively loop on an array labels, values or (key, value) pairs.
 
 * implemented :py:obj:`zip_array_values()` and :py:obj:`zip_array_items()` to loop respectively on several arrays values
   or (key, value) pairs.
@@ -147,9 +94,37 @@ New features
 Miscellaneous improvements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* implemented a simpler pattern language in :py:obj:`Axis.matching()` and :py:obj:`Group.matching()`. In addition to
-  regular expressions (which now require using the ``regexp`` argument), the two methods support the following simpler
-  patterns:
+* improved speed of :py:obj:`read_hdf()` function when reading a stored LArray object dumped with
+  the current and future version of larray. To get benefit of the speedup of reading arrays dumped
+  with older versions of larray, please read and re-dump them. Closes :issue:`563`.
+
+* allowed to not specify the axes in :py:obj:`LArray.set_labels()` (closes :issue:`634`):
+
+    >>> a = ndtest('nat=BE,FO;sex=M,F')
+    >>> a
+    nat\sex  M  F
+         BE  0  1
+         FO  2  3
+    >>> a.set_labels({'M': 'Men', 'BE': 'Belgian'})
+    nat\sex  Men  F
+    Belgian    0  1
+         FO    2  3
+
+* :py:obj:`LArray.set_labels()` can now take functions to transform axes labels (closes :issue:`536`).
+
+    >>> arr = ndtest((2, 2))
+    >>> arr
+    a\b  b0  b1
+     a0   0   1
+     a1   2   3
+    >>> arr.set_labels('a', str.upper)
+    a\b  b0  b1
+     A0   0   1
+     A1   2   3
+
+* implemented the same "simpler pattern language" in :py:obj:`Axis.matching()` and :py:obj:`Group.matching()` than in
+  :py:obj:`Session.filter()`. In addition to regular expressions (which now require using the ``regexp`` argument),
+  the two methods support the following simpler patterns:
 
     * `?`     matches any single character
     * `*`     matches any number of characters
@@ -180,18 +155,6 @@ Miscellaneous improvements
     >>> people.matching(pattern='[AB]*')
     people['Bruce Wayne', 'Bruce Willis', 'Arthur Dent']
 
-* :py:obj:`LArray.set_labels()` can now take functions to transform axes labels (closes :issue:`536`).
-
-    >>> arr = ndtest((2, 2))
-    >>> arr
-    a\b  b0  b1
-     a0   0   1
-     a1   2   3
-    >>> arr.set_labels('a', str.upper)
-    a\b  b0  b1
-     A0   0   1
-     A1   2   3
-
 * py:obj:`stack()` can now stack along several axes at once (closes :issue:`56`).
 
     >>> country = Axis('country=BE,FR,DE')
@@ -216,6 +179,8 @@ Miscellaneous improvements
   object, even on Python < 3.6. This will print a warning though because the ordering of labels is not guaranteed in
   that case.
 
+* added password argument to :py:obj:`Workbook.save()` to allow protecting Excel files with a password.
+
 * added option ``exact`` to ``join`` argument of :py:obj:`Axis.align()` and :py:obj:`LArray.align()` methods.
   Instead of aligning, passing ``join='exact'`` to the ``align`` method will raise an error when axes are not equal.
   Closes :issue:`338`.
@@ -235,7 +200,7 @@ Miscellaneous improvements
 
   Closes :issue:`669`.
 
-* allowed to specify an axis by its postion when selecting a subset of an array using the string notation:
+* allowed to specify an axis by its position when selecting a subset of an array using the string notation:
 
     >>> pop_mouv = ndtest('geo_from=BE,FR,UK;geo_to=BE,FR,UK')
     >>> pop_mouv
@@ -260,37 +225,10 @@ Miscellaneous improvements
 
 * updated the ``Working With Sessions`` section of the tutorial (closes :issue:`568`).
 
-* renamed `a_min` and `a_max` arguments of :py:obj:`LArray.clip()` as `minval` and `maxval` respectively
-  and made them optional (closes :issue:`747`).
-
 * added dtype argument to LArray to set the type of the array explicitly instead of relying on auto-detection.
 
 * added dtype argument to stack to set the type of the resulting array explicitly instead of relying on auto-detection.
 
-* implemented :py:obj:`LArray.reverse()` method to reverse one or several axes of an array (closes :issue:`631`).
-
-* added :py:obj:`set_options` allowing to set options for larray within a ``with`` block or globally:
-
-  The :py:obj:`get_options` function returns a view of the current options as a dictionary:
-
-  Closes :issue:`274`.
-
-* improved speed of :py:obj:`read_hdf()` function when reading a stored LArray object dumped with
-  the current and future version of larray. To get benefit of the speedup of reading arrays dumped
-  with older versions of larray, please read and re-dump them. Closes :issue:`563`.
-
-* allowed to not specifiy the axes in :py:obj:`LArray.set_labels()` (closes :issue:`634`):
-
-    >>> a = ndtest('nat=BE,FO;sex=M,F')
-    >>> a
-    nat\sex  M  F
-         BE  0  1
-         FO  2  3
-    >>> a.set_labels({'M': 'Men', 'BE': 'Belgian'})
-    nat\sex  Men  F
-    Belgian    0  1
-         FO    2  3
-
 * allowed to pass a single axis or group as ``axes_to_reindex`` argument
   of the :py:obj:`LArray.reindex()` method (closes :issue:`712`).
 
@@ -300,8 +238,6 @@ Miscellaneous improvements
   - light : to output axes labels only when they change instead of repeating them on each line
   - na_repr : to specify how to represent N/A (NaN) values
 
-* added password argument to :py:obj:`Workbook.save()` to allow protecting Excel files with a password.
-
 * substantially improved performance of creating, iterating, and doing a few other operations over larray objects.
   This solves a few pathological cases of slow operations, especially those involving many small-ish arrays but sadly
   the overall performance improvement is negligible over most of the real-world models using larray that we tested these