irfpy.vmag.scidata

MAG data module.

MAG is the magnetometer on board VEX.

There are two dataset supported. Graz-IRF collaborative dataset (4s time resolution) and PSA dataset (1s time resolution). The 1s dataset can be accessed by the module named irfpy.vmag.scidata1s.

Graz-IRF collaborative dataset (4s data product)

This MAG dataset was provided from Graz, and stored into a folder of user’s preference. The path should be specified in .irfpyrc with the entry of vmagbase under the section of [vmag].

See example below:

[vmag]
vmagbase = /venus/mag

Getting data

The simplest way of getting data is as follows:

>>> t0 = datetime.datetime(2006, 12, 5, 10, 0, 0)
>>> tobs, magvso = get_mag(t0)

You can get data in S/C frame using frame keyword.

>>> tobs, magsc = get_mag(t0, frame='sc')

Note that the t0 specified is not exactly the same as tobs returned. This is because the method just returns the data in the database tagged as the previous time of the specified time.

Thus, it is sometimes better if you know the exact time in the dataset. You can use get_obstime for this purpose.

>>> t0 = datetime.datetime(2006, 12, 5, 10, 0, 0)
>>> t1 = datetime.datetime(2006, 12, 5, 10, 10, 0)
>>> tlist = get_obstime(t0, t1)

This will give you the exact time of the data in the database.

If you want the data in the time series, you may also use the following syntax.

>>> t0 = datetime.datetime(2006, 12, 5, 10, 0, 0)
>>> t1 = datetime.datetime(2006, 12, 5, 10, 10, 0)
>>> tobs, magvso = get_magarray(t0, t1, frame='vso')

The data may contain untrusted data. In this case, 3-element array composed of nan is returned.

>>> t0 = datetime.datetime(2014, 11, 15, 0, 6, 1)
>>> tobs, magvso = get_mag(t0)
>>> print(magvso)      
[nan nan nan]

Note for developer

The module structure follows the guideline of data base accessor. See Hierarchy of irfpy.vels.scidata module for reference.

Note for logging

A python logger with name ‘irfpy.vmag.scidata’ is used.

class irfpy.vmag.scidata.MagData(t, bvso, bsc)

Bases: object

MAG data at a specified time. (4-s data)

MAG data contains the following information.

Observation time (starttime)

The start time of the observation. datetime.datetime instance.

B field in VSO frame (bvso)

The magnetic field in the VSO frame. Instance of numpy.array with the shape of (3,).

B field in VEX frame (bsc)

The magnetic field in the VEX frame. Instance of numpy.array with the shape of (3,).

Accessor by index is also supported.

get_starttime()

get_data(frame=None)

irfpy.vmag.scidata.parse_magfile(filename)

The mag data file is read and parsed.

Parameters

filename – Filename

Returns

A dictionary , with a key of time and a value of data.

class irfpy.vmag.scidata.MagFile(filename)

Bases: object

Class for a single MAG data file.

Parameters

filename – File name of MAG data.

Normally this is to reading the file, the instance should be regarded as immutable.

Contents of an instance is

• Time array, sorted array of the observation time

• Data dict, MagData instance corresponding to the time

parse_file()

Parse the file. It takes 6 s for my Mac. Should be much shorter, though.

get_data(t)

Pick the data of specified time

Parameters

t (datetime.datetime) – Time.

Returns

The corresponding MagData.

Return type

MagData instance

get_obstime()

Return the observation time list.

Returns

Observation time list of datetime.datetime instance

Return type

list of datetime.datetime

get_timerange(start_offset=0, stop_offset=0)

Return the time range of the observation.

Returns

Range of data file time as a list of datetime.datetime instances.

[t0 + start_offset, t1 + stop_offset] is returned, where t0 is the start time (the time of the first packet) and t1 is the end time (the time of the last packet). This means that the end time t1 does not agree with the end of the observation time. The end of the observation time should be the end time plus data acquisition time (4 sec, typically). Specifying stop_offset will compensate this issue.

Parameters

• start_offset – Offset in seconds to be added to the start time.

• stop_offset – Offset in seconds to be added to the stop time.

class irfpy.vmag.scidata.MagDB(rootfolder, enable_cache=True, cachesize=10)

Bases: object

Class for MAG data base.

Parameters

rootfolder – Root folder.

Data base is assumed to have a strucuture like

<rootfolder> -+- MAG_2009-01-01T00-00-00_DOY_001_S004_3_VSO_SAPV.dat
              +- MAG_2009-01-02T00-00-00_DOY_002_S004_3_VSO_SAPV.dat
              +- MAG_2009-01-03T00-00-00_DOY_003_S004_3_VSO_SAPV.dat
              +- ...

The data base is in the spaghetti.irf.se by manually mirroring from the Graz server thank to Tielong. The <rootfolder> in the spaghetti is /venus/mag/.

Initialize MagDB

Parameters

• rootfolder – The root folder.

• enable_cache – Enable cache.

• cachesize – Cache size

get_magfile(filename)

Get the instance for the MAG data file.

get_filename_fromdb(t)

Return the file name registered in the data base.

No clever check will be done as get_filename(). Just return the file name registered in the data base.

Use get_filename() for strict use.

get_filename(t, offset=4)

Use get_filename_fromdb().

previousof(filename)

nextof(filename)

classmethod get_defaultdb(enable_cache=True, cachesize=10)

Return the instance of MagDB from default rootfolder.

The default rootfolder can be defined by [vmag]-vmagbase in .irfpyrc.

irfpy.vmag.scidata.get_defaultdb(enable_cache=True)

This is an easy-accessor for ElsCountFileDB.get_defaultdb().

irfpy.vmag.scidata.isdb()

Return if the default database is available or not.

If False is returned, please check the entry of

[vmag]
vmagbase = /venus/mag

irfpy.vmag.scidata.get_mag(t, frame=None)

Return the MAG data in the specific time.

Parameters

t (datetime.datetime.) – Time

Returns

An array of the observation time and corresponding magnetic field data in the shape of (3,).

>>> t0 = datetime.datetime(2006, 12, 5, 7, 59, 59, 820996)
>>> t, mag = get_mag(t0)
>>> print(t)   # This may fail if data base changed.
2006-12-05 07:59:56
>>> print(mag.shape)   # This may fail if data base changed.
(3,)
>>> print(mag)   # This may fail if data base changed.
[ 4.078  1.431 -0.049]

>>> t, magsc = get_mag(t0, frame='sc')
>>> print(t)
2006-12-05 07:59:56
>>> print(magsc)      
[3.433 0.031 2.625]

irfpy.vmag.scidata.get_magarray(t0, t1, frame=None)

Return the MAG data between t0 and t1.

Parameters

• t0 – Start time, inclusive.

• t1 – End time, inclusive.

• frame (string) – Frame. 'vso' (default) or 'sc'.

Returns

A tuple (obstime, magarray). obstime is a list of the observation time. magarray is a numpy array with a shape of (N, 3), where N is the number of data.

>>> t0 = datetime.datetime(2006, 12, 5, 7, 30)
>>> t1 = datetime.datetime(2006, 12, 5, 7, 31)
>>> tlist, magarr = get_magarray(t0, t1)
>>> print(len(tlist))
16
>>> print(magarr.shape)
(16, 3)

irfpy.vmag.scidata.get_mags(t0, t1, frame=None)

Return the MAG data between t0 and t1.

Parameters

• t0 – Start time, inclusive.

• t1 – End time, inclusive.

• frame (string) – Frame. 'vso' or 'sc'.

Returns

A tuple (obstime, list_of_vector). obstime is a list of the observation time. list_of_vector is a list of magnetic field, namely, a list of (3,) shaped array.

The function is very similar to get_magarray(), but the structure is different.

This function is better used for iterating the results, while the time series analysis (e.g. taking averages, variations) or just plotting, you may use get_magarray().

>>> t0 = datetime.datetime(2006, 12, 5, 7, 30)
>>> t1 = datetime.datetime(2006, 12, 5, 7, 30, 15)
>>> tlist, maglist = get_mags(t0, t1)
>>> print(len(tlist))
4
>>> for t, b in zip(tlist, maglist):
...     print(t, b[0], b[1], b[2])
2006-12-05 07:30:00 -6.163 -3.536 3.544
2006-12-05 07:30:04 -4.923 -3.832 4.088
2006-12-05 07:30:08 -4.826 -3.636 3.875
2006-12-05 07:30:12 -5.358 -2.949 3.315

irfpy.vmag.scidata.get_obstime(t0, t1)

Get the obseration times (4-s resolution).

Parameters

• t0 (datetime.datetime) – Start time

• t1 (datetime.datetime) – Start time

Returns

List of datetime.datetime.

The following tests shows simple samples of using get_obstime(). This is based on database on 110704, so tests may be failed according to the change in the database.

>>> if not isdb():
...     pass 
... else:
...     t0 = datetime.datetime(2006, 12, 5)
...     t1 = datetime.datetime(2006, 12, 6)
...     t = get_obstime(t0, t1)
...     print(len(t))   # Database change may cause fails of the test.
21601

>>> if not isdb():
...     pass 
... else:
...     print(t[0])   # Database change may cause fails of the test.
2006-12-05 00:00:00

>>> if not isdb():
...     pass 
... else:
...     print(t[-1])   # Database change may cause fails of the test.
2006-12-06 00:00:00

irfpy.vmag.scidata.get_average_mag(t0, t1, frame=None)

Return the average magnetic field over t0 and t1.

Averaging has been done component-by-component.

Parameters

• t0 – Start time

• t1 – Stop time

Returns

(Bx, By, Bz)

>>> t0 = datetime.datetime(2012, 3, 1, 0, 0)
>>> t1 = datetime.datetime(2012, 3, 1, 0, 10)
>>> bx, by, bz = get_average_mag(t0, t1)
>>> print('{:.3f} {:.3f} {:.3f}'.format(bx, by, bz))
4.685 0.487 -1.157

irfpy.vmag.scidata.get_avgstd_mag(t0, t1, frame=None)

Return the average and std of magnetic field over t0 and t1.

Average/Std has been taken component-by-component.

Parameters

• t0 – Start time

• t1 – Stop time

Returns

(Bx, By, Bz), (dBx, dBy, dBz)

>>> t0 = datetime.datetime(2012, 3, 1, 0, 0)
>>> t1 = datetime.datetime(2012, 3, 1, 0, 10)
>>> (bx, by, bz), (dbx, dby, dbz) = get_avgstd_mag(t0, t1)
>>> print('{:.3f} {:.3f} {:.3f}'.format(bx, by, bz))
4.685 0.487 -1.157
>>> print('{:.3f} {:.3f} {:.3f}'.format(dbx, dby, dbz))
0.551 0.742 0.460

irfpy.vmag.scidata.clockangle(y, z)

Calculate the clock angle.

This calculate the clock angle. No abberation is considered.

The definition of clock angle is that

• 0 degree at positive Bz only

• 90 degrees at positive By only

• No abberation considered (i.e. thus, Bx not used)

• The range is from -180 (exclusive) to +180 (inclusive)

Parameters

• by – By

• bz – Bz

Returnc

Clock angle in degrees

>>> print(clockangle(1, 0))
90.0
>>> print(clockangle(0, 1))
0.0
>>> print(clockangle(-1, 0))
-90.0
>>> print(clockangle(0, -1))
180.0