Picon
Picon
Favicon

Changes to trunk/scipy/optimize

Hi all,

I noticed the following changeset coming through. Do you think docstrings are the right place for advertising external packages?  If not, should they be moved to the module docstring, or removed entirely?

Regards
Stéfan

---------- Forwarded message ----------
Author: dmitrey.kroshko
Date: 2010-02-09 02:41:34 -0600 (Tue, 09 Feb 2010)
New Revision: 6221

Modified:
  trunk/scipy/optimize/anneal.py
  trunk/scipy/optimize/cobyla.py
  trunk/scipy/optimize/lbfgsb.py
  trunk/scipy/optimize/minpack.py
  trunk/scipy/optimize/nnls.py
  trunk/scipy/optimize/optimize.py
  trunk/scipy/optimize/slsqp.py
  trunk/scipy/optimize/tnc.py
Log:
scikits.openopt replaced by mere openopt


Modified: trunk/scipy/optimize/anneal.py
===================================================================
--- trunk/scipy/optimize/anneal.py      2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/anneal.py      2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -217,6 +217,8 <at> <at>

      fixed_point -- scalar fixed-point finder

+      OpenOpt -- Python package with more optimization solvers
+
    """
    x0 = asarray(x0)
    lower = asarray(lower)

Modified: trunk/scipy/optimize/cobyla.py
===================================================================
--- trunk/scipy/optimize/cobyla.py      2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/cobyla.py      2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -46,8 +46,6 <at> <at>

    See also:

-        scikits.openopt, which offers a unified syntax to call this and other solvers
-
        fmin, fmin_powell, fmin_cg,
              fmin_bfgs, fmin_ncg -- multivariate local optimizers
        leastsq -- nonlinear least squares minimizer
<at> <at> -65,6 +63,9 <at> <at>

        fixed_point -- scalar fixed-point finder

+        OpenOpt -- a tool which offers a unified syntax to call this and
+         other solvers with possibility of automatic differentiation
+
    """
    err = "cons must be a sequence of callable functions or a single"\
              " callable function."

Modified: trunk/scipy/optimize/lbfgsb.py
===================================================================
--- trunk/scipy/optimize/lbfgsb.py      2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/lbfgsb.py      2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -119,8 +119,6 <at> <at>
       ACM Transactions on Mathematical Software, Vol 23, Num. 4, pp. 550 - 560.

    See also:
-        scikits.openopt, which offers a unified syntax to call this and other solvers
-
        fmin, fmin_powell, fmin_cg,
               fmin_bfgs, fmin_ncg -- multivariate local optimizers
        leastsq -- nonlinear least squares minimizer
<at> <at> -138,6 +136,9 <at> <at>

        fixed_point -- scalar fixed-point finder

+        OpenOpt -- a tool which offers a unified syntax to call this and
+         other solvers with possibility of automatic differentiation
+
    """
    n = len(x0)


Modified: trunk/scipy/optimize/minpack.py
===================================================================
--- trunk/scipy/optimize/minpack.py     2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/minpack.py     2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -102,8 +102,6 <at> <at>

    See Also
    --------
-    scikits.openopt : offers a unified syntax to call this and other solvers
-
    fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg : multivariate local optimizers

    leastsq : nonlinear least squares minimizer
<at> <at> -118,6 +116,9 <at> <at>

    fixed_point : scalar and vector fixed-point finder

+    OpenOpt : a tool which offers a unified syntax to call this and
+     other solvers with possibility of automatic differentiation
+
    """
    if not warning :
        msg = "The warning keyword is deprecated. Use the warnings module."
<at> <at> -263,7 +264,6 <at> <at>

    See Also
    --------
-    scikits.openopt: offers a unified syntax to call this and other solvers
    fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg: multivariate local optimizers
    fmin_l_bfgs_b, fmin_tnc, fmin_cobyla: constrained multivariate optimizers
    anneal, brute: global optimizers
<at> <at> -272,6 +272,9 <at> <at>
    brentq, brenth, ridder, bisect, newton: one-dimensional root-finding
    fixed_point: scalar and vector fixed-point finder
    curve_fit: find parameters for a curve-fitting problem.
+    OpenOpt : a tool which offers a unified syntax to call this and
+     other solvers with possibility of automatic differentiation
+
    """
    if not warning :
        msg = "The warning keyword is deprecated. Use the warnings module."

Modified: trunk/scipy/optimize/nnls.py
===================================================================
--- trunk/scipy/optimize/nnls.py        2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/nnls.py        2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -16,6 +16,8 <at> <at>

    wrapper around NNLS.F code below nnls/ directory

+    Check OpenOpt for more LLSP solvers
+
    """

    A,b = map(asarray_chkfinite, (A,b))

Modified: trunk/scipy/optimize/optimize.py
===================================================================
--- trunk/scipy/optimize/optimize.py    2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/optimize.py    2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -156,7 +156,8 <at> <at>

        Uses a Nelder-Mead simplex algorithm to find the minimum of
        function of one or more variables.
-
+        Check OpenOpt - a tool which offers a unified syntax to call
+        this and other solvers with possibility of automatic differentiation.
    """
    fcalls, func = wrap_function(func, args)
    x0 = asfarray(x0).flatten()
<at> <at> -694,8 +695,8 <at> <at>

    *See Also*:

-      scikits.openopt : SciKit which offers a unified syntax to call
-                        this and other solvers.
+      OpenOpt : a tool which offers a unified syntax to call
+                this and other solvers with possibility of automatic differentiation.

    """
    x0 = asarray(x0).squeeze()
<at> <at> -862,7 +863,8 <at> <at>
        using the nonlinear conjugate gradient algorithm of Polak and
        Ribiere See Wright, and Nocedal 'Numerical Optimization',
        1999, pg. 120-122.
-
+        Check OpenOpt - a tool which offers a unified syntax to call
+        this and other solvers with possibility of automatic differentiation.
    """
    x0 = asarray(x0).flatten()
    if maxiter is None:
<at> <at> -1018,8 +1020,7 <at> <at>
            If True, return a list of results at each iteration.

    :Notes:
-      1. scikits.openopt offers a unified syntax to call this and other solvers.
-      2. Only one of `fhess_p` or `fhess` need to be given.  If `fhess`
+      1. Only one of `fhess_p` or `fhess` need to be given.  If `fhess`
      is provided, then `fhess_p` will be ignored.  If neither `fhess`
      nor `fhess_p` is provided, then the hessian product will be
      approximated using finite differences on `fprime`. `fhess_p`
<at> <at> -1027,6 +1028,8 <at> <at>
      given, finite-differences on `fprime` are used to compute
      it. See Wright, and Nocedal 'Numerical Optimization', 1999,
      pg. 140.
+      2. Check OpenOpt - a tool which offers a unified syntax to call
+      this and other solvers with possibility of automatic differentiation.

    """
    x0 = asarray(x0).flatten()
<at> <at> -1179,8 +1182,9 <at> <at>
        Finds a local minimizer of the scalar function `func` in the
        interval x1 < xopt < x2 using Brent's method.  (See `brent`
        for auto-bracketing).
+        Check OpenOpt - a tool which offers a unified syntax to call
+        this and other solvers with possibility of automatic differentiation.

-
    """
    # Test bounds are of correct form

<at> <at> -1722,7 +1726,8 <at> <at>

        Uses a modification of Powell's method to find the minimum of
        a function of N variables.
-
+        Check OpenOpt - a tool which offers a unified syntax to call
+        this and other solvers with possibility of automatic differentiation.
    """
    # we need to use a mutable object here that we can update in the
    # wrapper function

Modified: trunk/scipy/optimize/slsqp.py
===================================================================
--- trunk/scipy/optimize/slsqp.py       2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/slsqp.py       2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -146,6 +146,11 <at> <at>

    for examples see :ref:`in the tutorial <tutorial-sqlsp>`

+    See also
+    --------
+    OpenOpt - a tool which offers a unified syntax to call this
+    and other solvers with possibility of automatic differentiation.
+
    """

    exit_modes = { -1 : "Gradient evaluation required (g & a)",

Modified: trunk/scipy/optimize/tnc.py
===================================================================
--- trunk/scipy/optimize/tnc.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/tnc.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -164,8 +164,6 <at> <at>
            Return code as defined in the RCSTRINGS dict.

    :SeeAlso:
-      - scikits.openopt, which offers a unified syntax to call this and other solvers
-
      - fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg :
         multivariate local optimizers

<at> <at> -184,6 +182,9 <at> <at>

      - fixed_point : scalar fixed-point finder

+      - OpenOpt : a tool which offers a unified syntax to call this and
+         other solvers with possibility of automatic differentiation.
+
 """
    x0 = asarray(x0, dtype=float).tolist()
    n = len(x0)

_______________________________________________
Scipy-svn mailing list
Scipy-svn <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-svn

_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev
Jarrod Millman | 9 Feb 11:14
Picon
Favicon

Re: Changes to trunk/scipy/optimize

2010/2/9 Stéfan van der Walt <stefan <at> sun.ac.za>:

> I noticed the following changeset coming through. Do you think docstrings > are the right place for advertising external packages?  If not, should they > be moved to the module docstring, or removed entirely?
My vote would be to remove them. I think the 'See Also' section should only point to numpy/scipy/scikits code. We can point to external packages on the website. -- -- Jarrod Millman Helen Wills Neuroscience Institute 10 Giannini Hall, UC Berkeley http://cirl.berkeley.edu/
Ralf Gommers | 9 Feb 11:15
Gravatar

Re: Changes to trunk/scipy/optimize



2010/2/9 Stéfan van der Walt <stefan <at> sun.ac.za>
Hi all,

I noticed the following changeset coming through. Do you think docstrings are the right place for advertising external packages?  If not, should they be moved to the module docstring, or removed entirely?


First, thanks to Dimitry for asking on this list before making the change. That said, docstrings do not seem like the right place for this, module docstring and/or tutorial seem like more appropriate places.

I do not see any reason to remove mention of OpenOpt completely, many external packages are mentioned in our docs and OpenOpt is clearly relevant. That it moved from scikits to some other location does not matter.

Cheers,
Ralf
_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev
Dmitrey | 9 Feb 11:19
Favicon

Re: Changes to trunk/scipy/optimize

I had asked it 2 days ago before today's commit
http://permalink.gmane.org/gmane.comp.python.scientific.devel/12740
why couldn't you answer earlier?
as for mention scikits.openopt, it was allowed that time I had asked for it (about 2 years ago).

In any way, of course, you can undo the changes / remove it completely / do anything else what you want.
D.

--- Исходное сообщение ---
От кого: St?fan van der Walt <stefan <at> sun.ac.za>
Кому: SciPy Developers List <scipy-dev <at> scipy.org>
Дата: 9 февраля, 11:31:12
Тема: [SciPy-dev] Changes to trunk/scipy/optimize

Hi all,

I noticed the following changeset coming through. Do you think docstrings
are the right place for advertising external packages? If not, should they
be moved to the module docstring, or removed entirely?

Regards
Stйfan

---------- Forwarded message ----------
Author: dmitrey.kroshko
Date: 2010-02-09 02:41:34 -0600 (Tue, 09 Feb 2010)
New Revision: 6221

Modified:
trunk/scipy/optimize/anneal.py
trunk/scipy/optimize/cobyla.py
trunk/scipy/optimize/lbfgsb.py
trunk/scipy/optimize/minpack.py
trunk/scipy/optimize/nnls.py
trunk/scipy/optimize/optimize.py
trunk/scipy/optimize/slsqp.py
trunk/scipy/optimize/tnc.py
Log:
scikits.openopt replaced by mere openopt

Modified: trunk/scipy/optimize/anneal.py
===================================================================
--- trunk/scipy/optimize/anneal.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/anneal.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -217,6 +217,8 <at> <at>

fixed_point -- scalar fixed-point finder

+ OpenOpt -- Python package with more optimization solvers
+
"""
x0 = asarray(x0)
lower = asarray(lower)

Modified: trunk/scipy/optimize/cobyla.py
===================================================================
--- trunk/scipy/optimize/cobyla.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/cobyla.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -46,8 +46,6 <at> <at>

See also:

- scikits.openopt, which offers a unified syntax to call this and
other solvers
-
fmin, fmin_powell, fmin_cg,
fmin_bfgs, fmin_ncg -- multivariate local optimizers
leastsq -- nonlinear least squares minimizer
<at> <at> -65,6 +63,9 <at> <at>

fixed_point -- scalar fixed-point finder

+ OpenOpt -- a tool which offers a unified syntax to call this and
+ other solvers with possibility of automatic differentiation
+
"""
err = "cons must be a sequence of callable functions or a single"\
" callable function."

Modified: trunk/scipy/optimize/lbfgsb.py
===================================================================
--- trunk/scipy/optimize/lbfgsb.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/lbfgsb.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -119,8 +119,6 <at> <at>
ACM Transactions on Mathematical Software, Vol 23, Num. 4, pp. 550 -
560.

See also:
- scikits.openopt, which offers a unified syntax to call this and
other solvers
-
fmin, fmin_powell, fmin_cg,
fmin_bfgs, fmin_ncg -- multivariate local optimizers
leastsq -- nonlinear least squares minimizer
<at> <at> -138,6 +136,9 <at> <at>

fixed_point -- scalar fixed-point finder

+ OpenOpt -- a tool which offers a unified syntax to call this and
+ other solvers with possibility of automatic differentiation
+
"""
n = len(x0)

Modified: trunk/scipy/optimize/minpack.py
===================================================================
--- trunk/scipy/optimize/minpack.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/minpack.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -102,8 +102,6 <at> <at>

See Also
--------
- scikits.openopt : offers a unified syntax to call this and other
solvers
-
fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg : multivariate local
optimizers

leastsq : nonlinear least squares minimizer
<at> <at> -118,6 +116,9 <at> <at>

fixed_point : scalar and vector fixed-point finder

+ OpenOpt : a tool which offers a unified syntax to call this and
+ other solvers with possibility of automatic differentiation
+
"""
if not warning :
msg = "The warning keyword is deprecated. Use the warnings module."
<at> <at> -263,7 +264,6 <at> <at>

See Also
--------
- scikits.openopt: offers a unified syntax to call this and other solvers
fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg: multivariate local
optimizers
fmin_l_bfgs_b, fmin_tnc, fmin_cobyla: constrained multivariate
optimizers
anneal, brute: global optimizers
<at> <at> -272,6 +272,9 <at> <at>
brentq, brenth, ridder, bisect, newton: one-dimensional root-finding
fixed_point: scalar and vector fixed-point finder
curve_fit: find parameters for a curve-fitting problem.
+ OpenOpt : a tool which offers a unified syntax to call this and
+ other solvers with possibility of automatic differentiation
+
"""
if not warning :
msg = "The warning keyword is deprecated. Use the warnings module."

Modified: trunk/scipy/optimize/nnls.py
===================================================================
--- trunk/scipy/optimize/nnls.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/nnls.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -16,6 +16,8 <at> <at>

wrapper around NNLS.F code below nnls/ directory

+ Check OpenOpt for more LLSP solvers
+
"""

A,b = map(asarray_chkfinite, (A,b))

Modified: trunk/scipy/optimize/optimize.py
===================================================================
--- trunk/scipy/optimize/optimize.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/optimize.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -156,7 +156,8 <at> <at>

Uses a Nelder-Mead simplex algorithm to find the minimum of
function of one or more variables.
-
+ Check OpenOpt - a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic
differentiation.
"""
fcalls, func = wrap_function(func, args)
x0 = asfarray(x0).flatten()
<at> <at> -694,8 +695,8 <at> <at>

*See Also*:

- scikits.openopt : SciKit which offers a unified syntax to call
- this and other solvers.
+ OpenOpt : a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic
differentiation.

"""
x0 = asarray(x0).squeeze()
<at> <at> -862,7 +863,8 <at> <at>
using the nonlinear conjugate gradient algorithm of Polak and
Ribiere See Wright, and Nocedal 'Numerical Optimization',
1999, pg. 120-122.
-
+ Check OpenOpt - a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic
differentiation.
"""
x0 = asarray(x0).flatten()
if maxiter is None:
<at> <at> -1018,8 +1020,7 <at> <at>
If True, return a list of results at each iteration.

:Notes:
- 1. scikits.openopt offers a unified syntax to call this and other
solvers.
- 2. Only one of `fhess_p` or `fhess` need to be given. If `fhess`
+ 1. Only one of `fhess_p` or `fhess` need to be given. If `fhess`
is provided, then `fhess_p` will be ignored. If neither `fhess`
nor `fhess_p` is provided, then the hessian product will be
approximated using finite differences on `fprime`. `fhess_p`
<at> <at> -1027,6 +1028,8 <at> <at>
given, finite-differences on `fprime` are used to compute
it. See Wright, and Nocedal 'Numerical Optimization', 1999,
pg. 140.
+ 2. Check OpenOpt - a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic differentiation.

"""
x0 = asarray(x0).flatten()
<at> <at> -1179,8 +1182,9 <at> <at>
Finds a local minimizer of the scalar function `func` in the
interval x1 < xopt < x2 using Brent's method. (See `brent`
for auto-bracketing).
+ Check OpenOpt - a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic
differentiation.

-
"""
# Test bounds are of correct form

<at> <at> -1722,7 +1726,8 <at> <at>

Uses a modification of Powell's method to find the minimum of
a function of N variables.
-
+ Check OpenOpt - a tool which offers a unified syntax to call
+ this and other solvers with possibility of automatic
differentiation.
"""
# we need to use a mutable object here that we can update in the
# wrapper function

Modified: trunk/scipy/optimize/slsqp.py
===================================================================
--- trunk/scipy/optimize/slsqp.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/slsqp.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -146,6 +146,11 <at> <at>

for examples see :ref:`in the tutorial <tutorial-sqlsp>`

+ See also
+ --------
+ OpenOpt - a tool which offers a unified syntax to call this
+ and other solvers with possibility of automatic differentiation.
+
"""

exit_modes = { -1 : "Gradient evaluation required (g & a)",

Modified: trunk/scipy/optimize/tnc.py
===================================================================
--- trunk/scipy/optimize/tnc.py 2010-02-08 15:18:27 UTC (rev 6220)
+++ trunk/scipy/optimize/tnc.py 2010-02-09 08:41:34 UTC (rev 6221)
<at> <at> -164,8 +164,6 <at> <at>
Return code as defined in the RCSTRINGS dict.

:SeeAlso:
- - scikits.openopt, which offers a unified syntax to call this and
other solvers
-
- fmin, fmin_powell, fmin_cg, fmin_bfgs, fmin_ncg :
multivariate local optimizers

<at> <at> -184,6 +182,9 <at> <at>

- fixed_point : scalar fixed-point finder

+ - OpenOpt : a tool which offers a unified syntax to call this and
+ other solvers with possibility of automatic differentiation.
+
"""
x0 = asarray(x0, dtype=float).tolist()
n = len(x0)

_______________________________________________
Scipy-svn mailing list
Scipy-svn <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-svn

_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev

_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev
Jarrod Millman | 9 Feb 12:05
Picon
Favicon

Re: Changes to trunk/scipy/optimize

2010/2/9 Dmitrey <tmp50 <at> ukr.net>:
> I had asked it 2 days ago before today's commit
> http://permalink.gmane.org/gmane.comp.python.scientific.devel/12740
> why couldn't you answer earlier?

Thanks for raising the issue to the list.  Sorry, I missed your
original email and I am sure Stefan must have missed it as well.
Please don't take this discussion as in any way an attempt to
discourage people from using OpenOpt or suggesting you did anything
wrong.  I know that OpenOpt is extremely useful and you've done a
great job developing it.

> as for mention scikits.openopt, it was allowed that time I had asked for it
> (about 2 years ago).

Just to be clear, I think Stefan was asking a more general question
that arose due to this specific instance.  The OpenOpt situation is a
bit unique since it was originally a Google SoC project for SciPy, but
after funding ran out became a successful stand-alone project of its
own.

Now the question is where is the best place for us to reference
external, but relevant and useful Python projects.  My personal
feeling is that it shouldn't be in the 'see also' section of our
docstrings, but we don't have any official policy on that yet.  So we
need to have a general discussion about what the general policy should
be.

Personally I would say that the primary place to point to external
packages is in the topical software section of website.  For instance,
OpenOpt is pointed to here:
http://www.scipy.org/Topical_Software#head-d21a11d2d173826993e03eb937fac7e6347e6d5f
I also think it would be fine to occasionally use external packages in
the tutorials if deemed useful.  But, in general, I would expect
external packages to have their own tutorials.  I would prefer to
limit the docstrings to just our core projects (numpy and scipy for
certain and perhaps the scikits as well).  If we don't limit the
docstrings in this way, I can see us either 1) getting in the
situation where it isn't clear how much more we should add to the
docstrings for the sake of completeness or 2) inadvertently getting
into political battles by appearing to favor certain external projects
while not mentioning others.

I am very interested in hearing what everyone else thinks about this
issue.  However, I think it would be most useful to discuss this in
general, rather than with a focus on openopt.  So if we decide not to
reference external packages in scipy and it turns out that we
reference several others in addition to openopt, then we should apply
the same standard to all the cases.

Best,
Jarrod
Martin Lüthi | 9 Feb 13:22
Picon

Re: Changes to trunk/scipy/optimize

Hi

At Tue, 9 Feb 2010 03:05:41 -0800,
Jarrod Millman wrote:

> Now the question is where is the best place for us to reference > external, but relevant and useful Python projects. My personal > feeling is that it shouldn't be in the 'see also' section of our > docstrings, but we don't have any official policy on that yet. So we > need to have a general discussion about what the general policy should > be.
I completely understand your reasoning. However, I would still find it useful if there were a docstring section named "similar packages", mentioning either of a) relevant packages that are closely painfully integrated with scipy and are generally regarded as useful b) a link to the relevant URL of the topical software guide. Option (a) might lead to some "political" problems, which I cannot imagine being difficult. Option (b) would be useful in any case. While checking out code the Topical Software Pages or the Scipy Wiki are not the immediately obvious places to look for more relevant information. Best, Martin
josef.pktd | 9 Feb 15:31
Picon

Re: Changes to trunk/scipy/optimize

2010/2/9 Martin Lüthi <luethi <at> vaw.baug.ethz.ch>:
> Hi
>
> At Tue, 9 Feb 2010 03:05:41 -0800,
> Jarrod Millman wrote:
>> Now the question is where is the best place for us to reference
>> external, but relevant and useful Python projects.  My personal
>> feeling is that it shouldn't be in the 'see also' section of our
>> docstrings, but we don't have any official policy on that yet.  So we
>> need to have a general discussion about what the general policy should
>> be.
>
> I completely understand your reasoning. However, I would still find it useful
> if there were a docstring section named "similar packages", mentioning either of
>
> a) relevant packages that are closely painfully integrated with scipy and are
>   generally regarded as useful
>
> b) a link to the relevant URL of the topical software guide.
>
> Option (a) might lead to some "political" problems, which I cannot imagine
> being difficult. Option (b) would be useful in any case. While checking out
> code the Topical Software Pages or the Scipy Wiki are not the immediately
> obvious places to look for more relevant information.

I think this would be useful on the module or scipy subpackage level
but not for the docstrings for individual functions or classes. In my
opinion, the docstring of function should provide only closely related
functions and classes for quick lookup. Extra information should go
into a different section, for example in the statsmodels docs, I
included a page with related packages.

For the specific case of scipy.optimize, I think also some of the
internal See Also can be removed, since many of the docstrings are
almost a table of content of scipy.optimize, which also can be
directly seen on the subpackage level. If I remember correctly, in
some parts of scipy some weeding of umbrella SeeAlso has already
occured.

On Wiki versus documentation pages, I think it would be helpful to
introduce additional descriptive sections on the scipy.subpackage
level, which could include specific Topical Software.

I'm using the numpy/scipy docs mainly through htmlhelp (.chm) where
the tree view makes browsing very fast (similar to matlab help), maybe
the html pages need more links than this.

Josef

>
> Best, Martin
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev <at> scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
Robert Kern | 9 Feb 16:30
Picon
Gravatar

Re: Changes to trunk/scipy/optimize

On Tue, Feb 9, 2010 at 08:31,  <josef.pktd <at> gmail.com> wrote:
> 2010/2/9 Martin Lüthi <luethi <at> vaw.baug.ethz.ch>:
>> Hi
>>
>> At Tue, 9 Feb 2010 03:05:41 -0800,
>> Jarrod Millman wrote:
>>> Now the question is where is the best place for us to reference
>>> external, but relevant and useful Python projects.  My personal
>>> feeling is that it shouldn't be in the 'see also' section of our
>>> docstrings, but we don't have any official policy on that yet.  So we
>>> need to have a general discussion about what the general policy should
>>> be.
>>
>> I completely understand your reasoning. However, I would still find it useful
>> if there were a docstring section named "similar packages", mentioning either of
>>
>> a) relevant packages that are closely painfully integrated with scipy and are
>>   generally regarded as useful
>>
>> b) a link to the relevant URL of the topical software guide.
>>
>> Option (a) might lead to some "political" problems, which I cannot imagine
>> being difficult. Option (b) would be useful in any case. While checking out
>> code the Topical Software Pages or the Scipy Wiki are not the immediately
>> obvious places to look for more relevant information.
>
> I think this would be useful on the module or scipy subpackage level
> but not for the docstrings for individual functions or classes. In my
> opinion, the docstring of function should provide only closely related
> functions and classes for quick lookup. Extra information should go
> into a different section, for example in the statsmodels docs, I
> included a page with related packages.

+1

> For the specific case of scipy.optimize, I think also some of the
> internal See Also can be removed, since many of the docstrings are
> almost a table of content of scipy.optimize, which also can be
> directly seen on the subpackage level. If I remember correctly, in
> some parts of scipy some weeding of umbrella SeeAlso has already
> occured.

+1

> On Wiki versus documentation pages, I think it would be helpful to
> introduce additional descriptive sections on the scipy.subpackage
> level, which could include specific Topical Software.

+0.5

--

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco
_______________________________________________
SciPy-Dev mailing list
SciPy-Dev <at> scipy.org
http://mail.scipy.org/mailman/listinfo/scipy-dev
Matthew Brett | 9 Feb 19:24
Picon

Re: Changes to trunk/scipy/optimize

Hi,


>> I think this would be useful on the module or scipy subpackage level >> but not for the docstrings for individual functions or classes. In my >> opinion, the docstring of function should provide only closely related >> functions and classes for quick lookup. Extra information should go >> into a different section, for example in the statsmodels docs, I >> included a page with related packages. > > +1
That seems a sensible suggestion. Matthew
Skipper Seabold | 9 Feb 17:03
Picon

Re: Changes to trunk/scipy/optimize

On Tue, Feb 9, 2010 at 9:31 AM,  <josef.pktd <at> gmail.com> wrote:
> 2010/2/9 Martin Lüthi <luethi <at> vaw.baug.ethz.ch>:
>> Hi
>>
>> At Tue, 9 Feb 2010 03:05:41 -0800,
>> Jarrod Millman wrote:
>>> Now the question is where is the best place for us to reference
>>> external, but relevant and useful Python projects.  My personal
>>> feeling is that it shouldn't be in the 'see also' section of our
>>> docstrings, but we don't have any official policy on that yet.  So we
>>> need to have a general discussion about what the general policy should
>>> be.
>>
>> I completely understand your reasoning. However, I would still find it useful
>> if there were a docstring section named "similar packages", mentioning either of
>>
>> a) relevant packages that are closely painfully integrated with scipy and are
>>   generally regarded as useful
>>
>> b) a link to the relevant URL of the topical software guide.
>>
>> Option (a) might lead to some "political" problems, which I cannot imagine
>> being difficult. Option (b) would be useful in any case. While checking out
>> code the Topical Software Pages or the Scipy Wiki are not the immediately
>> obvious places to look for more relevant information.
>

>

+1 to (b).  While I think (a), would be of more use, it could be
difficult to keep such sections clean, short, and relevant, but having
them some other place that's readily accessible is a good compromise.

I've been hearing some very mild push back against using Python from
others recently, because it's a "dark horse."  Whether or not this is
a fair moniker is irrelevant, but I think part of this is because it
doesn't feel like a totally integrated environment for problem solving
across packages (the fact that Python is much more general than this
seems to get lost...).  The question then is, is scipy the place to
act as a gateway for scientific problem solving writ large?  I'd say
yes...

> I think this would be useful on the module or scipy subpackage level
> but not for the docstrings for individual functions or classes. In my
> opinion, the docstring of function should provide only closely related
> functions and classes for quick lookup. Extra information should go
> into a different section, for example in the statsmodels docs, I
> included a page with related packages.
>

+1 Fair compromise.

> For the specific case of scipy.optimize, I think also some of the
> internal See Also can be removed, since many of the docstrings are
> almost a table of content of scipy.optimize, which also can be
> directly seen on the subpackage level. If I remember correctly, in
> some parts of scipy some weeding of umbrella SeeAlso has already
> occured.
>
> On Wiki versus documentation pages, I think it would be helpful to
> introduce additional descriptive sections on the scipy.subpackage
> level, which could include specific Topical Software.
>
> I'm using the numpy/scipy docs mainly through htmlhelp (.chm) where
> the tree view makes browsing very fast (similar to matlab help), maybe
> the html pages need more links than this.
>
> Josef
>
>
>>
>> Best, Martin

Skipper
Rob Clewley | 9 Feb 21:49
Picon

Re: Changes to trunk/scipy/optimize


> I completely understand your reasoning. However, I would still find it useful > if there were a docstring section named "similar packages", mentioning either of > > a) relevant packages that are closely painfully integrated with scipy and are >   generally regarded as useful > > b) a link to the relevant URL of the topical software guide. > > Option (a) might lead to some "political" problems, which I cannot imagine > being difficult. Option (b) would be useful in any case. While checking out > code the Topical Software Pages or the Scipy Wiki are not the immediately > obvious places to look for more relevant information.
+1 for (b). It achieves the same thing as (a) with only minimal additional inconvenience to the user but much greater convenience to developers of the external codes and to the maintainers of the scipy code. There is already a one stop shop for this info at the Topical Software wiki page, and this just has to be better advertised IMO. -Rob

Gmane