diff --git a/.gitignore b/.gitignore index c78ea1d83..cbcf3492b 100644 --- a/.gitignore +++ b/.gitignore @@ -44,8 +44,8 @@ lib lib64 # sphinx build directory doc/_build -doc/reference/statistics/ -doc/reference/unitary_event_analysis/ +doc/reference/toctree/* +!doc/reference/toctree/kernels/ *.h5 # setup.py dist directory dist diff --git a/MANIFEST.in b/MANIFEST.in index cffdc4477..c154fd144 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,11 +5,13 @@ include LICENSE.txt include elephant/VERSION include elephant/current_source_density_src/README.md include elephant/current_source_density_src/test_data.mat -include elephant/neural_trajectory_src/README.md -include elephant/spade_src/LICENCE -include elephant/gpfa_src/INFO.md +include elephant/spade_src/LICENSE recursive-include elephant/spade_src *.so *.pyd include elephant/test/spike_extraction_test_data.txt recursive-include doc * prune doc/_build -recursive-exclude . *~ +prune doc/tutorials/.ipynb_checkpoints +prune doc/reference/toctree +include doc/reference/toctree/kernels/* +recursive-exclude * *.h5 +recursive-exclude * *~ diff --git a/doc/authors.rst b/doc/authors.rst index 570258518..4478e8b22 100644 --- a/doc/authors.rst +++ b/doc/authors.rst @@ -8,6 +8,9 @@ The following people have contributed code and/or ideas to the current version of Elephant. The institutional affiliations are those at the time of the contribution, and may not be the current affiliation of a contributor. +Do you want to contribute to Elephant? Please refer to the +:ref:`developers_guide`. + * Alper Yegenoglu [1] * Andrew Davison [2] * Björn Müller [1] diff --git a/doc/documentation_guide.rst b/doc/documentation_guide.rst index ff48bd322..f41d53abe 100644 --- a/doc/documentation_guide.rst +++ b/doc/documentation_guide.rst @@ -21,7 +21,7 @@ Building the documentation The documentation in :file:`doc/` folder is written in `reStructuredText `_, using the `Sphinx `_ documentation system. To build the -documentation:: +documentation: 1. Install requirements-docs.txt and requirements-tutorials.txt in the same way as it's explained in :ref:`developers_guide` step 3:: diff --git a/doc/images/tutorials/tutorial_1_figure_1.png b/doc/images/tutorials/tutorial_1_figure_1.png deleted file mode 100644 index f61e2afc6..000000000 Binary files a/doc/images/tutorials/tutorial_1_figure_1.png and /dev/null differ diff --git a/doc/images/tutorials/tutorial_1_figure_2.png b/doc/images/tutorials/tutorial_1_figure_2.png deleted file mode 100644 index e289890cd..000000000 Binary files a/doc/images/tutorials/tutorial_1_figure_2.png and /dev/null differ diff --git a/doc/index.rst b/doc/index.rst index bb0fc2cb5..5b10a80bf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,7 +33,7 @@ Table of Contents authors release_notes get_in_touch - acknowledgements + acknowledgments diff --git a/doc/maintaners_guide.rst b/doc/maintainers_guide.rst similarity index 77% rename from doc/maintaners_guide.rst rename to doc/maintainers_guide.rst index 50a318fa0..cf8e72869 100644 --- a/doc/maintaners_guide.rst +++ b/doc/maintainers_guide.rst @@ -83,7 +83,7 @@ The module docstring of ``elephant/x.py`` is also standardized in its structure: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: x/ + :toctree: toctree/x/ function1 function2 @@ -92,7 +92,7 @@ The module docstring of ``elephant/x.py`` is also standardized in its structure: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: x/ + :toctree: toctree/x/ function3 function4 @@ -119,29 +119,35 @@ Making a release 1. Increment the Elephant package version in :file:`elephant/VERSION`. 2. Add a section in :file:`doc/release_notes.rst`, describing in short the -changes made from the previous release. + changes made from the previous release. 3. Check that the copyright statement (in :file:`LICENSE.txt`, -:file:`README.md`, and :file:`doc/conf.py`) is correct. + :file:`README.md`, and :file:`doc/conf.py`) is correct. -4. If there is a new module do not forget to add the modulename to the -:file:`doc/modules.rst` and make a file with a short description in -:file:`doc/reference/.rst`. +4. If there is a new module do not forget to add the module name to the + :file:`doc/modules.rst` and make a file with a short description in + :file:`doc/reference/.rst`. -To build a source package (see `Packaging Python Projects -`_):: +5. Remove :file:`elephant/spade_src/fim.so`. Otherwise, it'll be included in + the built package (it should be downloaded at pip install). + +6. Build a source package and upload it to PyPi. + + Build a source package (see `Packaging Python Projects + `_):: $ pip install --user --upgrade twine $ python setup.py sdist -To upload the package to `PyPI `_ -(if you have the necessary permissions):: + To upload the package to `PyPI `_ + (if you have the necessary permissions):: - $ python -m twine upload dist/elephant-x.x.x.tar.gz + $ python -m twine upload dist/elephant-X.Y.Z.tar.gz -Finally, tag the release in the Git repository and push it:: +7. Finally, make a release on GitHub UI page and copy-paste the release notes. + Then tag the release in the Git repository and push it:: $ git tag $ git push --tags upstream -Here, version should be of the form ``vX.Y.Z``. + Here, version should be of the form ``vX.Y.Z``. diff --git a/doc/reference/kernels/elephant.kernels.AlphaKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.AlphaKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.AlphaKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.AlphaKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.EpanechnikovLikeKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.EpanechnikovLikeKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.EpanechnikovLikeKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.EpanechnikovLikeKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.ExponentialKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.ExponentialKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.ExponentialKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.ExponentialKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.GaussianKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.GaussianKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.GaussianKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.GaussianKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.Kernel.rst b/doc/reference/toctree/kernels/elephant.kernels.Kernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.Kernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.Kernel.rst diff --git a/doc/reference/kernels/elephant.kernels.LaplacianKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.LaplacianKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.LaplacianKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.LaplacianKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.RectangularKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.RectangularKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.RectangularKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.RectangularKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.SymmetricKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.SymmetricKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.SymmetricKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.SymmetricKernel.rst diff --git a/doc/reference/kernels/elephant.kernels.TriangularKernel.rst b/doc/reference/toctree/kernels/elephant.kernels.TriangularKernel.rst similarity index 100% rename from doc/reference/kernels/elephant.kernels.TriangularKernel.rst rename to doc/reference/toctree/kernels/elephant.kernels.TriangularKernel.rst diff --git a/elephant/asset.py b/elephant/asset.py index da26a0c17..4832faa50 100644 --- a/elephant/asset.py +++ b/elephant/asset.py @@ -787,9 +787,9 @@ def cluster_matrix_entries(mat, eps=10, min=2, stretch=5): def probability_matrix_montecarlo( spiketrains, binsize, dt, t_start_x=None, t_start_y=None, surr_method='dither_spike_train', j=None, n_surr=100, verbose=False): - ''' + """ Given a list of parallel spike trains, estimate the cumulative probability - of each entry in their intersection matrix (see: intersection_matrix()) + of each entry in their intersection matrix (see: intersection_matrix()) by a Monte Carlo approach using surrogate data. Contrarily to the analytical version (see: probability_matrix_analytical()) the Monte Carlo one does not incorporate the assumptions of Poissonianity @@ -799,8 +799,8 @@ def probability_matrix_montecarlo( at disposal, see below) and calculates their intersection matrix M. For each entry (i, j), the intersection cdf P[i, j] is then given by: - .. centered:: P[i, j] = #(spike_train_surrogates such that M[i, j] < I[i, j]) / - #(spike_train_surrogates) + .. centered:: P[i, j] = #(spike_train_surrogates such that M[i, j] < + I[i, j]) / #(spike_train_surrogates) If P[i, j] is large (close to 1), I[i, j] is statistically significant: the probability to observe an overlap equal to or larger then I[i, j] @@ -853,7 +853,7 @@ def probability_matrix_montecarlo( See also -------- probability_matrix_analytical : for analytical derivation of the matrix - ''' + """ # Compute the intersection matrix of the original data imat, x_edges, y_edges = intersection_matrix( @@ -1260,7 +1260,7 @@ def _pmat_neighbors(mat, filter_shape, nr_largest=None, diag=0): def joint_probability_matrix( pmat, filter_shape, nr_largest=None, alpha=0, pvmin=1e-5): - ''' + """ Map a probability matrix pmat to a joint probability matrix jmat, where jmat[i, j] is the joint p-value of the largest neighbors of pmat[i, j]. @@ -1302,18 +1302,22 @@ def joint_probability_matrix( ---------- [1] Torre et al (in prep) ... - Example - ------- - # Assuming to have a list sts of parallel spike trains over 1s recording, - # the following code computes the intersection/probability/joint-prob - # matrices imat/pmat/jmat using a bin width of 5 ms + Examples + -------- + Assuming to have a list sts of parallel spike trains over 1s recording, + the following code computes the intersection/probability/joint-prob + matrices imat/pmat/jmat using a bin width of 5 ms: + + >>> import quantities as pq + >>> from elephant import asset >>> T = 1 * pq.s >>> binsize = 5 * pq.ms - >>> imat, xedges, yedges = intersection_matrix(sts, binsize=binsize, dt=T) - >>> pmat = probability_matrix_analytical(sts, binsize, dt=T) - >>> jmat = joint_probability_matrix(pmat, filter_shape=(fl, fw)) + >>> imat, xedges, yedges = asset.intersection_matrix(sts, + ... binsize=binsize, dt=T) + >>> pmat = asset.probability_matrix_analytical(sts, binsize, dt=T) + >>> jmat = asset.joint_probability_matrix(pmat, filter_shape=(fl, fw)) - ''' + """ # Find for each P_ij in the probability matrix its neighbors and maximize # them by the maximum value 1-pvmin pmat_neighb = _pmat_neighbors( diff --git a/elephant/cell_assembly_detection.py b/elephant/cell_assembly_detection.py index 6bb08ab0c..edc6dab35 100644 --- a/elephant/cell_assembly_detection.py +++ b/elephant/cell_assembly_detection.py @@ -20,8 +20,8 @@ applied as demonstrated in this short toy example of 5 parallel spike trains that exhibit fully synchronous events of order 5. -Example -------- +Examples +-------- >>> import matplotlib.pyplot as plt >>> import elephant.conversion as conv >>> import elephant.spike_train_generation diff --git a/elephant/kernels.py b/elephant/kernels.py index 6b6a96073..58b93dc83 100644 --- a/elephant/kernels.py +++ b/elephant/kernels.py @@ -9,7 +9,7 @@ ~~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: kernels/ + :toctree: toctree/kernels/ Kernel SymmetricKernel @@ -18,7 +18,7 @@ ~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: kernels/ + :toctree: toctree/kernels/ RectangularKernel TriangularKernel @@ -30,7 +30,7 @@ ~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: kernels/ + :toctree: toctree/kernels/ ExponentialKernel AlphaKernel @@ -186,8 +186,8 @@ def boundary_enclosing_area_fraction(self, fraction): whole probability mass of the kernel is concentrated over negative support for inverted kernels. - Parameter - --------- + Parameters + ---------- fraction : float Fraction of the whole area which has to be enclosed. diff --git a/elephant/pandas_bridge.py b/elephant/pandas_bridge.py index 141071a50..c18803752 100644 --- a/elephant/pandas_bridge.py +++ b/elephant/pandas_bridge.py @@ -582,8 +582,8 @@ def slice_spiketrain(pdobj, t_start=None, t_stop=None): pdobj : scalar, pandas Series, DataFrame, or Panel The returned data type is the same as the type of `pdobj` - Note - ---- + Notes + ----- The order of the index and/or column levels of the returned object may differ from the order of the original. diff --git a/elephant/spike_train_dissimilarity.py b/elephant/spike_train_dissimilarity.py index f10be8bb9..bb23bd242 100644 --- a/elephant/spike_train_dissimilarity.py +++ b/elephant/spike_train_dissimilarity.py @@ -21,20 +21,13 @@ import elephant.kernels as kernels from neo.core import SpikeTrain -# Problem of conversion from Python 2 to Python 3: -# 'xrange' in Python 2 is 'range' in Python 3. -try: - xrange -except NameError: - xrange = range - def _create_matrix_from_indexed_function( shape, func, symmetric_2d=False, **func_params): mat = np.empty(shape) if symmetric_2d: - for i in xrange(shape[0]): - for j in xrange(i, shape[1]): + for i in range(shape[0]): + for j in range(i, shape[1]): mat[i, j] = mat[j, i] = func(i, j, **func_params) else: for idx in np.ndindex(*shape): @@ -99,18 +92,19 @@ def victor_purpura_dist( Returns ------- - 2-D array - Matrix containing the VP distance of all pairs of spike trains. - - Example - ------- - import elephant.spike_train_dissimilarity_measures as stdm - q = 1.0 / (10.0 * pq.ms) - st_a = SpikeTrain([10, 20, 30], units='ms', t_stop= 1000.0) - st_b = SpikeTrain([12, 24, 30], units='ms', t_stop= 1000.0) - vp_f = stdm.victor_purpura_dist([st_a, st_b], q)[0, 1] - vp_i = stdm.victor_purpura_dist( - [st_a, st_b], q, algorithm='intuitive')[0, 1] + np.ndarray + 2-D Matrix containing the VP distance of all pairs of spike trains. + + Examples + -------- + >>> import quantities as pq + >>> from elephant.spike_train_dissimilarity import victor_purpura_dist + >>> q = 1.0 / (10.0 * pq.ms) + >>> st_a = SpikeTrain([10, 20, 30], units='ms', t_stop= 1000.0) + >>> st_b = SpikeTrain([12, 24, 30], units='ms', t_stop= 1000.0) + >>> vp_f = victor_purpura_dist([st_a, st_b], q)[0, 1] + >>> vp_i = victor_purpura_dist([st_a, st_b], q, + ... algorithm='intuitive')[0, 1] """ for train in trains: if not (isinstance(train, (pq.quantity.Quantity, SpikeTrain)) and @@ -199,7 +193,7 @@ def _victor_purpura_dist_for_st_pair_fast(train_a, train_b, kernel): Returns ------- - float + float The Victor-Purpura distance of train_a and train_b """ @@ -218,7 +212,7 @@ def _victor_purpura_dist_for_st_pair_fast(train_a, train_b, kernel): ((np.sqrt(6.0) * kernel.sigma) * kern).simplified) k = 1 - 2 * as_fortran - for i in xrange(min_dim): + for i in range(min_dim): # determine G[i, i] == accumulated_min[:, 0] accumulated_min = cost[:, :-i - 1] + k[i:, i] accumulated_min[1, :train_b.size - i] = \ @@ -268,18 +262,18 @@ def _victor_purpura_dist_for_st_pair_intuitive( Returns ------- - float + float The Victor-Purpura distance of train_a and train_b """ nspk_a = len(train_a) nspk_b = len(train_b) scr = np.zeros((nspk_a+1, nspk_b+1)) - scr[:, 0] = xrange(0, nspk_a+1) - scr[0, :] = xrange(0, nspk_b+1) + scr[:, 0] = range(0, nspk_a+1) + scr[0, :] = range(0, nspk_b+1) if nspk_a > 0 and nspk_b > 0: - for i in xrange(1, nspk_a+1): - for j in xrange(1, nspk_b+1): + for i in range(1, nspk_a+1): + for j in range(1, nspk_b+1): scr[i, j] = min(scr[i-1, j]+1, scr[i, j-1]+1) scr[i, j] = min(scr[i, j], scr[i-1, j-1] + np.float64(( q*abs(train_a[i-1]-train_b[j-1])).simplified)) @@ -319,17 +313,17 @@ def van_rossum_dist(trains, tau=1.0 * pq.s, sort=True): Returns ------- - 2-D array - Matrix containing the van Rossum distances for all pairs of + np.ndarray + 2-D Matrix containing the van Rossum distances for all pairs of spike trains. - Example - ------- - import elephant.spike_train_dissimilarity_measures as stdm - tau = 10.0 * pq.ms - st_a = SpikeTrain([10, 20, 30], units='ms', t_stop= 1000.0) - st_b = SpikeTrain([12, 24, 30], units='ms', t_stop= 1000.0) - vr = stdm.van_rossum_dist([st_a, st_b], tau)[0, 1] + Examples + -------- + >>> from elephant.spike_train_dissimilarity import van_rossum_dist + >>> tau = 10.0 * pq.ms + >>> st_a = SpikeTrain([10, 20, 30], units='ms', t_stop= 1000.0) + >>> st_b = SpikeTrain([12, 24, 30], units='ms', t_stop= 1000.0) + >>> vr = van_rossum_dist([st_a, st_b], tau)[0, 1] """ for train in trains: if not (isinstance(train, (pq.quantity.Quantity, SpikeTrain)) and @@ -386,9 +380,9 @@ def _summed_dist_matrix(spiketrains, tau, presorted=False): exp_diffs = np.exp(values[:, :-1] - values[:, 1:]) markage = np.zeros(values.shape) - for u in xrange(len(spiketrains)): + for u in range(len(spiketrains)): markage[u, 0] = 0 - for i in xrange(sizes[u] - 1): + for i in range(sizes[u] - 1): markage[u, i + 1] = (markage[u, i] + 1.0) * exp_diffs[u, i] # Same spiketrain terms @@ -396,9 +390,9 @@ def _summed_dist_matrix(spiketrains, tau, presorted=False): D[np.diag_indices_from(D)] = sizes + 2.0 * np.sum(markage, axis=1) # Cross spiketrain terms - for u in xrange(D.shape[0]): + for u in range(D.shape[0]): all_ks = np.searchsorted(values[u], values, 'left') - 1 - for v in xrange(u): + for v in range(u): js = np.searchsorted(values[v], values[u], 'right') - 1 ks = all_ks[v] slice_j = np.s_[np.searchsorted(js, 0):sizes[u]] diff --git a/elephant/sta.py b/elephant/sta.py index 38079b5f7..58f292efa 100644 --- a/elephant/sta.py +++ b/elephant/sta.py @@ -204,10 +204,8 @@ def spike_field_coherence(signal, spiketrain, **kwargs): spiketrain : SpikeTrain or BinnedSpikeTrain Single spike train to perform the analysis on. The binsize of the binned spike train must match the sampling_rate of signal. - - KWArgs - ------ - All KWArgs are passed to scipy.signal.coherence(). + **kwargs: + All kwargs are passed to `scipy.signal.coherence()`. Returns ------- @@ -219,8 +217,8 @@ def spike_field_coherence(signal, spiketrain, **kwargs): contains the frequency values corresponding to the first dimension of the 'coherence' array - Example - ------- + Examples + -------- Plot the SFC between a regular spike train at 20 Hz, and two sinusoidal time series at 20 Hz and 23 Hz, respectively. diff --git a/elephant/statistics.py b/elephant/statistics.py index 56d28fd44..e569cd0e6 100644 --- a/elephant/statistics.py +++ b/elephant/statistics.py @@ -24,7 +24,7 @@ ~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: statistics/ + :toctree: toctree/statistics/ mean_firing_rate instantaneous_rate @@ -36,7 +36,7 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: statistics/ + :toctree: toctree/statistics/ isi cv @@ -48,7 +48,7 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: - :toctree: statistics/ + :toctree: toctree/statistics/ fanofactor complexity_pdf diff --git a/elephant/unitary_event_analysis.py b/elephant/unitary_event_analysis.py index 91a50d0b8..320acb7a7 100644 --- a/elephant/unitary_event_analysis.py +++ b/elephant/unitary_event_analysis.py @@ -43,7 +43,7 @@ ------------------ .. autosummary:: - :toctree: unitary_event_analysis/ + :toctree: toctree/unitary_event_analysis/ jointJ_window_analysis