HinetPy.client module

class HinetPy.client.Client(user=None, password=None, timeout=60, retries=3, sleep_time_in_seconds=5, max_sleep_count=30)

Wrapper client to request waveform, catalog and manipulate stations.

Parameters:

  • user (str) – Username of Hi-net account.

  • password (str) – Password of Hi-net account.

  • timeout (float) – Time to wait for the server to send data before giving up.

  • retries (int) – How many times to retry if a request fails.

  • sleep_time_in_seconds (float) – Sleep time between each data status check. See notes below.

  • max_sleep_count (int) – Maximum number of sleeps before failing. See notes below.

Notes

The Hi-net server ususally spends 10-60 seconds on data preparation after receiving a data request. During the data preparation, users are NOT allowed to post another data request. So users have to wait until the data is ready.

HinetPy checks data status every sleep_time_in_seconds seconds for no more than max_sleep_count times, until the data is ready. If the data status is still NOT ready after max_sleep_count * sleep_time_in_seconds seconds, it most likely means something goes wrong with the data request. Then, HinetPy will retry to request the data retries times. Ususally, you don’t need to modify these parameters unless you know what you’re doing.

Examples

>>> from HinetPy import Client
>>> client = Client("username", "password")
doctor()

Doctor does some checks.

This is a utility function that checks:

  • if HinetPy has a new release

  • if Hi-net web service is updated

  • if catwin32 and win2sac_32 are in PATH

>>> client.doctor()
Hi-net web service is NOT updated.
You're using the latest release (v0.x.x).
catwin32: Full path is /home/user/bin/catwin32.
win2sac_32: Full path is /home/user/bin/win2sac_32.
check_service_update()

Check if Hi-net service is updated.

>>> client.check_service_update()
[2017-01-01 00:00:00] INFO: Hi-net web service is NOT updated.
info(code=None)

Show information of networks.

Parameters:

code (None or str) – Network code.

Examples

>>> client.info()
0101   : NIED Hi-net
0103   : NIED F-net (broadband)
0103A  : NIED F-net (strong motion)
010501 : NIED V-net (Tokachidake)
...
0703   : Aomori Prefectural Government
0705   : Shizuoka Prefectural Government
0801   : ADEP
>>> client.info("0101")
== Information of Network 0101 ==
Name: NIED Hi-net
Starttime: 20040401
No. of channels: 2336
get_arrivaltime(startdate, span, filename=None, os='DOS')

Get JMA arrival time data from Hi-net.

Parameters:

  • startdate (str, datetime.date, datetime.datetime) – Start date to request.

  • span (int) – Data length in days.

  • os (str) – File format. “DOS” or “UNIX”.

  • filename (str) – Filename to save.

Returns:

Filename saved.

Return type:

str

Examples

>>> from datetime import date
>>> startdate = date(2010, 1, 1)
>>> client.get_arrivaltime(startdate, 5)
'measure_20100101_5.txt'
>>> client.get_arrivaltime(startdate, 5, filename="arrivaltime.txt")
'arrivaltime.txt'
get_continuous_waveform(code, starttime, span, max_span=None, data=None, ctable=None, outdir=None, threads=3, cleanup=True)

Get continuous waveform data from Hi-net server.

Parameters:

  • code (str) – Network code. See info() for details.

  • starttime (datetime.datetime or str) – Starttime of a data request.

  • span (int) – Time span in minutes.

  • max_span (int) – Maximum time span for sub-requests. Defaults to be determined automatically. See notes below.

  • data (str) – Filename of downloaded win32 data. Default format: CODE_YYYYmmddHHMM_SPAN.cnt

  • ctable (str) – Filename of downloaded channel table file. Default format: CODE_YYYYmmdd.ch

  • outdir (str) – Save win32 and channel table data to a specified directory. Default is in the current directory.

  • threads (int) – Parallel data download using more threads.

  • cleanup (bool) – Clean up one-minute cnt files after merging.

Returns:

  • data (str) – Filename of downloaded win32 data.

  • ctable (str) – Filename of downloaded channel table file.

Notes

TimeZone

All times in HinetPy and in Hi-net data are in JST (UTC+0900).

max_span

Hi-net server sets three limitations for each data request:

  1. Record_Length <= 60 min

  2. Number_of_channels * Record_Length <= 12000 min

  3. Only the latest 150 requested data are kept

For example, Hi-net network has about 24000 channels. Acoording to limitation 2, the record length should be no more than 5 minutes for each data request. HinetPy “break through” the limitation by splitting a long-duration data request into several short-duration sub-requsts.

How it works

  1. do several checks

  2. split a long-duration request into several short-duration sub-requests

  3. loop over all sub-requests and return the data IDs

  4. download all data based on the data IDs

  5. extract all zip files and merge them into one single win32 data

  6. clean up

Examples

Request 6-minute data since 2010-01-01T05:35 (UTC+0900) from Hi-net.

>>> client.get_continuous_waveform("0101", "201001010535", 6)
('0101_201001010535_6.cnt', '0101_20100101.ch')

Several other string formats of starttime are also supported:

>>> client.get_continuous_waveform("0101", "2010-01-01 05:35", 6)
>>> client.get_continuous_waveform("0101", "2010-01-01T05:35", 6)

datetime.datetime is also supported:

>>> from datetime import datetime
>>> starttime = datetime(2010, 1, 1, 5, 35)
>>> client.get_continuous_waveform("0101", starttime, 6)
('0101_201001010535_6.cnt', '0101_20100101.ch')

Request full-day data of 2010-01-01T00:00 (UTC+0900) of F-net:

>>> client.get_continuous_waveform("0103", starttime, 1440, max_span=25)
('0103_201001010000_1440.cnt', '0103_20100101.ch')
get_event_waveform(starttime, endtime, region='00', minmagnitude=3.0, maxmagnitude=9.9, include_unknown_mag=True, mindepth=None, maxdepth=None, minlatitude=None, maxlatitude=None, minlongitude=None, maxlongitude=None, latitude=None, longitude=None, minradius=None, maxradius=None)

Get event waveform data.

Parameters:

  • starttime (datetime.datetime or str) – Starttime of events.

  • endtime (datetime.datetime or str) – Endtime of events.

  • region (str) –

    Limit events in specified region. Allowed values are:

    • 00: Whole Japan

    • 01: Hokkaido Region

    • 02: Tohoku Region

    • 03: Kanto Region

    • 04: Chubu Region

    • 05: Kinki Region

    • 06: Chugoku/Shikoku Region

    • 07: Kyushu Region

    • 08: Others

  • minmagnitude (float) – Limit to events with a magnitude larger than speicified minimum.

  • maxmagnitude (float) – Limit to events with a magnitude smaller than speicified maximum.

  • include_unknown_mag (bool) – Include/exclude undetermined magnitude events.

  • mindepth (float) – Limit to events deeper than the specified minimum.

  • maxdepth (float) – Limit to events shallower than the specified maximum.

  • minlatitude (float) – Limit to events with a latitude larger than the specified minimum.

  • maxlatitude (float) – Limit to events with a latitude smaller than the specified maximum.

  • minlongitude (float) – Limit to events with a longitude larger than the specified minimum.

  • maxlongitude (float) – Limit to events with a longitude smaller than the specified maximum.

  • latitude (float) – Specify the latitude to be used for a radius search.

  • longitude (float) – Specify the longitude to be used for a radius search.

  • minradius (float) – Limit to events within the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • maxradius (float) – Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters.

get_focalmechanism(startdate, span, filename=None, os='DOS')

Get JMA focal mechanism data from Hi-net.

Parameters:

  • startdate (str, datetime.date, datetime.datetime) – Start date to request.

  • span (int) – Data length in days.

  • os (str) – File format. “DOS” or “UNIX”.

  • filename (str) – Filename to save.

Returns:

Filename saved.

Return type:

str

Examples

>>> from datetime import date
>>> startdate = date(2010, 1, 1)
>>> client.get_focalmechanism(startdate, 5)
'focal_20100101_5.txt'
>>> client.get_focalmechanism(startdate, 5, filename="focal.txt")
'focal.txt'
get_selected_stations(code: str)

Query stations selected for requesting data.

It supports two networks: Hi-net (0101) and F-net (0103, 0103A).

Parameters:

code – Network code.

Returns:

stations – List of selected stations with station metadata information.

Return type:

list of Station

Examples

>>> stations = client.get_selected_stations("0101")
>>> len(stations)
16
>>> for station in stations:
...     print(station)
0101 N.WNNH 45.4883 141.885 -159.06
0101 N.SFNH 45.3346 142.1185 -81.6
>>> names = [station.name for station in stations]
>>> print(*names)
N.WNNH N.SFNH ...
get_station_list(code)

Get station list of a network.

The function only supports the following networks: Hi-net (0101), F-net (0103, 0103A), S-net (0120, 0120A) and MeSO-net (0131).

>>> stations = client.get_station_list("0101")
>>> for station in stations:
...     print(station)
0101 N.WNNH 45.4883 141.885 -159.06
0101 N.SFNH 45.3346 142.1185 -81.6
...
get_waveform(code, starttime, span, **kwargs)

Deprecated since version 0.6.0: get_waveform() is deprecated. Use get_continuous_waveform() instead.

login(user, password)

Login in the Hi-net server.

Parameters:

  • user (str) – Username of Hi-net account.

  • password (str) – Password of Hi-net account.

Examples

>>> from HinetPy import Client
>>> client = Client()
>>> client.login("username", "password")
select_stations(code, stations=None, minlatitude=None, maxlatitude=None, minlongitude=None, maxlongitude=None, latitude=None, longitude=None, minradius=None, maxradius=None)

Select stations of a network.

It only supports the following networks: Hi-net (0101), F-net (0103, 0103A), S-net (0120, 0120A) and MeSO-net (0131).

Parameters:

  • code (str) – Network code.

  • stations (str or list) – Stations to select.

  • minlatitude (float) – Limit to stations with a latitude larger than the specified minimum.

  • maxlatitude (float) – Limit to stations with a latitude smaller than the specified maximum.

  • minlongitude (float) – Limit to stations with a longitude larger than the specified minimum.

  • maxlongitude (float) – Limit to stations with a longitude smaller than the specified maximum.

  • latitude (float) – Specify the latitude to be used for a radius search.

  • longitude (float) – Specify the longitude to be used for a radius search.

  • minradius (float) – Limit to stations within the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • maxradius (float) – Limit to stations within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters.

Examples

Select only two stations of Hi-net:

>>> client.select_stations("0101", ["N.AAKH", "N.ABNH"])
>>> len(client.get_selected_stations("0101"))
2

Select stations in a box region:

>>> client.select_stations(
...     "0101",
...     minlatitude=40,
...     maxlatitude=50,
...     minlongitude=140,
...     maxlongitude=150,
... )

Select stations in a circular region:

>>> client.select_stations(
...     "0101", latitude=30, longitude=139, minradius=0, maxradius=2
... )

Select all Hi-net stations:

>>> client.select_stations("0101")
>>> len(client.get_selected_stations("0101"))
0
class HinetPy.client.Event(evid, origin, latitude, longitude, depth, magnitude, name, name_en)

Event class for requesting event waveforms.

class HinetPy.client.Station(code, name, latitude, longitude, elevation)

Class for Stations.