README.md

Geomag Algorithms

Geomag Algorithms is an open source library for processing Geomagnetic timeseries data. It includes algorithms and input/output factories used by the USGS Geomagnetism Program to translate between data formats, generate derived data and indices in near-realtime, and research and develop new algorithms.

• Accesses USGS data services.
• Built using established open source python libraries NumPy, SciPy, and ObsPy.
• Common geomagnetic formats including IAGA2002, IMFV122, IMFV283 (read only), and PCDCP.
• Defines command line interface, geomag.py.
• Embeddable Python API, import geomagio.

Examples

More Examples in docs/example/

The following examples request data from USGS for BOU observatory, H, E, Z, and F component, minute interval, and variation type data for the day 2016-07-04, then write IAGA2002 formatted output to the console.

Command Line Interface Example

geomag.py \
    --input edge \
    --observatory BOU \
    --inchannels H E Z F \
    --type variation \
    --interval minute \
    --output iaga2002 \
    --output-stdout \
    --starttime 2016-07-04T00:00:00Z \
    --endtime 2016-07-04T23:59:00Z

Command Line Interface documentation

Python API Example

import sys
import geomagio
from obspy.core import UTCDateTime

input_factory = geomagio.edge.EdgeFactory()
timeseries = input_factory.get_timeseries(
    observatory = 'BOU',
    channels = ('H', 'E', 'Z', 'F'),
    type = 'variation',
    interval = 'minute',
    starttime = UTCDateTime('2016-07-04T00:00:00Z'),
    endtime = UTCDateTime('2016-07-04T23:59:00Z'))

output_factory = geomagio.iaga2002.IAGA2002Factory()
output_factory.write_file(
    channels = ('H', 'E', 'Z', 'F'),
    fh = sys.stdout,
    timeseries = timeseries)

Python API documentation

Install

More Install options in docs/install.md.

Docker

Docker is the simplest install option.

1. Create and start a new container

   named geomagio, listening on local port 8000, from the image usgs/geomag-algorithms on docker hub

   docker run -d --name geomagio -p 8000:8000 usgs/geomag-algorithms
   

2. Find the token, (the token improves security)

   docker logs geomagio
   

   This outputs a URL to copy/paste into your browser address bar:

   Copy/paste this URL into your browser when you connect for the first time,
   to login with a token:
       http://localhost:8000/?token=TOKEN
   

3. Use the running container

• Run the geomag.py command line interface:

  docker exec -it geomagio geomag.py
  

• Run python interactively in a web browser (using the token found in step 2):

  http://localhost:8000/?token=TOKEN
  

  In the top right corner, choose "New" then "Python 2"

Algorithms

Algorithms described in docs/algorithms/

Developing

Developing described in docs/develop.md.

License

License described in LICENSE.md

Problems or Questions?

• Report an issue using the GitHub issue tracker
• Join the USGS geomag-data mailing list
• Email jmfee at usgs.gov

Additional Links

• USGS Geomagnetism Program Home Page
• Waffle Project Board