Update docs

JuliaSeismo · Jun 28, 2019 · 78dc5f6 · 78dc5f6
1 parent e3510c9
commit 78dc5f6
Show file tree

Hide file tree

Showing 7 changed files with 185 additions and 15 deletions.
diff --git a/docs/src/Types/corrdata.md b/docs/src/Types/corrdata.md
@@ -1,11 +1,11 @@
 `CorrData` - Objects for ambient noise cross-correlations.
 
-`Noise` uses a custom structure `CorrData` for holding cross-correlations. To create
+`SeisNoise` uses a custom structure `CorrData` for holding cross-correlations. To create
 an empty `CorrData` object, use the `CorrData()` function. `CorrData` are created
 with the `compute_cc` function.
 
 ```julia
-julia> using Noise
+julia> using SeisNoise
 julia> CorrData()
 CorrData with 0 Corrs
       NAME: …
@@ -91,7 +91,7 @@ julia> C.corr
 ```
 !!! note
 
-      By convention in Julia, data are stored *column-wise*. Here, `C` contains 188 individual correlations. 
+      By convention in Julia, data are stored *column-wise*. Here, `C` contains 188 individual correlations.
 
 ```@docs
 CorrData

diff --git a/docs/src/Types/fftdata.md b/docs/src/Types/fftdata.md
@@ -1,12 +1,12 @@
 `FFTData` - Objects for holding Fourier transforms (FFTs)
 
-`Noise` is designed around array-based cross-correlation. `Noise` uses a custom
+`SeisNoise` is designed around array-based cross-correlation. `SeisNoise` uses a custom
 structure `FFTData` for holding Fourier transforms of ambient noise. To create
 an empty `FFTData` object, use the `FFTData()` function. `FFTData` are created
 with the `compute_fft` function.
 
 ```julia
-julia> using Noise
+julia> using SeisNoise
 julia> FFTData()
 FFTData with 0 ffts
       NAME: …

diff --git a/docs/src/fft.md b/docs/src/fft.md
@@ -1,8 +1,123 @@
 # `Computing FFTs` - methods for computing FFTs raw noise data.
 
+All correlation in SeisNoise.jl is done in the frequency domain, which can be represented
+by:
+
+```math
+C_{AB}(ω) = u_A(ω) u^∗_B(ω)
+```
+
+Where ``u_A(ω)`` is the Fourier transform of ambient noise time series ``A``,
+``u^*_B(ω)`` is the complex conjugate of the Fourier transform of ambient noise
+time series ``B``, and ``C_{AB}(ω)`` is the cross-correlation of ``A`` and ``B``
+in the frequency domain. For time and memory efficiency, the real Fourier transform
+(`rfft`) is used as opposed to the regular Fourier transform (`fft`). This gives
+a speedup of about a factor of 3. A typical workflow for computing `fft`'s can include:
+
+- Spectral whitening (removing spectral amplitude information)
+- One-bit normalization
+- Phase normalization
+
+## Computing FFTs
+
+The `compute_fft` function provides the typical workflow for computing `fft`s.
+
+```julia
+julia> using SeisNoise, SeisIO
+julia> S = get_data("IRIS","TA.V04C..BHZ",s="2006-02-01T00:00:00",t="2006-02-01T01:00:00")
+julia> freqmin, freqmax = 1.,10.
+julia> fs = 20.
+julia> cc_step, cc_len = 100, 100
+julia> F = compute_fft(S,freqmin,freqmax,fs,cc_step,cc_len,time_norm=false,
+                       to_whiten=false)
+
+FFTData with 36 ffts
+      NAME: "TA.V04C..BHZ"                     
+        ID: "2006-02-01"                       
+       LOC: 0.0 N, 0.0 E, 0.0 m
+        FS: 20.0
+      GAIN: 1.0
+   FREQMIN: 0.05
+   FREQMAX: 5.0
+    CC_LEN: 100                                
+   CC_STEP: 100                                
+  WHITENED: false                              
+ TIME_NORM: false                              
+      RESP: c = 0.0, 0 zeros, 0 poles
+      MISC: 0 entries                          
+     NOTES: 2 entries                          
+         T: 2006-02-01T00:00:00.000            …
+       FFT: 1001×36 Array{Complex{Float32},2}  
+```
+
+Underneath the hood, `compute_fft` applies pre-processing with `merge`, `ungap`,
+and `process_raw`. The `SeisData` object is then transformed into an Array `A` of
+sliding windows. The `process_fft` then applies spectral or time-domain normalization
+and returns `FFT`, the Fourier transform of `A`. An `FFTData` object is then created
+from the parameters of `S` and `FFT`.
+
+```julia                        
+merge!(S)
+ungap!(S)
+process_raw!(S,fs)
+A, starts, ends = slide(S[1], cc_len, cc_step)
+FFT = process_fft(A, freqmin, freqmax, fs, time_norm=time_norm,to_whiten=to_whiten)
+F = FFTData(S[1].id, Dates.format(u2d(starts[1]),"Y-mm-dd"),
+                       S[1].loc, S[1].fs, S[1].gain, freqmin, freqmax,
+                       cc_len, cc_step, to_whiten, time_norm, S[1].resp,
+                       S[1].misc, S[1].notes, starts, FFT)
+```
+
+## Saving/Loading FFTs
+
+`FFTData` objects can be saved to disk in the native Julia [JLD2](https://github.com/JuliaIO/JLD2.jl)
+format using the `save_fft` function.
+
+```julia
+julia> OUTDIR = "~/TEST/FFT/"
+julia> save_fft(F,OUTDIR)
+```
+
+`FFTData` are stored in groups by channel (e.g. BHZ or HHZ), then by date
+(in yyyy-mm-dd format) in JLD2. By default, JLD2 files are saved to
+/PATH/TO/OUTDIR/NET.STA,CHAN.jld2. 
+
+```julia
+file = jldopen("~/TEST/FFT/TA.V04C.BHZ.jld2","r")
+JLDFile ~TEST/FFT/TA.V04C.BHZ.jld2 (read-only)
+ └─📂 BHZ
+    └─🔢 2006-02-01
+```
+
+To read an `FFTData` on disk, use the `load_fft` function:
+
+```julia
+julia> F = load_fft("~/TEST/FFT/TA.V04C.BHZ.jld2","BHZ")
+FFTData with 36 ffts
+      NAME: "TA.V04C..BHZ"                     
+        ID: "2006-02-01"                       
+       LOC: 0.0 N, 0.0 E, 0.0 m
+        FS: 20.0
+      GAIN: 1.0
+   FREQMIN: 0.05
+   FREQMAX: 5.0
+    CC_LEN: 100                                
+   CC_STEP: 100                                
+  WHITENED: false                              
+ TIME_NORM: false                              
+      RESP: c = 0.0, 0 zeros, 0 poles
+      MISC: 0 entries                          
+     NOTES: 2 entries                          
+         T: 2006-02-01T00:00:00.000            …
+       FFT: 1001×36 Array{Complex{Float32},2}
+```
+
+Note that it is necessary to specify the channel when using `load_fft`.
+
 ```@docs
 whiten
 process_fft
 compute_fft
 save_fft
+load_fft
 ```
diff --git a/docs/src/filter.md b/docs/src/filter.md
@@ -1,5 +1,61 @@
 # `Filters` - methods for filtering `SeisData` and `SeisChannel` objects.
 
+SeisNoise.jl provides `bandpass`, `bandstop`, `lowpass` and `highpass` filters built from
+[DSP.jl](https://github.com/JuliaDSP/DSP.jl). Due to [multiple dispatch](https://en.wikipedia.org/wiki/Multiple_dispatch) in Julia, filter functions in SeisNoise.jl work on either the data in `SeisChannel` or `SeisData` objects or directly with Julia `Array`s. SeisNoise.jl uses Butterworth filters with a default of 4 corners.
+
+## Filtering a SeisChannel or SeisData
+```julia
+julia> freqmin, freqmax = 1., 10. # low and high frequencies in Hz
+julia> corners = 4 # number of corners in Butterworth filter
+julia> zerophase = true # if true, apply filter twice for no phase shifting
+julia> S = get_data("IRIS","TA.V04C..BHZ",s="2006-02-01T00:00:00",t="2006-02-01T01:00:00")
+julia> SeisIO.demean!(S) # remove mean
+julia> SeisIO.detrend!(S) # remove linear trend
+julia> SeisIO.taper!(S) # taper - defaults to 5% taper on either side of the trace
+julia> bandpass(S,freqmin,freqmax,corners=corners,zerophase=zerophase)
+```
+
+### Nyquist Frequency
+Filtering above the Nyquist frequency will give a warning, if using a `lowpass`
+or `bandpass` filter, while using a `highpass` above the Nyquist frequency will throw an
+error.
+
+```julia
+julia> S[1].fs / 2. # Nyquist frequency is half sampling rate
+20.
+julia> freqmax = S[1].fs / 2. + 5.
+25.  
+julia> bandpass(S,freqmin,freqmax,corners=corners,zerophase=zerophase)
+┌ Warning: Selected high corner frequency (25.0) of bandpass is at or
+│        above Nyquist (20.0). Applying a high-pass instead.
+└
+julia> lowpass(S,freqmax,corners=corners,zerophase=zerophase)
+┌ Warning: Selected corner frequency (25.0) is
+│ above Nyquist (20.0). Setting Nyquist as high corner.
+└
+julia> highpass(S,freqmax,corners=corners,zerophase=zerophase)
+ERROR: frequencies must be less than the Nyquist frequency 20.0
+```
+
+## Filtering Arrays
+
+Filtering arrays works much the same as filtering `SeisData` or `SeisChannel` objects.
+The only additional variable required is the sampling rate `fs` of the data in the
+array.
+
+```julia
+julia> cc_step, cc_len = 100, 100 # step and length of slices
+julia> A, starts, ends = slide(S[1], cc_len, cc_step) # create sliding array
+julia> fs = S[1].fs # get sampling rate
+julia> demean!(A) # remove mean
+julia> detrend!(A) # remove linear trend
+julia> taper!(A,fs) # taper - defaults to 5% taper on either side of the trace
+julia> bandpass(A,freqmin,freqmax,fs,corners=corners,zerophase=zerophase)
+```
+
+
+
+
 ```@docs
 bandpass!
 bandstop!

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,25 +1,25 @@
-# Noise.jl
+# SeisNoise.jl
 
 *Ambient Noise Cross-Correlation in Julia.*
 
-Noise.jl provides routines for quickly and efficiently implementing [seismic interferometry](https://en.wikipedia.org/wiki/Seismic_interferometry).
+SeisNoise.jl provides routines for quickly and efficiently implementing [seismic interferometry](https://en.wikipedia.org/wiki/Seismic_interferometry).
 
 !!! note
 
-    Much of the I/O and preprocessing in Noise.jl uses the [SeisIO.jl](https://github.com/jpjones76/SeisIO.jl) package. Please read through the [SeisIO Documentation](https://seisio.readthedocs.io/en/latest/) to get familiar with seismic data processing in Julia.
+    Much of the I/O and preprocessing in SeisNoise.jl uses the [SeisIO.jl](https://github.com/jpjones76/SeisIO.jl) package. Please read through the [SeisIO Documentation](https://seisio.readthedocs.io/en/latest/) to get familiar with seismic data processing in Julia.
 
 ## Installation
 From the Julia command prompt:
 1. Press `]` to enter `pkg`.
-2. Type or copy: `add https://github.com/tclements/Noise.jl; build; precompile`
+2. Type or copy: `add https://github.com/tclements/SeisNoise.jl; build; precompile`
 3. Press backspace to exit `pkg`.
-4. Type or copy: `using Noise`
+4. Type or copy: `using SeisNoise`
 
-## Using Noise.jl
+## Using SeisNoise.jl
 
-Noise.jl was designed to be as easy to use in the REPL as on an HPC cluster. If
+SeisNoise.jl was designed to be as easy to use in the REPL as on an HPC cluster. If
 you want to get started processing data, head over to the tutorial or parallel example.
 This documentation provides a reference to all the underlying function for cross-correlation.
-We encourage you to develop your own workflow using Noise's core functionality.
+We encourage you to develop your own workflow using SeisNoise's core functionality.
 
 ![plot1](assets/CI-moveout.png)
diff --git a/docs/src/postprocessing.md b/docs/src/postprocessing.md
@@ -1,7 +1,6 @@
 # `Post-Processing` - methods for working with correlation data.
 
 ```@docs
-stack!
 mwcs
 mwcs_dvv
 stretching

diff --git a/docs/src/preprocessing.md b/docs/src/preprocessing.md
@@ -16,7 +16,7 @@ Here is an example workflow:
 Data can be downloaded using `SeisIO`'s `get_data` function.
 
 ```julia
-julia> using SeisIO, Noise
+julia> using SeisIO, SeisNoise
 julia> S = get_data("IRIS","TA.V04C..BHZ",s="2006-02-01",t="2006-02-02")
 SeisData with 1 channels (1 shown)
     ID: TA.V04C..BHZ