Re: [Numpy-discussion] Standard Deviation (std): Suggested change for ddof default value
On 2 April 2014 16:06, Sturla Molden sturla.mol...@gmail.com wrote: josef.p...@gmail.com wrote: pandas came later and thought ddof=1 is worth more than consistency. Pandas is a data analysis package. NumPy is a numerical array package. I think ddof=1 is justified for Pandas, for consistency with statistical software (SPSS et al.) For NumPy, there are many computational tasks where the Bessel correction is not wanted, so providing a uncorrected result is the correct thing to do. NumPy should be a low-level array library that does very little magic. All this discussion reminds me of the book Numerical Recipes: if the difference between N and N - 1 ever matters to you, then you are probably up to no good anyway -- e.g., trying to substantiate a questionable hypothesis with marginal data. For any reasonably sized data set, it is a correction in the second significant figure. ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Standard Deviation (std): Suggested change for ddof default value
On Fri, Apr 4, 2014 at 8:50 AM, Daπid davidmen...@gmail.com wrote: On 2 April 2014 16:06, Sturla Molden sturla.mol...@gmail.com wrote: josef.p...@gmail.com wrote: pandas came later and thought ddof=1 is worth more than consistency. Pandas is a data analysis package. NumPy is a numerical array package. I think ddof=1 is justified for Pandas, for consistency with statistical software (SPSS et al.) For NumPy, there are many computational tasks where the Bessel correction is not wanted, so providing a uncorrected result is the correct thing to do. NumPy should be a low-level array library that does very little magic. All this discussion reminds me of the book Numerical Recipes: if the difference between N and N − 1 ever matters to you, then you are probably up to no good anyway — e.g., trying to substantiate a questionable hypothesis with marginal data. For any reasonably sized data set, it is a correction in the second significant figure. I fully agree, but sometimes you don't have much choice. `big data` == `statistics with negative degrees of freedom` ? or maybe `machine learning` == `statistics with negative degrees of freedom` ? Josef ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy 1.8.1 release
I'ts time for me to come back to the discussion after a longer break. some personal history: I was looking for a 64bit mingw more than a year ago (unrelated to python) for Fortran development and tried out quite some mingw toolchain variants based on the mingw-w64 project. In a nutshell: the most appropriate and best documentated solution are the toolchains provided by the mingw builds project IMHO. The next step was the idea to use this toolchain for compiling python extensions (C and Fortran) and then to try out compiling numpy and scipy with OpenBLAS. Despite the fact, that a mingw-w64 based toolchain is rock solid today the following possible issues should be considered for Python development: (1) deploy problem: mingw runtime DLLs can not be found at runtime Solution: use flags for static linking or use a dedicated 'static' GCC toolchain for compiling and linking. Both solutions should work. (2) Win32 default stack alignment incompatibility: GCC uses 16 bytes since GCC4.6, MSVC uses 4 bytes Solution: use the -mincoming-stack-boundary=2 flag for compiling. Win64 X86_64 is not affected. This issue is the major cause for segment faults on 32bit systems. (3) Import library problem: numpy distutils does not play well with mingw-w64 Solution: create a Python import library with the mingw-w64 tools. Use a patched numpy distutils. A detailed description can be found here: http://article.gmane.org/gmane.comp.python.numeric.general/56749 . (4) linking against the correct msvcrXXX Version. Solution: create a 'specs' file (howto see http://www.mingw.org/wiki/HOWTO_Use_the_GCC_specs_file ) that includes necessary informations. (5) manifest resources Solution: extend the GCC toolchain with the Manifest resource files and ensure linkage with the help of the 'specs' file. (6) Blas Lapack for numpy scipy There is no silver bullet! A trade-off between licence acceptance, performance and stability remains to be found. OpenBLAS on Win32 seems to be quite stable. Some OpenBLAS issues on Win64 can be adressed with a single threaded version of that library. On my google drive: https://drive.google.com/folderview?id=0B4DmELLTwYmldUVpSjdpZlpNM1kusp=sharingI provide the necessary parts to try the procedures described at http://article.gmane.org/gmane.comp.python.numeric.general/56749 and http://article.gmane.org/gmane.comp.python.numeric.general/56767 Up to now I didn't find time to put a comprehensive description on the Web and to update all that stuff (MSVCR100 support for the toolchain still missing), so I add my incomplete, not yet published mingw-w64 FAQ at the end of my longish E-Mail for further discussions. Carl --- my personal mingw-w64 FAQ = what is mingw-w64 - mingw-w64 is a fork of the mingw32 project - http://sourceforge.net/apps/trac/mingw-w64/wiki/History why choose mingw-w64 over mingw --- - 32 AND 64bit support - large file support - winpthread pthreads implementation, MIT licenced. - cross compiler toolchains availabe for Linux official mingw-w64 releases --- source releases of the mingw-64 repository - http://sourceforge.net/projects/mingw-w64/files/mingw-w64/mingw-w64-release/ official mingw-w64 GCC toolchains - 'recommened' builds are available from the mingw-builds project http://mingw-w64.sourceforge.net/download.php#mingw-builds for example - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/4.8.2/threads-posix/seh/ - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/4.8.2/threads-posix/dwarf/ These are common combinations of exception and thread models. You can find other combinations as well. Exception handling affects C++ development. Don't ever link object code with different types of exception and/or thread handling! threads concerning the question 'where to find mingw-w64 builds' - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/7700 - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/8484 how to build a mingw-w64 based GCC toolchain on Windows --- mingw-builds is a set of scripts and patches for compiling the GCC toolchain under Windows with the help of msys2 POSIX enviroment - https://github.com/niXman/mingw-builds/tree/develop recent 'mingw-builds' GCC toolchains can be downloaded from the mingw-w64 sf.net (4) what is msys2 - msys2 is the successor of msys. Msys2 is necessary as enviroment for the mingw build process on Windows. - http://sourceforge.net/p/msys2/wiki/MSYS2%20installation/ where to get precompiled mingw-w64 compiled libraries - recent mingw-w64 based tools and library packages together with sources and patches are available from archlinux as well as from the msys2 maintainers.
[Numpy-discussion] Where to put versionadded
Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. *New Function* 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. *New Parameter* 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. Josef Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
On Fri, Apr 4, 2014 at 12:48 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. I find the opposite to be true. Because numpy needs maintain compatibility with a number python versions, I often check the python documentation to see in which version a function was added. Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
Hi, On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris charlesr.har...@gmail.com wrote: On Fri, Apr 4, 2014 at 12:48 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. I find the opposite to be true. Because numpy needs maintain compatibility with a number python versions, I often check the python documentation to see in which version a function was added. I agree; versionadded 2.1 is not likely interesting but versionadded 2.7 is very interesting. Cheers, Matthew ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy 1.8.1 release
I'ts time for me to come back to the discussion after a longer break. some personal history: I was looking for a 64bit mingw more than a year ago (unrelated to python) for Fortran development and tried out quite some mingw toolchain variants based on the mingw-w64 project. In a nutshell: the most appropriate and best documentated solution are the toolchains provided by the mingw builds project IMHO. The next step was the idea to use this toolchain for compiling python extensions (C and Fortran) and then to try out compiling numpy and scipy with OpenBLAS. Despite the fact, that a mingw-w64 based toolchain is rock solid today the following possible issues should be considered for Python development: (1) deploy problem: mingw runtime DLLs can not be found at runtime Solution: use flags for static linking or use a dedicated 'static' GCC toolchain for compiling and linking. Both solutions should work. (2) Win32 default stack alignment incompatibility: GCC uses 16 bytes since GCC4.6, MSVC uses 4 bytes Solution: use the -mincoming-stack-boundary=2 flag for compiling. Win64 X86_64 is not affected. This issue is the major cause for segment faults on 32bit systems. (3) Import library problem: numpy distutils does not play well with mingw-w64 Solution: create a Python import library with the mingw-w64 tools. Use a patched numpy distutils. A detailed description can be found here: http://article.gmane.org/gmane.comp.python.numeric.general/56749 . (4) linking against the correct msvcrXXX Version. Solution: create a 'specs' file (howto see http://www.mingw.org/wiki/HOWTO_Use_the_GCC_specs_file ) that includes necessary informations. (5) manifest resources Solution: extend the GCC toolchain with the Manifest resource files and ensure linkage with the help of the 'specs' file. (6) Blas Lapack for numpy scipy There is no silver bullet! A trade-off between licence acceptance, performance and stability remains to be found. OpenBLAS on Win32 seems to be quite stable. Some OpenBLAS issues on Win64 can be adressed with a single threaded version of that library. On my google drive: https://drive.google.com/folderview?id=0B4DmELLTwYmldUVpSjdpZlpNM1kusp=sharingI provide the necessary parts to try the procedures described at http://article.gmane.org/gmane.comp.python.numeric.general/56749 and http://article.gmane.org/gmane.comp.python.numeric.general/56767 Up to now I didn't find time to put a comprehensive description on the Web and to update all that stuff (MSVCR100 support for the toolchain still missing), so I add my incomplete, not yet published mingw-w64 FAQ at the end of my longish E-Mail for further discussions. Carl --- my personal mingw-w64 FAQ = what is mingw-w64 - mingw-w64 is a fork of the mingw32 project - http://sourceforge.net/apps/trac/mingw-w64/wiki/History why choose mingw-w64 over mingw --- - 32 AND 64bit support - large file support - winpthread pthreads implementation, MIT licenced. - cross compiler toolchains availabe for Linux official mingw-w64 releases --- source releases of the mingw-64 repository - http://sourceforge.net/projects/mingw-w64/files/mingw-w64/mingw-w64-release/ official mingw-w64 GCC toolchains - 'recommened' builds are available from the mingw-builds project http://mingw-w64.sourceforge.net/download.php#mingw-builds for example - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/4.8.2/threads-posix/seh/ - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/4.8.2/threads-posix/dwarf/ These are common combinations of exception and thread models. You can find other combinations as well. Exception handling affects C++ development. Don't ever link object code with different types of exception and/or thread handling! threads concerning the question 'where to find mingw-w64 builds' - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/7700 - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/8484 how to build a mingw-w64 based GCC toolchain on Windows --- mingw-builds is a set of scripts and patches for compiling the GCC toolchain under Windows with the help of msys2 POSIX enviroment - https://github.com/niXman/mingw-builds/tree/develop recent 'mingw-builds' GCC toolchains can be downloaded from the mingw-w64 sf.net (4) what is msys2 - msys2 is the successor of msys. Msys2 is necessary as enviroment for the mingw build process on Windows. - http://sourceforge.net/p/msys2/wiki/MSYS2%20installation/ where to get precompiled mingw-w64 compiled libraries - recent mingw-w64 based tools and library packages together with sources and patches are available from archlinux as well as from the msys2 maintainers.
Re: [Numpy-discussion] Where to put versionadded
On Fri, Apr 4, 2014 at 3:07 PM, Matthew Brett matthew.br...@gmail.com wrote: Hi, On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris charlesr.har...@gmail.com wrote: On Fri, Apr 4, 2014 at 12:48 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. I find the opposite to be true. Because numpy needs maintain compatibility with a number python versions, I often check the python documentation to see in which version a function was added. I agree; versionadded 2.1 is not likely interesting but versionadded 2.7 is very interesting. That's true, but it's a mess for maintainers because we support now 5 python versions. numpy doesn't have a long history of versionadded yet, I didn't find anything for 1.3 in a quick search. statsmodels has now numpy 1.6 as minimum requirement and I'm interested in the features that become available with a minimum version increase. Once I know what I'm allowed to use, I only care about the real documentation, How does einsum really work?. But as a numpy user, I was never really interested in the information that arraysetops where enhanced and renamed in numpy 1.x (x=?4), or that take was added in 0.y, ... Even the first part of polynomial is already in 1.4 (It might just make me feel old if I remember when it was changed.) versionadded is not very distracting in the html rendering, so I'm just +0.1 on Notes. Josef Cheers, Matthew ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] ANN: NumPy 1.8.1 release
Hi, On Fri, Apr 4, 2014 at 8:19 AM, Carl Kleffner cmkleff...@gmail.com wrote: I'ts time for me to come back to the discussion after a longer break. some personal history: I was looking for a 64bit mingw more than a year ago (unrelated to python) for Fortran development and tried out quite some mingw toolchain variants based on the mingw-w64 project. In a nutshell: the most appropriate and best documentated solution are the toolchains provided by the mingw builds project IMHO. The next step was the idea to use this toolchain for compiling python extensions (C and Fortran) and then to try out compiling numpy and scipy with OpenBLAS. Despite the fact, that a mingw-w64 based toolchain is rock solid today the following possible issues should be considered for Python development: (1) deploy problem: mingw runtime DLLs can not be found at runtime Solution: use flags for static linking or use a dedicated 'static' GCC toolchain for compiling and linking. Both solutions should work. (2) Win32 default stack alignment incompatibility: GCC uses 16 bytes since GCC4.6, MSVC uses 4 bytes Solution: use the -mincoming-stack-boundary=2 flag for compiling. Win64 X86_64 is not affected. This issue is the major cause for segment faults on 32bit systems. (3) Import library problem: numpy distutils does not play well with mingw-w64 Solution: create a Python import library with the mingw-w64 tools. Use a patched numpy distutils. A detailed description can be found here: http://article.gmane.org/gmane.comp.python.numeric.general/56749 . (4) linking against the correct msvcrXXX Version. Solution: create a 'specs' file (howto see http://www.mingw.org/wiki/HOWTO_Use_the_GCC_specs_file ) that includes necessary informations. (5) manifest resources Solution: extend the GCC toolchain with the Manifest resource files and ensure linkage with the help of the 'specs' file. (6) Blas Lapack for numpy scipy There is no silver bullet! A trade-off between licence acceptance, performance and stability remains to be found. OpenBLAS on Win32 seems to be quite stable. Some OpenBLAS issues on Win64 can be adressed with a single threaded version of that library. On my google drive: https://drive.google.com/folderview?id=0B4DmELLTwYmldUVpSjdpZlpNM1kusp=sharing I provide the necessary parts to try the procedures described at http://article.gmane.org/gmane.comp.python.numeric.general/56749 and http://article.gmane.org/gmane.comp.python.numeric.general/56767 Up to now I didn't find time to put a comprehensive description on the Web and to update all that stuff (MSVCR100 support for the toolchain still missing), so I add my incomplete, not yet published mingw-w64 FAQ at the end of my longish E-Mail for further discussions. Carl --- my personal mingw-w64 FAQ = what is mingw-w64 - mingw-w64 is a fork of the mingw32 project - http://sourceforge.net/apps/trac/mingw-w64/wiki/History why choose mingw-w64 over mingw --- - 32 AND 64bit support - large file support - winpthread pthreads implementation, MIT licenced. - cross compiler toolchains availabe for Linux official mingw-w64 releases --- source releases of the mingw-64 repository - http://sourceforge.net/projects/mingw-w64/files/mingw-w64/mingw-w64-release/ official mingw-w64 GCC toolchains - 'recommened' builds are available from the mingw-builds project http://mingw-w64.sourceforge.net/download.php#mingw-builds for example - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/4.8.2/threads-posix/seh/ - http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/4.8.2/threads-posix/dwarf/ These are common combinations of exception and thread models. You can find other combinations as well. Exception handling affects C++ development. Don't ever link object code with different types of exception and/or thread handling! threads concerning the question 'where to find mingw-w64 builds' - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/7700 - http://article.gmane.org/gmane.comp.gnu.mingw.w64.general/8484 how to build a mingw-w64 based GCC toolchain on Windows --- mingw-builds is a set of scripts and patches for compiling the GCC toolchain under Windows with the help of msys2 POSIX enviroment - https://github.com/niXman/mingw-builds/tree/develop recent 'mingw-builds' GCC toolchains can be downloaded from the mingw-w64 sf.net (4) what is msys2 - msys2 is the successor of msys. Msys2 is necessary as enviroment for the mingw build process on Windows. - http://sourceforge.net/p/msys2/wiki/MSYS2%20installation/ where to get precompiled mingw-w64 compiled libraries
Re: [Numpy-discussion] Where to put versionadded
On Fri, Apr 4, 2014 at 3:33 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 3:07 PM, Matthew Brett matthew.br...@gmail.com wrote: Hi, On Fri, Apr 4, 2014 at 11:54 AM, Charles R Harris charlesr.har...@gmail.com wrote: On Fri, Apr 4, 2014 at 12:48 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. since I like history: AFAICS: arraysetops was changed in 1.4 histogram was added in 0.4 corrcoef was added in 0.9.2 numpy 0.9.2 is 8 years old python 2.1 has soon it's 13th anniversary Josef I find the opposite to be true. Because numpy needs maintain compatibility with a number python versions, I often check the python documentation to see in which version a function was added. I agree; versionadded 2.1 is not likely interesting but versionadded 2.7 is very interesting. That's true, but it's a mess for maintainers because we support now 5 python versions. numpy doesn't have a long history of versionadded yet, I didn't find anything for 1.3 in a quick search. statsmodels has now numpy 1.6 as minimum requirement and I'm interested in the features that become available with a minimum version increase. Once I know what I'm allowed to use, I only care about the real documentation, How does einsum really work?. But as a numpy user, I was never really interested in the information that arraysetops where enhanced and renamed in numpy 1.x (x=?4), or that take was added in 0.y, ... Even the first part of polynomial is already in 1.4 (It might just make me feel old if I remember when it was changed.) versionadded is not very distracting in the html rendering, so I'm just +0.1 on Notes. Josef Cheers, Matthew ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Where to put versionadded
On Apr 4, 2014 8:54 PM, Charles R Harris charlesr.har...@gmail.com wrote: On Fri, Apr 4, 2014 at 12:48 PM, josef.p...@gmail.com wrote: On Fri, Apr 4, 2014 at 2:12 PM, Charles R Harris charlesr.har...@gmail.com wrote: Hi All, Currently there are several placements of the '.. versionadded::' directive and I'd like to settle on a proper style for consistency. There are two occasions on which it is used, first, when a new function or class is added and second, when a new keyword is added to an existing function or method. The options are as follows. New Function 1) Originally, the directive was added in the notes section. Notes - .. versionadded:: 1.5.0 2) Alternatively, it is placed after the extended summary. blah, blah ..versionadded:: 1.5.0 Between these two, I vote for 2) because the version is easily found when reading the documentation either in a terminal or rendered into HTML. New Parameter 1) It is placed before the parameter description newoption : int, optional .. versionadded:: 1.5.0 blah. 2) It is placed after the parameter description. newoption : int, optional blah. .. versionadded:: 1.5.0 Both of these render correctly, but the first is more compact while the second puts the version after the description where it doesn't interrupt the reading. I'm tending towards 1) on account of its compactness. Thoughts? I'm in favor of putting them only in the Notes section. Most of the time they are not crucial information and it's distracting. I usually only look for them when I'm working explicitly across several numpy versions. like in python: versionadded 2.1 is only interesting for historians. I find the opposite to be true. Because numpy needs maintain compatibility with a number python versions, I often check the python documentation to see in which version a function was added. Chuck ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion My user perspective: I am developing a tool whose main use is to run on my computer, so I prefer to run the newest and sweetest version of the libraries, and I this report the minimum versions. But it would be good if I could grep my code, see what numpy functions are being used and infer a probable minimum version required. If other libraries follow similar conventions, and one does not do metaprogramming or other fancy things, it is relatively easy to get automatically. ___ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
