README.rst 7.83 KB
Newer Older
Javier Quinteros's avatar
Javier Quinteros committed
1 2
dasscripts
==========
Javier Quinteros's avatar
Javier Quinteros committed
3

4 5
.. image:: https://img.shields.io/pypi/v/dasscripts.svg
   :target: https://img.shields.io/pypi/v/dasscripts.svg
Javier Quinteros's avatar
Javier Quinteros committed
6

7 8
.. image:: https://img.shields.io/pypi/pyversions/dasscripts.svg
   :target: https://img.shields.io/pypi/pyversions/dasscripts.svg
Javier Quinteros's avatar
Javier Quinteros committed
9

10 11
.. image:: https://img.shields.io/pypi/format/dasscripts.svg
   :target: https://img.shields.io/pypi/format/dasscripts.svg
Javier Quinteros's avatar
Javier Quinteros committed
12

13 14
.. image:: https://img.shields.io/pypi/status/dasscripts.svg
   :target: https://img.shields.io/pypi/status/dasscripts.svg
Javier Quinteros's avatar
Javier Quinteros committed
15 16 17 18 19

Scripts to work with data generated by DAS systems.

Overview
--------
20 21
This package provides a set of scripts to read, manipulate and convert seismic waveforms
generated by DAS systems. In particular, the ones saved in TDMs format.
Javier Quinteros's avatar
Javier Quinteros committed
22

Javier Quinteros's avatar
Javier Quinteros committed
23
dasconv
24
-------
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
This utility lets you convert and manipulate seismic waveforms in TDMs format and export them into MiniSEED.

Data acquired from experiments with DAS systems are usually stored in one folder. Files within this folder have names
indicating the experiment and the start time of the waveforms saved. An example of the files generated in a test
experiment is shown below. ::

    $ ls -l
    total 1577352
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:38 default_UTC_20190508_093735.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:38 default_UTC_20190508_093805.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:39 default_UTC_20190508_093835.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:39 default_UTC_20190508_093905.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:40 default_UTC_20190508_093935.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:40 default_UTC_20190508_094005.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:41 default_UTC_20190508_094035.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:41 default_UTC_20190508_094105.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:42 default_UTC_20190508_094135.409.tdms

There, *default* is the name of the experiment and the rest is the start time with the following format:
*experiment_TZ_YYYYMMDD_HHmmss.fff.tdms*.

Javier Quinteros's avatar
Javier Quinteros committed
46
``dasconv`` provides also a TDMS class which needs to receive one mandatory parameter to be instantiated,
47 48
*filename*, which is actually the experiment name and how all file names in the containing folder start with.
A detailed explanation on how to use it on your own programs can be found in the documentation.
49

Javier Quinteros's avatar
Javier Quinteros committed
50
A typical help message from ``dasconv`` looks like the following: ::
51

Javier Quinteros's avatar
Javier Quinteros committed
52 53
    usage: dasconv [-h] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-d DIRECTORY]
                   [--start START] [--end END] [--chstart CHSTART]
54 55
                   [--chstop CHSTOP] [--chstep CHSTEP] [--decimate {1,5}]
                   [--metadata] [-V]
Javier Quinteros's avatar
Javier Quinteros committed
56
                   filename
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78

    Read, manipulate and convert seismic waveforms generated by a DAS system.

    positional arguments:
      filename              Experiment to read and process. It is usually the
                            first part of the filenames.

    optional arguments:
      -h, --help            show this help message and exit
      -l {CRITICAL,ERROR,WARNING,INFO,DEBUG}, --loglevel {CRITICAL,ERROR,WARNING,INFO,DEBUG}
                            Verbosity in the output.
      -d DIRECTORY, --directory DIRECTORY
                            Directory where files are located.
      --start START, --starttime START
                            Start of the selected time window. Format:
                            2019-02-01T00:01:02.123456Z
      --end END, --endtime END
                            End of the selected time window. Format:
                            2019-02-01T00:01:02.123456Z
      --chstart CHSTART     First channel to export
      --chstop CHSTOP       Last channel to export
      --chstep CHSTEP       Step between channels in the selection
79
      --decimate {1,5}      Factor by which the sampling rate is lowered by
80
                            decimation.
81
      --metadata            Read and display the metadata from the TDMS files
82
      -V, --version         show program's version number and exit
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100


Examples
========

Export waveforms from channels 800, 802 and 804 starting at 2019-05-08T09:37:35.409000 until 2019-05-08T09:38:05.400000.
The waveforms will be exported to MiniSEED format after being decimated by a factor of 5 (e.g. from 1000Hz to 200Hz). ::

    dasconv -d /home/user/test/ --start "2019-05-08T09:37:35.409000" --end "2019-05-08T09:38:05.400000" default --chstart 800 --chstop 805 --chstep 2

Export waveforms from channels 0 and 1 from the beginning of the measurements until 2019-05-08T09:32:15.
The waveforms will be exported to MiniSEED format after being decimated by a factor of 5 (e.g. from 1000Hz to 200Hz). ::

    dasconv -d /home/user/test/ --endtime "2019-05-08T09:32:15" default --chstart 0 --chstop 1

Export waveforms from channels 0 to 4 from the beginning of the measurements until 2019-05-08T09:32:15.
The waveforms will be exported to MiniSEED format after being decimated by a factor of 5 (e.g. from 1000Hz to 200Hz). ::

101
    dasconv -d /home/user/test/ --endtime "2019-05-08T09:32:15" default --chstart 0 --chstop 4 --decimate 5
102 103 104 105 106 107

tdmsws (experimental)
---------------------
tdmsws is a stand-alone implementation of the FDSN Dataselect web service, which is able to serve miniSEED data extracted
from a folder with TDMS files.

Javier Quinteros's avatar
Javier Quinteros committed
108
A typical help message from ``tdmsws`` looks like the following: ::
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 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

    % tdmsws -h
    usage: tdmsws [-h] [-mc] [-l {DEBUG,WARNING,INFO,DEBUG}]

    tdmsws is an FDSN Dataselect implementation to read TDMS files

    optional arguments:
      -h, --help            show this help message and exit
      -mc, --minimalconfig  Generate a minimal configuration file.
      -l {DEBUG,WARNING,INFO,DEBUG}, --log {DEBUG,WARNING,INFO,DEBUG}
                            Increase the verbosity level.


The "mc" switch creates a config file, which should be placed in the same folder as the TDMS files. The file includes
all needed options and configuration variables which will be read by the software before being able to serve the data.
The user is expected to edit this file and provide the basic information about the DAS experiment before running the
service.

One can see below a typical config file. ::

    [General]
    experiment = default
    loglevel = INFO

    [NSLC]
    network = XX
    location =
    channel = FH1

The "experiment" variable refers to the first part of the filenames in the folder. For instance, in the example above
all files will start with "default" and then a timestamp including the timezone (or UTC) will follow. ::

    $ ls -l
    total 1577352
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:38 default_UTC_20190508_093735.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:38 default_UTC_20190508_093805.409.tdms
    -rwxrwxrwx  1 user  staff   49965056 May  8 09:39 default_UTC_20190508_093835.409.tdms

The variables "network", "location" and "channel" will be fixed to define the N.S.L.C code. Only the station will vary
and it will always be a number referring to the stream number for the experiment. From the example above, the only valid
code would be "XX.00001..FH1", "XX.00002..FH1", ..., "XX.00123..FH1" up to all available streams.

Running the service
===================
To run the service you should "cd" into the folder with the TDMS files and make sure that there is a file called
"tdmsws.cfg" with its variables properly configured. Then, you can simply call the programm, which will start and run
as a daemon. The service will listen to all requests in port 7000.

Web service methods
===================

    * query: The six required parameters "net", "sta", "loc", "cha", "starttime", and "endtime" are supported. The aliases are still missing. Errors are returned as specified in the standard.

    * version: returns the version number in text/plain format

    * application.wadl: NOT implemented yet!

    * queryauth: NOT implemented yet!