README.md 4.19 KB
Newer Older
Sebastian Heimann's avatar
Sebastian Heimann committed
1
2
3
4
# Lassie

*A friendly earthquake detector.*

Sebastian Heimann's avatar
Sebastian Heimann committed
5
6
7
8
9
## Installation

First, install [Pyrocko](http://emolch.github.io/pyrocko/v0.3/install.html),
then install Lassie:

10
```bash
Sebastian Heimann's avatar
Sebastian Heimann committed
11
12
13
14
15
git clone https://gitext.gfz-potsdam.de/heimann/lassie.git
cd lassie
sudo python setup.py install
```

Sebastian Heimann's avatar
Sebastian Heimann committed
16
17
18
## Tutorial: detecting events in a regional network

This tutorial explains how to use Lassie to detect events in a regional
19
20
21
network. The one-day test dataset from the Alentejo region in South Portugal
can be downloaded from
http://kinherd.org/lassie-example-alentejo.tar (235 MB). Data from 12 seismic
Sebastian Heimann's avatar
Sebastian Heimann committed
22
23
stations from the
[DOCTAR](http://www.geo.uni-potsdam.de/doctar-1317/articles/doctar-1317.html)
24
25
26
experiment and from 5 permanent stations from regional networks [REFERENCE] are
included. A region of roughly 100 x 100 km is covered by the available data.

27
#### Dataset preparation
28
29
30
31
32
33

```bash
# download data and unpack
wget http://kinherd.org/lassie-example-alentejo.tar
tar -xf lassie-example-alentejo.tar
cd lassie-example-alentejo
Sebastian Heimann's avatar
Sebastian Heimann committed
34
ls
35
# data/                 - raw waveforms in mseed format
Sebastian Heimann's avatar
Sebastian Heimann committed
36
37
38
39
40
41
42
43
44
45
# stations.txt          - text file with station coordinates
# confirmed-events.txt  - catalog with some known events
```

To get a quick overview on the dataset, use the 
[Snuffler](http://emolch.github.io/pyrocko/v0.3/snuffler_tutorial.html) 
application which is part of [Pyrocko](http://emolch.github.io/pyrocko/).

```bash
snuffler --stations=stations.txt --events=confirmed-events.txt data/
46
```
Sebastian Heimann's avatar
Sebastian Heimann committed
47

Sebastian Heimann's avatar
Sebastian Heimann committed
48
#### Hints, when preparing your own dataset:
49
50
51
52
53
54
55

* NET.STA.LOC codes in waveform files must match exactly what is given in the
  stations file.
* Waveform files and directory layout do not have to follow any specific
  convention, but with large files, data access can become less efficient. As a
  rule of thumb, use files smaller than 1MB each. To cut a dataset into a new
  chunksize, use the Jackseis program which is part of
Sebastian Heimann's avatar
Sebastian Heimann committed
56
57
  [Pyrocko](http://emolch.github.io/pyrocko/), e.g. to cut a whole dataset into
  hour files use: `jackseis INPUT_DIR --tinc=3600 --output-dir=OUTPUT_DIR`
58
59
60
61
62
63
64
65
66
67
68
69
70

#### Lassie configuration

Lassie reads its configuration from a text file in the
[YAML](https://en.wikipedia.org/wiki/YAML) format. To create an initial
configuration, run

```bash
lassie init > config.lassie
# or filling in already the names of the stations file and the waveform directory:
lassie init --stations=stations.txt data > config.lassie
```

Sebastian Heimann's avatar
Sebastian Heimann committed
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
```yaml
%YAML 1.1
--- !lassie.Config

## Configuration file for Lassie, your friendly earthquake detector
## 
## Receiver coordinates can be read from a stations file in Pyrocko format:
stations_path: 'stations.txt'

## Receivers can also be listed in the config file, lat/lon and carthesian 
## (x/y/z) = (North/East/Down) coordinates are supported and may be combined 
## (interpreted as reference + offset). Omitted values are treated as zero.
# receivers:
# - !lassie.Receiver
#   codes: ['', 'ACC13', '']
#   lat: 10.
#   lon: 12.
#   x: 2397.56
#   y: 7331.94
#   z: -404.1

## List of data directories. Lassie will recurse into subdirectories to find
## all contained waveform files.
data_paths:
- 'data'

## Processing time interval (default: use time interval of available data)
# tmin: '2012-02-06 04:20:00'
# tmax: '2012-02-06 04:30:00'

## Search grid; if not given here (if commented), a default grid will be chosen
# grid: !lassie.Carthesian3DGrid
#   lat: 38.7
#   lon: -7.9
#   xmin: -70e3  # in [m]
#   xmax: 70e3
#   ymin: -70e3
#   ymax: 70e3
#   zmin: 0.0
#   zmax: 0.0
#   dx: 2.5e3
#   dy: 2.5e3
#   dz: 2.5e3

## Size factor to use when automatically choosing a grid size
autogrid_radius_factor: 1.5

## Grid density factor used when automatically choosing a grid
autogrid_density_factor: 10.0

## Image function contributions
ifcs:
- !lassie.WavePacketIFC
  name: 'P'
  weight: 1.0
  fmin: 1.0
  fmax: 15.0
  fsmooth_factor: 0.1
  shifter: !lassie.VelocityShifter
    velocity: 3500.
- !lassie.WavePacketIFC
  name: 'S'
  weight: 1.0
  fmin: 1.0
  fmax: 10.0
  fsmooth_factor: 0.1
  shifter: !lassie.VelocityShifter
    velocity: 2500.

## Whether to divide image function frames by their mean value
sharpness_normalization: true

## Threshold on detector function
detector_threshold: 100.0

## Output filename for detections
detections_path: 'detections.txt'
```