Skip to content

Commit ee8ef74

Browse files
gdementengdementen
committed
final touches on the changelog before the release
reordered by perceived importance, add a few links, remove broken links, etc.
1 parent 1758892 commit ee8ef74

File tree

1 file changed

+73
-137
lines changed

1 file changed

+73
-137
lines changed

‎doc/source/changes/version_0_30.rst.inc

Lines changed: 73 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -4,114 +4,56 @@
44
Syntax changes
55
^^^^^^^^^^^^^^
66

7-
* :py:obj:`LArray.as_table()` is deprecated. Please use :py:obj:`LArray.dump()` instead.
8-
97
* :py:obj:`stack()` ``axis`` argument was renamed to ``axes`` to reflect the fact that the function can now stack
108
along multiple axes at once (see below).
119

10+
* to accommodate for the "simpler pattern language" now supported for those functions, using a regular expression in
11+
:py:obj:`Axis.matching()` or :py:obj:`Group.matching()` now requires passing the pattern as an explicit ``regex``
12+
keyword argument instead of just the first argument of those methods. For example ``my_axis.matching('test.*')``
13+
becomes ``my_axis.matching(regex='test.*')``.
1214

13-
Backward incompatible changes
14-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15-
16-
* :py:obj:`LArray.equals()` now returns True for arrays even when axes are in a different order or some axes are
17-
missing on either side (but the data is constant over that axis on the other side). To get back the old behavior, use
18-
check_axes=True. Closes :issue:`237`.
19-
20-
>>> a = Axis('a=a0,a1')
21-
>>> arr1 = ndtest(a)
22-
>>> arr1
23-
a a0 a1
24-
0 1
25-
26-
Identical arrays are (still) considered equal
27-
28-
>>> arr2 = arr1.copy()
29-
>>> arr2.equals(arr1)
30-
True
31-
32-
Arrays with different labels (for the same axes), are (still) not equal
33-
34-
>>> arr3 = arr1.set_labels('a', 'a8,a9')
35-
>>> arr3
36-
a a8 a9
37-
0 1
38-
>>> arr3.equals(arr1)
39-
False
40-
41-
Arrays with the same axes but different data, are (still) not equal
42-
43-
>>> arr4 = arr1.copy()
44-
>>> arr4['a1'] = 42
45-
>>> arr4
46-
a a0 a1
47-
0 42
48-
>>> arr4.equals(arr1)
49-
False
50-
51-
Arrays with extra axes but the same data are now considered equal
15+
* ``LArray.as_table()`` is deprecated because it duplicated functionality found in :py:obj:`LArray.dump()`.
16+
Please only use :py:obj:`LArray.dump()` from now on.
5217

53-
>>> arr5 = arr1.expand('b=b0..b2')
54-
>>> arr5
55-
a\b b0 b1 b2
56-
a0 0 0 0
57-
a1 1 1 1
58-
>>> arr5.equals(arr1)
59-
True
60-
61-
Unless check_axes is True
62-
63-
>>> arr5.equals(arr1, check_axes=True)
64-
False
65-
66-
Arrays with axes in a different order (but the same data) are also equal...
67-
68-
>>> arr6 = arr5.transpose()
69-
>>> arr6
70-
b\a a0 a1
71-
b0 0 1
72-
b1 0 1
73-
b2 0 1
74-
>>> arr6.equals(arr5)
75-
True
18+
* renamed ``a_min`` and ``a_max`` arguments of :py:obj:`LArray.clip()` to ``minval`` and ``maxval`` respectively
19+
and made them optional (closes :issue:`747`).
7620

77-
Unless check_axes is True
7821

79-
>>> arr3.equals(arr4, check_axes=True)
80-
False
22+
Backward incompatible changes
23+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8124

82-
* modified the behavior of the ``pattern`` argument of :py:obj:`Session.filter()` to work as the ``pattern``
83-
argument of :py:obj:`Group.matching()`:
25+
* modified the behavior of the ``pattern`` argument of :py:obj:`Session.filter()` to actually support patterns instead
26+
of only checking if the object names start with the pattern. Special characters include ``?`` for matching any single
27+
character and ``*`` for matching any number of characters. Closes :issue:`703`.
8428

85-
>>> axis = Axis('a=a0..a2')
86-
>>> group = axis['a0,a1'] >> 'a01'
87-
>>> test1, zero1 = ndtest((2, 2)), zeros((3, 2))
88-
>>> s = Session([('test1', test1), ('zero1', zero1), ('axis', axis), ('group', group)])
29+
.. warning::
8930

90-
>>> # get all items with names ending with '1'
91-
>>> s.filter(pattern='*1').names
92-
['test1', 'zero1']
31+
If you were using Session.filter, you must add a ``*`` to your pattern to keep your code working.
32+
For example, ``my_session.filter('test')`` must be changed to ``my_session.filter('test*')``.
9333

94-
>>> # get all items with names starting with letter in range a-k
95-
>>> s.filter(pattern='[a-k]*').names
96-
['axis', 'group']
34+
* :py:obj:`LArray.equals()` now returns True for arrays even when axes are in a different order or some axes are
35+
missing on either side (but the data is constant over that axis on the other side). Closes :issue:`237`.
9736

98-
Warning: to retrieve the previous behavior, add the character ``*`` to your pattern
99-
(e.g. ``s.filter('test')`` becomes ``s.filter('test*')``).
37+
.. warning::
10038

101-
Closes :issue:`703`.
39+
If you were using :py:obj:`LArray.equals()` **and** want to keep the old, stricter, behavior, you must add
40+
``check_axes=True``.
10241

10342

10443
New features
10544
^^^^^^^^^^^^
10645

46+
* added :py:obj:`set_options()` and :py:obj:`get_options()` functions to respectively set and get options for larray.
47+
Available options currently include ``display_precision`` for controlling the number of decimal digits used when
48+
showing floating point numbers, ``display_maxlines`` to control the maximum number of lines to use when displaying
49+
an array, etc. :py:obj:`set_options()` can used either like a normal function to set the options globally or within a
50+
``with`` block to set them only temporarily. Closes :issue:`274`.
51+
10752
* implemented :py:obj:`read_stata()` and :py:obj:`LArray.to_stata()` to read arrays from and write arrays to Stata .dta
10853
files.
10954

110-
* added :py:obj:`LArray.isin()` method to check whether each element of an array is contained in a list (or array) of
111-
values.
112-
113-
* implemented :py:obj:`LArray.keys()`, :py:obj:`LArray.values()` and :py:obj:`LArray.items()`
114-
methods to respectively loop on an array labels, values or (key, value) pairs.
55+
* implemented :py:obj:`LArray.isin()` method to check whether each value of an array is contained in a list (or array)
56+
of values.
11557

11658
* implemented :py:obj:`LArray.unique()` method to compute unique values (or sub-arrays) for an array,
11759
optionally along axes.
@@ -123,19 +65,24 @@ New features
12365
* implemented :py:obj:`LArray.apply_map()` method to apply a transformation mapping to array elements. For example, this
12466
can be used to transform some numeric codes to labels.
12567

68+
* implemented :py:obj:`LArray.reverse()` method to reverse one or several axes of an array (closes :issue:`631`).
69+
70+
* implemented :py:obj:`LArray.roll()` method to roll the cells of an array n-times to the right along an axis. This is
71+
similar to :py:obj:`LArray.shift()`, except that cells which are pushed "outside of the axis" are reintroduced on the
72+
opposite side of the axis instead of being dropped.
73+
12674
* implemented :py:obj:`Axis.apply()` method to transform an axis labels by a function and return a new Axis.
12775

12876
* added :py:obj:`Session.update()` method to add and modify items from an existing session by passing
12977
either another session or a dict-like object or an iterable object with (key, value) pairs (closes :issue:`754`).
13078

79+
* implemented :py:obj:`AxisCollection.rename()` to rename axes of an AxisCollection, independently of any array.
80+
13181
* implemented :py:obj:`wrap_elementwise_array_func()` function to make a function defined in another library work with
13282
LArray arguments instead of with numpy arrays.
13383

134-
* implemented :py:obj:`LArray.roll()` to roll the cells of an array n-times to the right along an axis. This is similar
135-
to :py:obj:`LArray.shift()`, except that cells which are pushed "outside of the axis" are reintroduced on the opposite
136-
side of the axis instead of being dropped.
137-
138-
* implemented :py:obj:`AxisCollection.rename()` to rename axes of an AxisCollection, independently of any array.
84+
* implemented :py:obj:`LArray.keys()`, :py:obj:`LArray.values()` and :py:obj:`LArray.items()`
85+
methods to respectively loop on an array labels, values or (key, value) pairs.
13986

14087
* implemented :py:obj:`zip_array_values()` and :py:obj:`zip_array_items()` to loop respectively on several arrays values
14188
or (key, value) pairs.
@@ -147,9 +94,37 @@ New features
14794
Miscellaneous improvements
14895
^^^^^^^^^^^^^^^^^^^^^^^^^^
14996

150-
* implemented a simpler pattern language in :py:obj:`Axis.matching()` and :py:obj:`Group.matching()`. In addition to
151-
regular expressions (which now require using the ``regexp`` argument), the two methods support the following simpler
152-
patterns:
97+
* improved speed of :py:obj:`read_hdf()` function when reading a stored LArray object dumped with
98+
the current and future version of larray. To get benefit of the speedup of reading arrays dumped
99+
with older versions of larray, please read and re-dump them. Closes :issue:`563`.
100+
101+
* allowed to not specify the axes in :py:obj:`LArray.set_labels()` (closes :issue:`634`):
102+
103+
>>> a = ndtest('nat=BE,FO;sex=M,F')
104+
>>> a
105+
nat\sex M F
106+
BE 0 1
107+
FO 2 3
108+
>>> a.set_labels({'M': 'Men', 'BE': 'Belgian'})
109+
nat\sex Men F
110+
Belgian 0 1
111+
FO 2 3
112+
113+
* :py:obj:`LArray.set_labels()` can now take functions to transform axes labels (closes :issue:`536`).
114+
115+
>>> arr = ndtest((2, 2))
116+
>>> arr
117+
a\b b0 b1
118+
a0 0 1
119+
a1 2 3
120+
>>> arr.set_labels('a', str.upper)
121+
a\b b0 b1
122+
A0 0 1
123+
A1 2 3
124+
125+
* implemented the same "simpler pattern language" in :py:obj:`Axis.matching()` and :py:obj:`Group.matching()` than in
126+
:py:obj:`Session.filter()`. In addition to regular expressions (which now require using the ``regexp`` argument),
127+
the two methods support the following simpler patterns:
153128

154129
* `?` matches any single character
155130
* `*` matches any number of characters
@@ -180,18 +155,6 @@ Miscellaneous improvements
180155
>>> people.matching(pattern='[AB]*')
181156
people['Bruce Wayne', 'Bruce Willis', 'Arthur Dent']
182157

183-
* :py:obj:`LArray.set_labels()` can now take functions to transform axes labels (closes :issue:`536`).
184-
185-
>>> arr = ndtest((2, 2))
186-
>>> arr
187-
a\b b0 b1
188-
a0 0 1
189-
a1 2 3
190-
>>> arr.set_labels('a', str.upper)
191-
a\b b0 b1
192-
A0 0 1
193-
A1 2 3
194-
195158
* py:obj:`stack()` can now stack along several axes at once (closes :issue:`56`).
196159

197160
>>> country = Axis('country=BE,FR,DE')
@@ -216,6 +179,8 @@ Miscellaneous improvements
216179
object, even on Python < 3.6. This will print a warning though because the ordering of labels is not guaranteed in
217180
that case.
218181

182+
* added password argument to :py:obj:`Workbook.save()` to allow protecting Excel files with a password.
183+
219184
* added option ``exact`` to ``join`` argument of :py:obj:`Axis.align()` and :py:obj:`LArray.align()` methods.
220185
Instead of aligning, passing ``join='exact'`` to the ``align`` method will raise an error when axes are not equal.
221186
Closes :issue:`338`.
@@ -235,7 +200,7 @@ Miscellaneous improvements
235200

236201
Closes :issue:`669`.
237202

238-
* allowed to specify an axis by its postion when selecting a subset of an array using the string notation:
203+
* allowed to specify an axis by its position when selecting a subset of an array using the string notation:
239204

240205
>>> pop_mouv = ndtest('geo_from=BE,FR,UK;geo_to=BE,FR,UK')
241206
>>> pop_mouv
@@ -260,37 +225,10 @@ Miscellaneous improvements
260225

261226
* updated the ``Working With Sessions`` section of the tutorial (closes :issue:`568`).
262227

263-
* renamed `a_min` and `a_max` arguments of :py:obj:`LArray.clip()` as `minval` and `maxval` respectively
264-
and made them optional (closes :issue:`747`).
265-
266228
* added dtype argument to LArray to set the type of the array explicitly instead of relying on auto-detection.
267229

268230
* added dtype argument to stack to set the type of the resulting array explicitly instead of relying on auto-detection.
269231

270-
* implemented :py:obj:`LArray.reverse()` method to reverse one or several axes of an array (closes :issue:`631`).
271-
272-
* added :py:obj:`set_options` allowing to set options for larray within a ``with`` block or globally:
273-
274-
The :py:obj:`get_options` function returns a view of the current options as a dictionary:
275-
276-
Closes :issue:`274`.
277-
278-
* improved speed of :py:obj:`read_hdf()` function when reading a stored LArray object dumped with
279-
the current and future version of larray. To get benefit of the speedup of reading arrays dumped
280-
with older versions of larray, please read and re-dump them. Closes :issue:`563`.
281-
282-
* allowed to not specifiy the axes in :py:obj:`LArray.set_labels()` (closes :issue:`634`):
283-
284-
>>> a = ndtest('nat=BE,FO;sex=M,F')
285-
>>> a
286-
nat\sex M F
287-
BE 0 1
288-
FO 2 3
289-
>>> a.set_labels({'M': 'Men', 'BE': 'Belgian'})
290-
nat\sex Men F
291-
Belgian 0 1
292-
FO 2 3
293-
294232
* allowed to pass a single axis or group as ``axes_to_reindex`` argument
295233
of the :py:obj:`LArray.reindex()` method (closes :issue:`712`).
296234

@@ -300,8 +238,6 @@ Miscellaneous improvements
300238
- light : to output axes labels only when they change instead of repeating them on each line
301239
- na_repr : to specify how to represent N/A (NaN) values
302240

303-
* added password argument to :py:obj:`Workbook.save()` to allow protecting Excel files with a password.
304-
305241
* substantially improved performance of creating, iterating, and doing a few other operations over larray objects.
306242
This solves a few pathological cases of slow operations, especially those involving many small-ish arrays but sadly
307243
the overall performance improvement is negligible over most of the real-world models using larray that we tested these

0 commit comments

Comments
 (0)