From 7c19249976bb41bb0c836d959986177fcd06135e Mon Sep 17 00:00:00 2001 From: Calum Chamberlain Date: Sun, 19 Aug 2018 22:40:35 +0000 Subject: [PATCH] Update docs --- eqcorrscan/doc/intro.rst | 80 ++++++++++++-------------------------- eqcorrscan/doc/updates.rst | 2 + 2 files changed, 27 insertions(+), 55 deletions(-) diff --git a/eqcorrscan/doc/intro.rst b/eqcorrscan/doc/intro.rst index cc230bd75..1c4d1a050 100644 --- a/eqcorrscan/doc/intro.rst +++ b/eqcorrscan/doc/intro.rst @@ -10,34 +10,23 @@ EQcorrscan is designed to compute detections of earthquakes, or any seismic sign (explosions work *really* well) using more advanced routines than standard amplitude-ratio methods. -This package was originally based around a matched-filter detection routine -which works by comparing templates with continuous data. -The main benefit of EQcorrscan's matched-filter routine is the level of parallel -processing that can be achieved. EQcorrscan will run on anything from a 1GB RAM -single-board computer to a multi-hundred-GB RAM, thousand CPU high-performance -computer. Because the internals of EQcorrscan's matched-filter routine scale -reasonably well, the developers have observed speed-ups of 150x (from 2 months -to 10 hours) by migrating from a small cluster -to a large one (for a 6.5 year long continuous dataset and 800 templates). - The authors of EQcorrscan foresee this project as an open repository for the development of software for the detection and analysis of repeating and near-repeating earthquakes. This repository will continue to grow and develop and any and all help/criticism will be appreciated. There are a lot of things that could be added to this project - if you want to -get involved the best place to start, and the most valuable thing for your -understanding, and for the health of this package would be to contribute tests and +get involved a good place to start would be to contribute tests and documentation. -Installation - Updated for version 0.2.7 ----------------------------------------- +Installation - Updated for versions > 0.2.7 +------------------------------------------- Recommended install method ~~~~~~~~~~~~~~~~~~~~~~~~~~ In general we recommend users to install EQcorrscan in a virtual environment, -|conda| will simplify your install greatly (install instuction for anaconda +|conda| will simplify your install greatly (install instructions for anaconda or miniconda are here: |conda-install|) - we recommend creating a conda environment with the following: @@ -56,13 +45,13 @@ To then install EQcorrscan you can simply run: conda install eqcorrscan -Not-recomended but workable methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Not-recommended but workable methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are a myriad of other ways to install EQcorrscan and it's dependancies, +There are other ways to install EQcorrscan and it's dependencies, some details for some of those cases can be found :doc:`here`. We do note that the other methods are more involved, and can be problematic. If -you do chose not to use conda then you should definitely test your install. +you do chose not to use conda then you should definitely test your install (see below). .. |conda| raw:: html @@ -99,53 +88,34 @@ you do chose not to use conda then you should definitely test your install. Supported environments ---------------------- -We support Linux, OSX and Windows environments running Python 2.7, 3.4 and 3.5. -We don't run our tests on other versions of Python so you might have some issues -with other Python 3.x series, if you do, let us know. +We support Linux, OSX and Windows environments running Python 2.7 and 3.x. We do **not** support Python 2.6. +We will stop support for Python 2.7 in a forthcoming release, for more information +see |#242|. -Functions ---------- - -This package is divided into sub-directories of :doc:`core ` and :doc:`utils `. The -:doc:`utils ` directory contains simple functions for integration with |seisan_link|, -these are in the :doc:`sfile_util ` -module and functions therein which are essentially barebones and do not have the -full functionality that seisan can handle. :doc:`utils ` also contains a simple -peak-finding algorithm :doc:`findpeaks ` which looks for peaks within noisy data -above a certain threshold and within windows. - -Many other functions have been -added to this module to handle the analysis of repeating and near-repeating -earthquakes, including stacking routines, clustering algorithms, magnitude -calculation both by amplitude picking and by singular value decomposition. I -recommend you take a look in here to see if any of it is useful. There are also -some plotting routines that make handling large datasets a little simpler. Most -recently I have added a simple synthetic seismogram generator, which is currently -my main project focus. +.. |#242| raw:: html -.. |seisan_link| raw:: html + issue #242 - Seisan -Since earlier versions the :doc:`core ` modules have moved away from using parameter -files, and instead rely on explicit argument calls. The parameter files are -still included by not documented here (see inside the par files), and remain -useful when generating batch scripts (see the scripts in the github repo). +Functionality +------------- Within :doc:`core ` you will find the core routines to generate templates, (:doc:`template_gen `) search for likely templates -(:doc:`bright_lights `) and -compute cross-channel correlations from these templates (:doc:`match_filter `). The -bright_lights and match_filter submodules have been designed with parallel +(:doc:`bright_lights `), +compute cross-channel correlations from these templates +(:doc:`match_filter `), generate cross-correlation +corrected pick-times (:doc:`lag_calc `), +and run subspace detection (:doc:`subspace `). + +The bright_lights and match_filter submodules have been designed with parallel computing in mind, to the extent that the more cores and machines you have -running them the better. These rely on the python multiprocessing module to -handle parallelisation at lower-levels. You can also do some 'brute-force' -parallelisation on a day level when computing detections over multiple days. -I tend to run one day per node of a cluster computer, with each day running -templates in parallel. +running them (generally) the better. These rely on the python multiprocessing +module, and some C extensions using openMP to handle parallelisation at +lower-levels. .. _RunningTests: diff --git a/eqcorrscan/doc/updates.rst b/eqcorrscan/doc/updates.rst index a8b3392a7..07cb7a2ce 100644 --- a/eqcorrscan/doc/updates.rst +++ b/eqcorrscan/doc/updates.rst @@ -40,6 +40,7 @@ Version 0.3.2 trends - variance threshold is now raised, and Python checks for low-variance and applies gain to stabilise correlations if needed. * Plotting functions are now tested and have a more consistent interface: + * All plotting functions accept the keyword arguments `save`, `savefile`, `show`, `return_figure` and `title`. * All plotting functions return a figure. @@ -51,6 +52,7 @@ Version 0.3.2 one sample too long resulting in minor differences in data processing (due to difference in FFT length) and therefore minor differences in resulting correlations (~0.07 per channel). + * Includes extra stability check in fftw_normxcorr which affects the last sample before a gap when that sample is near-zero. * BUG-FIX: fftw correlation dot product was not thread-safe on some systems.