Commit 526ef99f authored by Javier Quinteros's avatar Javier Quinteros
Browse files

Major improvements in the documentation

parent 7aad3349
......@@ -63,13 +63,13 @@ def printmetadata(data):
def str2date(dstr: str) -> datetime.datetime:
"""Transform a string to a datetime.
"""Transform a string to a datetime
:param dstr: A datetime in ISO format.
:type dstr: str
:return: A datetime represented the converted input.
:rtype: datetime.datetime
:raise ValueError. if no integers are found as components of the string
:raise ValueError: if no integers are found as components of the string
"""
# In case of empty string
if (dstr is None) or (not len(dstr)):
......
......@@ -14,13 +14,14 @@
import sys
import os
from dastools import __version__
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('..'))
from dastools import __version__
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
......@@ -56,7 +57,7 @@ author = u'Javier Quinteros'
# built documents.
#
# The short X.Y version.
version = '0.5'
version = __version__[:3]
# The full version, including alpha/beta/rc tags.
release = __version__
......@@ -104,16 +105,12 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme = 'sphinxdoc'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'collapse_navigation': False,
'externalrefs': True,
'navigation_depth': 2,
'prev_next_buttons_location': 'both'
}
# Add any paths that contain custom themes here, relative to this directory.
......@@ -121,7 +118,7 @@ html_theme_options = {
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = 'dastools Documentation'
html_title = 'dastools v%s Documentation' % release
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
......@@ -138,7 +135,7 @@ html_title = 'dastools Documentation'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']
# html_static_path = ['.static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
......
dasconv package
===============
.. automodule:: dasconv
:members:
:undoc-members:
:show-inheritance:
dastools package
================
Submodules
----------
dastools.archive module
-----------------------
.. automodule:: dastools.archive
:members:
:undoc-members:
:show-inheritance:
dastools.dasconv module
-----------------------
.. automodule:: dastools.dasconv
:members:
:undoc-members:
:show-inheritance:
dastools.tdms module
--------------------
.. automodule:: dastools.tdms
:members:
:undoc-members:
:show-inheritance:
dastools.tdmsws module
----------------------
.. automodule:: dastools.tdmsws
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: dastools
:members:
:undoc-members:
:show-inheritance:
......@@ -4,4 +4,5 @@ Developer documentation
.. toctree::
:maxdepth: 4
dasconv
dastools
dastools User documentation
###########################
User documentation
##################
Summary
=======
......@@ -41,6 +41,7 @@ Installation
This software can be easily installed by means of pip with the following command ::
$ sudo pip3 install numpy
$ sudo pip3 install dastools
Optionally you could run it as a normal user (no sudo) and deploy it locally.
......@@ -64,40 +65,40 @@ Running the code
To check if the software was properly installed you can run ::
$ dasconv -h
% dasconv -h
usage: dasconv [-h] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-d DIRECTORY]
[--start START] [--end END] [--chstart CHSTART]
[--chstop CHSTOP] [--chstep CHSTEP] [--decimate {1,5}]
[--metadata] [-V]
filename
[--start START] [--end END] [--chstart CHSTART] [--chstop CHSTOP]
[--chstep CHSTEP] [--decimate {1,5}] [-N NETWORK] [-C CHANNEL]
[-o {SDS,StreamBased,StreamBasedHour}] [--metadata] [-V] filename
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.
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.
Directory where files are located (default: ".")
--start START, --starttime START
Start of the selected time window. Format:
2019-02-01T00:01:02.123456Z
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
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
--decimate {1,5} Factor by which the sampling rate is lowered by
decimation.
--decimate {1,5} Factor by which the sampling rate is lowered by decimation.
-N NETWORK, --network NETWORK
Network code to store in the miniseed header (default: "XX")
-C CHANNEL, --channel CHANNEL
Channel code to store in the miniseed header (default: "FSF")
-o {SDS,StreamBased,StreamBasedHour}, --outstruct {SDS,StreamBased,StreamBasedHour}
Available options are [SDS, StreamBased, StreamBasedHour]
--metadata Read and display the metadata from the TDMS files
-V, --version show program's version number and exit
dasconv can be used to convert data from TDMS format into miniSEED. Below you will find some examples showing how to
use it to select subsets of the original data and export it. A complete list of its parameters and default values can
be found in the :ref:`Table of parameters<Table_Parameters>`
......@@ -127,28 +128,31 @@ be found in the :ref:`Table of parameters<Table_Parameters>`
lowered by decimation. Exactly the factor
by which the number of samples will be
reduced ``1``
--network (-N) str Network code (two characters) ``XX``
--channel (-C) str Channel code (three characters) ``FSF``
--metadata bool Read and display metadata information
instead of exporting data Disable
--version (-V) bool Print version information Disable
=================== ======== ========================================= ==========
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). ::
dasconv -d /home/user/test/ --endtime "2019-05-08T09:32:15" default --chstart 0 --chstop 4 --decimate 5
......@@ -158,24 +162,25 @@ Notes on some measurements
--------------------------
dasconv is only exporting to mSEED format. Some tests have been made to export to other formats. The idea is to find
one or more formats which could provide some benefit compared to mSEED (e.g. more compression). ASDF was tested, but
the compression achieved was only 18% of the total size. With this level of compression is not worth to migrate the
data to a non 100% standard format.
one or more formats which could provide some benefit compared to mSEED (e.g. more compression).
For the time being, using STEIM2 compression and 32-bit integers the total size compression is around 30%.
When a decimation of factor 5 (e.g. 1000 Hz -> 200 Hz) is applied the final compression is around 85% (between 7
and 8 times smaller).
Testing the service
-------------------
.. todo:: Provide a ``test`` directory with a tdms file and its miniSEED version. Use dasconv to convert the data and
check with the provided miniSEED file. The same for an ASCII format.
.. todo::
Provide a ``test`` directory with a tdms file and its miniSEED version. Use dasconv to convert the data and check with the provided miniSEED file. The same for an ASCII format.
Two scripts are provided to test the functionality of the service at different
levels. These can be found in the ``test`` folder under the root directory of
your installation.
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.
tdmsws (alpha)
--------------
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.
A typical help message from ``tdmsws`` looks like the following: ::
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment