mth5.clients.intermag

Created on Fri Apr 17 18:02:38 2026

@author: jpopelar

Classes

`IntermagClient`	Get geomagnetic data from observatories.
`Intermag`

Module Contents

class mth5.clients.intermag.IntermagClient(**kwargs)[source]

Get geomagnetic data from observatories.

key words

observatory: Geogmangetic observatory ID
type: type of data to get ‘adjusted’
start: start date time to request UTC
end: end date time to request UTC
elements: components to get
sampling_period: samples between measurements in seconds
format: JSON or IAGA2002

Use this URL base as an example ‘https://imag-data.bgs.ac.uk/GIN_V1/GINServices?request=GetData&observatoryIagaCode=WIC&dataStartDate=2021-03-10T00:00:00Z&dataEndDate=2021-03-11T23:59:59Z&Format=iaga2002&elements=&publicationState=adj-or-rep&samplesPerDay=minute’ https://wdcapi.bgs.ac.uk/data/text-data/day/{obs-name} .. seealso:: https://www.usgs.gov/tools/web-service-geomagnetism-data

type = 'adjusted'[source]

property sampling_period[source]

samples_per_day = 'second'[source]

property elements[source]

format = 'json'[source]

property observatory[source]

property start[source]

property end[source]

property user_agent[source]

User agent for the URL request

Returns:: DESCRIPTION
Return type:: TYPE

get_data(run_id='001')[source]

Get data from geomag client at USGS based on the request. This might have to be done in chunks depending on the request size. The returned output is a json object, which we should turn into a ChannelTS object

For now read into a pandas dataframe and then into a ChannelTS

In the future, if the request is large, think about writing directly to an MTH5 for better efficiency.

Returns:: DESCRIPTION
Return type:: TYPE

class mth5.clients.intermag.Intermag(**kwargs)[source]

save_path[source]

mth5_filename = None[source]

interact = False[source]

request_columns = ['observatory', 'type', 'elements', 'sampling_period', 'start', 'end'][source]

h5_compression = 'gzip'[source]

h5_compression_opts = 4[source]

h5_shuffle = True[source]

h5_fletcher32 = True[source]

h5_data_level = 1[source]

mth5_file_mode = 'a'[source]

mth5_version = '0.2.0'[source]

property h5_kwargs[source]

validate_request_df(request_df)[source]

Make sure the input request dataframe has the appropriate columns

Parameters:: request_df (pandas.DataFrame) – request dataframe
Returns:: valid request dataframe
Return type:: pandas.DataFrame

add_run_id(request_df)[source]

Add run id to request df

Parameters:: request_df (pandas.DataFrame) – request dataframe
Returns:: add a run number to unique time windows for each observatory at each unique sampling period.
Return type:: pandas.DataFrame

make_mth5_from_intermag(request_df)[source]

Download geomagnetic observatory data from USGS webservices into an MTH5 using a request dataframe or csv file.

Parameters:

request_df (pandas.DataFrame, str or Path if csv file) –

DataFrame with columns

’observatory’ –> Observatory code
’type’ –> data type [ ‘variation’ | ‘adjusted’ | ‘quasi-definitive’ | ‘definitive’ ]
’elements’ –> Elements to get [D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z]
’sampling_period’ –> sample period [ 1 | 60 | 3600 ]
’start’ –> Start time YYYY-MM-DDThh:mm:ss
’end’ –> End time YYYY-MM-DDThh:mm:ss

Returns:

if interact is True an MTH5 object is returned otherwise the path to the file is returned

Return type:

Path or mth5.mth5.MTH5