Repository: scipy/scipy

Issue:
DOC: Add "Examples" to docstrings
Many of the functions in scipy do not include examples in their docstrings.  Even a simple example can be helpful for a new user, so we should try to include examples wherever possible.

A script called `find_functions_missing_examples.py` is now maintained in my github repository [`analyze-scipy-code`](https://github.com/WarrenWeckesser/analyze-scipy-code).  This script reports the names of functions that are missing the "Examples" section.

Below is the output that I get when run with the current master branch.  Some of these functions have proper docstrings, so all they need is the addition of an "Examples" section containing one or more illustrative examples.  Many of them, however, do not comply with the [numpy docstring guidelines](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt), and may be missing the "Parameters" and "Returns" sections.  In particular, the docstrings of many of the functions in `scipy.special` are quite terse.  Anyone who works on this task should ensure that the final docstring complies with the guidelines.  See, for example, https://github.com/scipy/scipy/pull/7148, where the sections "Parameters", "Returns" and "Examples" were added to the docstring of `scipy.special.gamma`.

I have added the tag "good first issue" to this task, because it is usually very easy to add one or two examples to a function.  (How to edit the docstring of the functions in `scipy.special` is not obvious, but take a look at https://github.com/scipy/scipy/pull/7148 or https://github.com/scipy/scipy/pull/7143 for examples.)  The tag does not mean it will be easy to complete this task.  As you can see below, there is a lot of work to be done!   Anyone who wants to help should feel free to pick a function or two to work on.

The script ignores functions that have the string "is deprecated" in their docstring.  The names of other functions that should be ignored can be added to the list `skip`.  If you find such a function, add a comment about it here.

Functions missing "Examples" (last updated 26-May-2024):

```
scipy version 1.14.0.dev0+1320.0c590f4

datasets (1)
    download_all
fft (7)
    dst
    hfft2
    idst
    ifht
    ihfft2
    irfft2
    rfft2
ndimage (6)
    affine_transform
    generic_filter1d
    generic_gradient_magnitude
    generic_laplace
    morphological_laplace
    watershed_ift
odr (1)
    odr
optimize (5)
    excitingmixing
    fmin_ncg
    fmin_tnc
    linearmixing
    linprog_verbose_callback
signal (22)
    abcd_normalize
    band_stop_obj
    besselap
    buttap
    cheb1ap
    cheb2ap
    cspline2d
    ellipap
    hilbert2
    invres
    invresz
    lfiltic
    medfilt
    qspline2d
    residue
    residuez
    sos2zpk
    ss2zpk
    symiirorder1
    symiirorder2
    vectorstrength
    zpk2ss
sparse (1)
    kronsum
special (134)
    assoc_laguerre
    bdtr
    bdtrc
    bdtri
    bdtrik
    bdtrin
    bei_zeros
    beip
    beip_zeros
    ber_zeros
    berp
    berp_zeros
    btdtria
    btdtrib
    c_roots
    cg_roots
    chebyc
    chebys
    chndtr
    chndtridf
    chndtrinc
    chndtrix
    clpmn
    ellipeinc
    ellipj
    ellipk
    ellipkinc
    ellipkm1
    entr
    eval_chebyt
    eval_chebyu
    eval_gegenbauer
    eval_genlaguerre
    eval_hermite
    eval_hermitenorm
    eval_jacobi
    eval_laguerre
    eval_sh_chebyt
    eval_sh_chebyu
    eval_sh_jacobi
    eval_sh_legendre
    fresnel_zeros
    fresnelc_zeros
    fresnels_zeros
    h_roots
    hankel1
    hankel1e
    hankel2
    hankel2e
    he_roots
    hermitenorm
    j_roots
    jnjnp_zeros
    js_roots
    kei_zeros
    keip
    keip_zeros
    kelvin
    kelvin_zeros
    ker_zeros
    kerp
    kerp_zeros
    kl_div
    l_roots
    la_roots
    lmbda
    loggamma
    lpmn
    lpmv
    lpn
    lqmn
    lqn
    mathieu_a
    mathieu_b
    mathieu_cem
    mathieu_even_coef
    mathieu_modcem1
    mathieu_modcem2
    mathieu_modsem1
    mathieu_modsem2
    mathieu_odd_coef
    mathieu_sem
    modfresnelm
    modfresnelp
    obl_ang1
    obl_ang1_cv
    obl_cv
    obl_cv_seq
    obl_rad1
    obl_rad1_cv
    obl_rad2
    obl_rad2_cv
    pbdn_seq
    pbdv
    pbdv_seq
    pbvv
    pbvv_seq
    pbwa
    pro_ang1
    pro_ang1_cv
    pro_cv
    pro_cv_seq
    pro_rad1
    pro_rad1_cv
    pro_rad2
    pro_rad2_cv
    ps_roots
    rel_entr
    riccati_jn
    riccati_yn
    roots_chebyc
    roots_chebys
    roots_chebyt
    roots_chebyu
    roots_gegenbauer
    roots_genlaguerre
    roots_hermite
    roots_hermitenorm
    roots_jacobi
    roots_laguerre
    roots_sh_chebyt
    roots_sh_chebyu
    roots_sh_jacobi
    roots_sh_legendre
    s_roots
    sh_chebyt
    sh_chebyu
    sh_jacobi
    sh_legendre
    sph_harm
    t_roots
    ts_roots
    u_roots
    us_roots
stats (2)
    epps_singleton_2samp
    kstatvar
stats.mstats (46)
    f_oneway
    friedmanchisquare
    hdmedian
    hdquantiles_sd
    idealfourths
    kendalltau
    kendalltau_seasonal
    ks_1samp
    ks_2samp
    ks_twosamp
    kstest
    kurtosis
    kurtosistest
    mannwhitneyu
    median_cihs
    meppf
    mjci
    moment
    mquantiles_cimj
    msign
    normaltest
    obrientransform
    plotting_positions
    pointbiserialr
    rankdata
    rsh
    scoreatpercentile
    siegelslopes
    skew
    skewtest
    spearmanr
    theilslopes
    trimboth
    trimmed_mean
    trimmed_mean_ci
    trimmed_std
    trimmed_stde
    trimmed_var
    trimr
    trimtail
    tsem
    ttest_1samp
    ttest_ind
    ttest_onesamp
    ttest_rel
    tvar

Found 225 functions
```

(This issue was created March 13, 2017.  At that time, version 0.19.0 had just been released a few days earlier.  When I run this script on that version (with `'fft'` removed from `modules`), it finds 674 functions without examples.)

**Note:** if your PR only adds documentation, please add `[docs only]` on a new line in the commit message. This will help save our CI credits.


Discussion:
I am a newbie here. I exactly do not understand what the task is. Are the above commands do not have relevant examples for them?
@pssk1988 Yes.  The docstrings of those functions do not have an "Examples" section.

The docstring standard that scipy tries to follow is https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt; in particular, ["Sections"](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections) defines the sections that should be included in a docstring.  "Examples" is the last section described in the docstring standard.  According to the numpy docstring standard, "Examples" is an optional section, but many of us think it is a very important section, so we would like to ensure that as many functions as possible include it.



@WarrenWeckesser Okay. Thats interesting! I will take up a section of them, probably start with simpler ones.
I just started to add to examples. I forked scipy and performed `build` as mentioned [here](https://docs.scipy.org/doc/scipy-0.14.0/reference/hacking.html#recommended-development-setup). However, while trying to `import scipy` in Python, I get the following error:

```
>>> import scipy
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named scipy
```
I know I can do `pip install scipy`, but that's not the point of building the developer version of scipy, I guess. Can someone help?
> The docstring standard that scipy tries to follow is https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

There doesn't appear to be an example of an Examples section in that reference. Could someone add a few examples to this issue illustrating the desired format for the section to follow? E.g. where does it go relative to the other sections?
I've casually browsed through the examples in the current docs. It looked like that it comes at the very end after notes and references and *Added in version x.xxx*. But I'm not sure if this was intentional. It doesn't seem like this behavior is consistent.

I would like to correct the recent examples if this was not the case. To me before notes and references seems a better place content wise but if somebody just looks up the docstring on the prompt, the examples show up as the last thing which is also good avoiding the scroll in case of long Notes sections. 
The "Examples" section is the last section.  My understanding is that the recommended order of the sections in the docstring is the same as the order they are described at https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections.  I'm pretty sure that's the intent, and that's what we've been doing for years.  Any exceptions to that were probably accidental.
@WarrenWeckesser  This is my first contribution to an issue, so I started with a simple one. If it caters to the docstrings, how should I ask for a merge?
# numpy.average()

```python
"""The following module describes how to use 
the average function of the numpy class"""

# From the existing set of classes we import numpy
import numpy as np
# We can rename numpy as np. Once may use anything

# -----METHOD 1-----
"""What is Average?
average = [Sum of all the elements of array]/[Number of elements in array]"""

# Let us declare an array of integers as follows
data = [1,2,3,4]

# Let us store the average in a variable 'av'
av = np.average(data)

print('The average using Method 1 is:', av)

# -----METHOD 2 - Weights -----
"""What is Weighted Average?
Given data=[1,2,3,4] and weight=[0.1,0.2,0.3,0.4]
average = [(1*0.2)+(2*0.2)+(3*0.3)+(4*0.4)]/[0.1+0.2+0.3+0.4]
"""
# We are going to use the same data as in METHOD 1
# Here we are going to have weight as [0.1,0.2,0.3,0.4]

weight_array = [0.1,0.2,0.3,0.4]

"""SYNTAX for Weighted Average
Weighted_Average = numpy.average(<data_name>, weights = <weight_array>)
Remember, here, 'weights' is a Python Keyword"""

weighted_av = np.average(data, weights = weight_array)

print('The Weighted Average using Method 2 is: ', weighted_av)

```
@ss-is-master-chief Roughly summarizing: 

 - You can start by forking the official SciPy repository. You can simply do it from the upper right corner. 
 - Then you create a branch of a name you have chosen. And then you modify the necessary function docstring and commit your changes to that branch. 
 - Then you can create a Pull Request and people can review it and suggest changes and if it goes through gets merged with the official repository.

The branch creation is really important because if later on you would like to do something else then we have to sort out subtle conflicts between the master of SciPy and your master branch. Hence, to keep things contained we work in branches and only merge if we are fully sure that it doesn't break anything.

Please have a look at the similar function docstrings for examples. However note that `average` is a NumPy function so it is not related here. 
@ilayn Could you suggest me some functions which I could work upon? 
@ss-is-master-chief  Pick your favorite from the list above 😃 (except the linalg ones I'm about to submit a PR for them)
@WarrenWeckesser 
I believe that the documentation to the 23 functions of cluster.hierarchy is incomplete. Should I go ahead with it? It would take me two to three days (from the day of this comment) to prepare the complete doc.
@ss-is-master-chief yes please! You may want to submit a first PR after you've done a couple, just to make sure you get feedback that the examples look right before doing 20 more in a similar fashion.
@rgommers Awesome. Please do review my request once I do. Thanks in advance.
@WarrenWeckesser  @rgommers I have prepared the documentation for cluster.vq.kmeans2. Please have a look. :)
is this issue still open?
which functions need examples?
@RadZaeem yes it is open. The functions are listed in the description.
Hello, I crated an example for **voronoi_plot_2d**, but when I generate the documentation with:
'''
 python setup.py build_sphinx
'''
no figures are created. Is there some other method for generating documentation with plots?
In `doc/`, use `make html` to build the docs locally
It would be great to have a global documentation sprint, similar to what pandas did a while ago :)

https://www.numfocus.org/blog/worldwide-pandas-sprint
scipy.integrate.dblquad not mentioned in the list above. Can I add an example for it?
@vagishagupta23, thanks for your interest in contributing! `dblquad` is not mentioned because it already has an "Examples" section; see https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.dblquad.html (scroll down to the bottom to see the example).

Check the list for other functions with docstrings that need examples.  If something interests you, go ahead and work on it.
Hi! This is the first issue I have tried to contribute to. I would like to add an example to fft2 listed above. Are the above guidelines explained and other reference documentation still the current practice? Thanks!
@nwjenkins Thanks for helping out. Yes, you can pick and choose any of them. We just have a mild requirement of having the example explanatory and not too specific. If you can cover all the args and keywords that would be the unicorn example. Just keep an eye on PEP8 and also empty lines in between the code and the text when you are alternating between them. 

Having said that I do see an example for `fft2` at the [current master branch](http://scipy.github.io/devdocs/generated/scipy.fft.fft2.html#scipy.fft.fft2) Did you mean something else? You can use the [`fft` example](http://scipy.github.io/devdocs/generated/scipy.fft.fft.html#scipy.fft.fft) as a template 


@ilayn Thanks for the info! I was just going by the list above which includes fft2 under fftpack. I do see that it already has an example now, maybe I'm misinterpreting the list? In any case, I will find another function from the list if that is already accounted for.
You are right. That was the fftpack one. Sorry for the noise
Hello all, I have subscribed to this forum but was busy due to my main work. I have some spare time now and can contribute. Where can I start? If someone can point me to easy open tickets, that will be nice.
First time contributor here, I've forked the repository, will do quad_vec. I was going to do the quad_explain but could not find the file. Only question I had was, how do I define a vector valued function?
@WarrenWeckesser I think there are some legacy functions, should these functions has Examples?
For example:
- fftpack module is legacy functions
- optimize has many legacy functions like:
anderson, broyden1, broyden2, diagbroyden, excitingmixing, fmin_bfgs, fmin_l_bfgs_b, fmin_ncg
fmin_tnc, linearmixing, newton_krylov 

> fftpack module is legacy functions

No need to spend effort on these functions I think. It's not quite deprecated, but all new code should use `scipy.fft`.

> optimize has many legacy functions like

Those aren't going anywhere. I would think examples can be helpful, but can be minimal - anything fancy would make more sense as a tutorial for a set of functions, individual examples are all going to look similar and it's the differences between them that's more interesting probably.
The `fft` namespace is missing though in the overview, so the list of documented functions there won't change, just `fftpack` -> `fft`.
@rgommers Thank you for your comments. OK I understood. 

I have cloned scipy/scipy when I entered python3 runtests.py --doc html to cmd it is showing this stuff-
Traceback (most recent call last):
  File "setup.py", line 590, in <module>
    setup_package()
  File "setup.py", line 565, in setup_package
    from numpy.distutils.core import setup
ModuleNotFoundError: No module named 'numpy'

Build failed! (0:00:01.022104 elapsed)


as I am a newbie here so can somebody please help me out :)

Hi @1sarthakbhardwaj please just install `numpy` in your environment, that should fix this.
I have installed NumPy but i have got even bigger error while building it,
Building, see build.log...
scipy/linalg/_generate_pyx.py: all files up-to-date
scipy/special/_generate_pyx.py: all files up-to-date
Running scipy\linalg\_generate_pyx.py
Running scipy\special\_generate_pyx.py
scipy\cluster\_hierarchy.pyx has not changed
scipy\io\matlab\mio_utils.pyx has not changed
scipy\io\matlab\streams.pyx has not changed
scipy\linalg\cython_blas.pyx has not changed
scipy\linalg\cython_lapack.pyx has not changed
scipy\linalg\_decomp_update.pyx.in has not changed
scipy\linalg\_matfuncs_sqrtm_triu.pyx has not changed
scipy\linalg\_solve_toeplitz.pyx has not changed
scipy\ndimage\src\_cytest.pyx has not changed
scipy\ndimage\src\_ni_label.pyx has not changed
scipy\optimize\_bglu_dense.pyx has not changed
scipy\optimize\_group_columns.pyx has not changed
scipy\optimize\cython_optimize\_zeros.pyx.in has not changed
scipy\optimize\_lsq\givens_elimination.pyx has not changed
scipy\optimize\_trlib\_trlib.pyx has not changed
scipy\signal\_max_len_seq_inner.pyx has not changed
scipy\signal\_peak_finding_utils.pyx has not changed
scipy\signal\_sosfilt.pyx has not changed
scipy\signal\_spectral.pyx has not changed
scipy\signal\_upfirdn_apply.pyx has not changed
scipy\sparse\_csparsetools.pyx.in has not changed
scipy\sparse\csgraph\_flow.pyx has not changed
scipy\sparse\csgraph\_matching.pyx has not changed
scipy\sparse\csgraph\_min_spanning_tree.pyx has not changed
scipy\sparse\csgraph\_reordering.pyx has not changed
scipy\sparse\csgraph\_shortest_path.pyx has not changed
scipy\sparse\csgraph\_tools.pyx has not changed
scipy\sparse\csgraph\_traversal.pyx has not changed
scipy\spatial\ckdtree.pyx has not changed
scipy\spatial\qhull.pyx has not changed
scipy\spatial\_hausdorff.pyx has not changed
scipy\spatial\_voronoi.pyx has not changed
scipy\interpolate\interpnd.pyx has not changed
scipy\special\cython_special.pyx has not changed
scipy\special\_comb.pyx has not changed
scipy\special\_ellip_harm_2.pyx has not changed
scipy\special\_test_round.pyx has not changed
scipy\special\_ufuncs.pyx has not changed
scipy\special\_ufuncs_cxx.pyx has not changed
scipy\stats\_stats.pyx has not changed
scipy\_lib\messagestream.pyx has not changed
scipy\_lib\_ccallback_c.pyx has not changed
scipy\_lib\_test_deprecation_call.pyx has not changed
scipy\_lib\_test_deprecation_def.pyx has not changed
scipy\cluster\_vq.pyx has not changed
scipy\fftpack\convolve.pyx has not changed
scipy\spatial\transform\rotation.pyx has not changed
scipy\interpolate\_bspl.pyx has not changed
scipy\interpolate\_ppoly.pyx has not changed
scipy\io\matlab\mio5_utils.pyx has not changed
scipy\cluster\_optimal_leaf_ordering.pyx has not changed
Cythonizing sources
lapack_opt_info:
lapack_mkl_info:
No module named 'numpy.distutils._msvccompiler' in numpy.distutils; trying
from distutils
customize MSVCCompiler
  libraries mkl_rt not found in ['C:/Users/7sart/anaconda3\\Library\\lib']
  NOT AVAILABLE

openblas_lapack_info:
  libraries openblas not found in ['C:\\Users\\7sart\\anaconda3\\lib',
'C:\\', 'C:\\Users\\7sart\\anaconda3\\libs']
get_default_fcompiler: matching types: '['gnu', 'intelv', 'absoft',
'compaqv', 'intelev', 'gnu95', 'g95', 'intelvem', 'intelem', 'flang']'
customize GnuFCompiler
Could not locate executable g77
Could not locate executable f77
customize IntelVisualFCompiler
Could not locate executable ifort
Could not locate executable ifl
customize AbsoftFCompiler
Could not locate executable f90
customize CompaqVisualFCompiler
Could not locate executable DF
customize IntelItaniumVisualFCompiler
Could not locate executable efl
customize Gnu95FCompiler
Found executable C:\MinGW\bin\gfortran.exe
Using built-in specs.
COLLECT_GCC=C:\MinGW\bin\gfortran.exe
COLLECT_LTO_WRAPPER=c:/mingw/bin/../libexec/gcc/mingw32/6.3.0/lto-wrapper.exe
Target: mingw32
Configured with: ../src/gcc-6.3.0/configure --build=x86_64-pc-linux-gnu
--host=mingw32 --with-gmp=/mingw --with-mpfr=/mingw --with-mpc=/mingw
--with-isl=/mingw --prefix=/mingw --disable-win32-registry --target=mingw32
--with-arch=i586 --enable-languages=c,c++,objc,obj-c++,fortran,ada
--with-pkgversion='MinGW.org GCC-6.3.0-1' --enable-static --enable-shared
--enable-threads --with-dwarf2 --disable-sjlj-exceptions
--enable-version-specific-runtime-libs --with-libiconv-prefix=/mingw
--with-libintl-prefix=/mingw --enable-libstdcxx-debug --with-tune=generic
--enable-libgomp --disable-libvtv --enable-nls
Thread model: win32
gcc version 6.3.0 (MinGW.org GCC-6.3.0-1)
  NOT AVAILABLE

openblas_clapack_info:
  libraries openblas,lapack not found in
['C:\\Users\\7sart\\anaconda3\\lib', 'C:\\',
'C:\\Users\\7sart\\anaconda3\\libs']
get_default_fcompiler: matching types: '['gnu', 'intelv', 'absoft',
'compaqv', 'intelev', 'gnu95', 'g95', 'intelvem', 'intelem', 'flang']'
customize GnuFCompiler
customize IntelVisualFCompiler
customize AbsoftFCompiler
customize CompaqVisualFCompiler
customize IntelItaniumVisualFCompiler
customize Gnu95FCompiler
Using built-in specs.
COLLECT_GCC=C:\MinGW\bin\gfortran.exe
COLLECT_LTO_WRAPPER=c:/mingw/bin/../libexec/gcc/mingw32/6.3.0/lto-wrapper.exe
Target: mingw32
Configured with: ../src/gcc-6.3.0/configure --build=x86_64-pc-linux-gnu
--host=mingw32 --with-gmp=/mingw --with-mpfr=/mingw --with-mpc=/mingw
--with-isl=/mingw --prefix=/mingw --disable-win32-registry --target=mingw32
--with-arch=i586 --enable-languages=c,c++,objc,obj-c++,fortran,ada
--with-pkgversion='MinGW.org GCC-6.3.0-1' --enable-static --enable-shared
--enable-threads --with-dwarf2 --disable-sjlj-exceptions
--enable-version-specific-runtime-libs --with-libiconv-prefix=/mingw
--with-libintl-prefix=/mingw --enable-libstdcxx-debug --with-tune=generic
--enable-libgomp --disable-libvtv --enable-nls
Thread model: win32
gcc version 6.3.0 (MinGW.org GCC-6.3.0-1)
  NOT AVAILABLE

flame_info:
  libraries flame not found in ['C:\\Users\\7sart\\anaconda3\\lib', 'C:\\',
'C:\\Users\\7sart\\anaconda3\\libs']
  NOT AVAILABLE

atlas_3_10_threads_info:
Setting PTATLAS=ATLAS
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\lib
  libraries tatlas,tatlas not found in C:\Users\7sart\anaconda3\lib
  libraries lapack_atlas not found in C:\
  libraries tatlas,tatlas not found in C:\
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\libs
  libraries tatlas,tatlas not found in C:\Users\7sart\anaconda3\libs
<class 'numpy.distutils.system_info.atlas_3_10_threads_info'>
  NOT AVAILABLE

atlas_3_10_info:
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\lib
  libraries satlas,satlas not found in C:\Users\7sart\anaconda3\lib
  libraries lapack_atlas not found in C:\
  libraries satlas,satlas not found in C:\
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\libs
  libraries satlas,satlas not found in C:\Users\7sart\anaconda3\libs
<class 'numpy.distutils.system_info.atlas_3_10_info'>
  NOT AVAILABLE

atlas_threads_info:
Setting PTATLAS=ATLAS
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\lib
  libraries ptf77blas,ptcblas,atlas not found in
C:\Users\7sart\anaconda3\lib
  libraries lapack_atlas not found in C:\
  libraries ptf77blas,ptcblas,atlas not found in C:\
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\libs
  libraries ptf77blas,ptcblas,atlas not found in
C:\Users\7sart\anaconda3\libs
<class 'numpy.distutils.system_info.atlas_threads_info'>
  NOT AVAILABLE

atlas_info:
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\lib
  libraries f77blas,cblas,atlas not found in C:\Users\7sart\anaconda3\lib
  libraries lapack_atlas not found in C:\
  libraries f77blas,cblas,atlas not found in C:\
  libraries lapack_atlas not found in C:\Users\7sart\anaconda3\libs
  libraries f77blas,cblas,atlas not found in C:\Users\7sart\anaconda3\libs
<class 'numpy.distutils.system_info.atlas_info'>
  NOT AVAILABLE

accelerate_info:
  NOT AVAILABLE

lapack_info:
  libraries lapack not found in ['C:\\Users\\7sart\\anaconda3\\lib',
'C:\\', 'C:\\Users\\7sart\\anaconda3\\libs']
  NOT AVAILABLE

lapack_src_info:
  NOT AVAILABLE

  NOT AVAILABLE

C:\Users\7sart\anaconda3\lib\site-packages\setuptools\distutils_patch.py:25:
UserWarning: Distutils was imported before Setuptools. This usage is
discouraged and may exhibit undesirable behaviors or errors. Please use
Setuptools' objects directly or at least import Setuptools first.
  warnings.warn(
Running from SciPy source directory.
C:\Users\7sart\anaconda3\lib\site-packages\numpy\distutils\system_info.py:1730:
UserWarning:
    Lapack (http://www.netlib.org/lapack/) libraries not found.
    Directories to search for the libraries can be specified in the
    numpy/distutils/site.cfg file (section [lapack]) or by setting
    the LAPACK environment variable.
  return getattr(self, '_calc_info_{}'.format(name))()
C:\Users\7sart\anaconda3\lib\site-packages\numpy\distutils\system_info.py:1730:
UserWarning:
    Lapack (http://www.netlib.org/lapack/) sources not found.
    Directories to search for the sources can be specified in the
    numpy/distutils/site.cfg file (section [lapack_src]) or by setting
    the LAPACK_SRC environment variable.
  return getattr(self, '_calc_info_{}'.format(name))()
Traceback (most recent call last):
  File "setup.py", line 590, in <module>
    setup_package()
  File "setup.py", line 586, in setup_package
    setup(**metadata)
  File
"C:\Users\7sart\anaconda3\lib\site-packages\numpy\distutils\core.py", line
137, in setup
    config = configuration()
  File "setup.py", line 484, in configuration
    raise NotFoundError(msg)
numpy.distutils.system_info.NotFoundError: No BLAS/LAPACK libraries found.
To build Scipy from sources, BLAS & LAPACK libraries need to be installed.
See site.cfg.example in the Scipy source directory and
https://docs.scipy.org/doc/scipy/reference/building/index.html for details.

Build failed! (0:00:11.713980 elapsed)




On Wed, Sep 30, 2020 at 7:55 PM Ralf Gommers <notifications@github.com>
wrote:

> Hi @1sarthakbhardwaj <https://github.com/1sarthakbhardwaj> please just
> install numpy in your environment, that should fix this.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/scipy/scipy/issues/7168#issuecomment-701425555>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AO4ZSSDJCI24QZCAQNQLTWTSIM5V3ANCNFSM4DDQLKJQ>
> .
>

Hi @1sarthakbhardwaj can you please open a new issue for this? It doesn't quite belong here. In general: you should try to read the error message you're getting backwards (start at the end) the relevant message is:
```
To build Scipy from sources, BLAS & LAPACK libraries need to be installed.
See site.cfg.example in the Scipy source directory and
https://docs.scipy.org/doc/scipy/reference/building/index.html for details
```
Alright i will open an issue

On Wed, Sep 30, 2020, 22:20 Ralf Gommers <notifications@github.com> wrote:

> Hi @1sarthakbhardwaj <https://github.com/1sarthakbhardwaj> can you please
> open a new issue for this? It doesn't quite belong here. In general: you
> should try to read the error message you're getting backwards (start at the
> end) the relevant message is:
>
> To build Scipy from sources, BLAS & LAPACK libraries need to be installed.
> See site.cfg.example in the Scipy source directory andhttps://docs.scipy.org/doc/scipy/reference/building/index.html for details
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/scipy/scipy/issues/7168#issuecomment-701513018>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AO4ZSSBVHZF2IO7P4OMQIELSINOWJANCNFSM4DDQLKJQ>
> .
>

For the PyCon 2021 sprint on May 16,  here are a few functions with docstrings that are missing an "Examples" section for which a few interesting examples can be added fairly easily:

* `scipy.stats.trim1`
* `scipy.special.bernoulli`
  Needs 'Parameters', 'Returns', 'Examples' (see https://numpydoc.readthedocs.io/en/latest/format.html#sections for all the required and optional sections of a docstring).

  We could also add a reference to the wikipedia page.

  A simple trivial example is something like

        >>> from scipy.special import bernoulli, zeta
        >>> bernoulli(4)
        array([ 1.        , -0.5       ,  0.16666667,  0.        , -0.03333333])

        The wikipedia article points out the relationship between the
        Bernoulli numbers and the zeta function, B_n^+ = -n * zeta(1 - n)
        for n > 0:

        >>> n = np.arange(1, 5)
        >>> -n * zeta(1 - n)
        array([ 0.5       ,  0.16666667, -0.        , -0.03333333])

        Note that, in the notation used in the wikipedia article,
        `bernoulli` computes B_n^- (i.e. it used the convention that
        B_1 is -1/2).  The relation given above is for B_n^+, so the
        sign of 0.5 does not match the output of `bernoulli(4)`.

* `scipy.special.hermite`
  Maybe something like:

        >>> p = hermite(4)
        >>> p  # Show that the return value is a poly1d object
        >>> p(0.5)  # Evaluate at a point.

  And then a loop that plots the first four or five polynomials over the interval [-3, 3], with `ylim(-40, 40)`

* `scipy.special.gegenbauer`
  Similar notes as for hermite.

  Could also verfiy the orthogonality by computing integrals of products using
  `scipy.integrate.quad`, with `weight='alg'` and `wvar=(alpha-0.5, alpha-0.5)`.
Working on `trim1` adding example section to docstring
Adding example section to docstring in `scipy.special.hermite`
Working on `gegenbauer` example area within docstring
Working on `bernoulli`
I notice parameter (n) and return parameters are missing as well as the example
Thanks a lot @lgfunderburk you don't need to ping this issue, just go for it and we'll take them out of the list 😎 
@ilayn normally that's true, but the recent comments were from participants in the PyCon sprint yesterday.  Because several people were working on updating docstrings, we recommended that they make a comment here to indicate which function they were working on.
Ha! that's great. Then my gratitude to the participants. Didn't know it was these days.
For further examples: @ilayn pointed out https://github.com/scipy/scipy/pull/14063#discussion_r634249543 that we should use the OO interface of Matplotlib in the examples. +1 here.
I'm adding examples and references to jacobi polynomials docstring, and some others
I updated the script to include the `uarray._Function` instances in the `scipy.fft` namespace.
For anyone also looking into `scipy.special`: I seek to finish examples for all Bessel functions for the next release.
Thanks @dschmitz89. Since you will have had an exposure to all these, it would be very helpful if you could add some summary of all these and how to use what/when in the tutorials for instance.
> Thanks @dschmitz89. Since you will have had an exposure to all these, it would be very helpful if you could add some summary of all these and how to use what/when in the tutorials for instance.

I am not confident that I can write a useful tutorial for them as I never really used them myself besides writing those examples. I am not even familiar with typical use cases (physics bachelor memories are fading by now ..).
No problem 😃 
Could this issue be pinned? Would draw more attention and I think this is a good start for first time contributors.
At the risk of being annoying: I see that there is again space in the top panel, so could this issue be pinned?
Sorry that no one responded to your initial suggestion to pin this issue.  My first inclination was that being tagged "good first issue" was probably enough.  Of course, being pinned would make the issue far more discoverable for a casual browser of the github issues.  But that's true for any issue.

I don't think this issue "reaches the bar" (whatever that is) for being pinned, but I won't object if gets pinned.

-----

What makes an issue "pinnable"?  I don't know.  A good use of pinning has been when we were getting many duplicate issues for a known problem, such as support for Python 3.11. We currently have two pinned issues (gh-17278 and gh-15765), but I wonder if those would be better as github projects. Certainly gh-15765 seems like it could be better managed as a project.  But that is a casual, "drive by" suggestion, and certainly not a demand--I haven't used the github projects interface, so I don't know if converting that issue to a project would be more trouble than it is worth.

Thanks for the reply. Of course the bar for an issue to be "pinnable" must be reasonably high.

scikit-learn folks crowd sourced another tedious issue similar to this by pinning: making sure that their examples pass numpydoc validation (see [here](https://github.com/scikit-learn/scikit-learn/issues/21350)). For a long time this meta issue was very visible in the issue tracker and drew a lot of attention followed by PRs. In my opinion, adding examples to the documentation is of uttermost importance for SciPy and by pinning hopefully a momentum like for the sklearn issue could be reached.
I want to work on this issue. Please assign me the same!
@SoubhagyaKhan thanks for lending a hand. We don't assign issues but instead you can pick a function from the list at the top and open a pull request for review. You can see many examples above in the mentioned issues, how to go about it but let us know if you need more help. 
Thank you for the reply.I will definitely do so.
On Thu, 12 Jan 2023, 14:03 Ilhan Polat, ***@***.***> wrote:

> @SoubhagyaKhan <https://github.com/SoubhagyaKhan> thanks for lending a
> hand. We don't assign issues but instead you can pick a function from the
> list at the top and open a pull request for review. You can see many
> examples above in the mentioned issues, how to go about it but let us know
> if you need more help.
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/scipy/scipy/issues/7168#issuecomment-1379976615>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/A3SAMO3ZRDLE4QXM3IT5QKLWR66XJANCNFSM4DDQLKJQ>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

Hi @WarrenWeckesser . I'm interested in contributing to this repository. Can you assign me to this issue?

Hi @meaviral17, thank you for your interest. We do not assign issues. You are free to take up some function which does not have example and add some. Please read the thread for further details, examples, etc. There is a lot of valuable info here 😃 

Resolving patch:
diff --git a/scipy/fft/_fftlog.py b/scipy/fft/_fftlog.py
--- a/scipy/fft/_fftlog.py
+++ b/scipy/fft/_fftlog.py
@@ -334,6 +334,17 @@ def fhtoffset(dln, mu, initial=0.0, bias=0.0):
         Optimal offset of the uniform logarithmic spacing of the transform that
         fulfils a low-ringing condition.
 
+    Examples
+    --------
+    >>> from scipy.fft import fhtoffset
+    >>> dln = 0.1
+    >>> mu = 2.0
+    >>> initial = 0.5
+    >>> bias = 0.0
+    >>> offset = fhtoffset(dln, mu, initial, bias)
+    >>> offset
+    0.5454581477676637
+
     See Also
     --------
     fht : Definition of the fast Hankel transform.
diff --git a/scipy/stats/_stats_py.py b/scipy/stats/_stats_py.py
--- a/scipy/stats/_stats_py.py
+++ b/scipy/stats/_stats_py.py
@@ -9629,6 +9629,24 @@ def combine_pvalues(pvalues, method='fisher', weights=None):
         pvalue : float
             The combined p-value.
 
+    Examples
+    --------
+    Suppose we wish to combine p-values from four independent tests
+    of the same null hypothesis using Fisher's method (default).
+
+    >>> from scipy.stats import combine_pvalues
+    >>> pvalues = [0.1, 0.05, 0.02, 0.3]
+    >>> combine_pvalues(pvalues)
+    SignificanceResult(statistic=20.828626352604235, pvalue=0.007616871850449092)
+
+    When the individual p-values carry different weights, consider Stouffer's
+    method.
+
+    >>> weights = [1, 2, 3, 4]
+    >>> res = combine_pvalues(pvalues, method='stouffer', weights=weights)
+    >>> res.pvalue
+    0.009578891494533616
+
     Notes
     -----
     If this function is applied to tests with a discrete statistics such as


Test patch: