irfpy.vima.scidata

VEX/IMA science data, providing the count rate data file access

A file-based VEX/IMA science data accessor. The MATLAB formatted file is loaded.

Note

From v4.0.6, the default dataset became the “aurora” database (aka full database).

For high-level use, you may use get_ima_count_file(). It will read the corresponding file.

The returned is ImaCountFile object. Basically you may use

• ImaCountFile.mat to access the data matrix.

• ImaCountFile.getobstime() to access the observed time.

A simple example follows

>>> t = datetime.datetime(2006, 12, 5, 7)
>>> imafile = get_ima_count_file(t)
>>> if imafile is not None:
...     mat = imafile.mat
... else:
...     pass

How to handle the instance ``mat``?

See an independent document How to handle IMA science data?.

The data url should be specified by [vima] imamatbase in .irfpyrc.

[vima]
imamatbase = /path/to/datatree/

Todo

Disable the functionality of URI. Only limit to local access!

class irfpy.vima.scidata.ImaCountFile(filename)

Bases: object

VEX/IMA data file.

>>> imacnt = ImaCountFile(ImaCountFile.get_sample_filename())   

Load the matlab count rate file

Parameters

filename – The filename of the file. URI is no more supported (at least maintained.)

rc = <irfpy.util.irfpyrc.Rc object>

classmethod get_sample_filename()

classmethod get_uribase_path()

classmethod get_uri(yr, mo, dy, hr)

classmethod get_base_path()

classmethod get_filename(yr, mo, dy, hr)

mat

Matlab formatted data

getobstime()

Return the observation time list.

Returns

Observation time list (component is in datetime.datetime instance) is returned.

>>> imacnt = ImaCountFile(ImaCountFile.get_sample_filename())
>>> print(len(imacnt.getobstime()))
104

gettimerange(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 is the end time plus data acquisition time (12 sec or 24 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.

>>> imacnt = ImaCountFile(ImaCountFile.get_sample_filename())

>>> print(imacnt.gettimerange())
[datetime.datetime(2007, 1, 1, 5, 19, 11, 880840), datetime.datetime(2007, 1, 1, 6, 0, 24, 256140)]

>>> print(imacnt.gettimerange(stop_offset=12))
[datetime.datetime(2007, 1, 1, 5, 19, 11, 880840), datetime.datetime(2007, 1, 1, 6, 0, 36, 256140)]

irfpy.vima.scidata.isdb()

irfpy.vima.scidata.get_ima_count_file_reduced(time)

Return the ImaCountFile instance covering the specified time, from reduced-HD embedded dataset.

Parameters

time (datetime.datetime instance.) – Time of the data

Note: This is not yet fully debugged.

irfpy.vima.scidata.get_ima_count_file_full(time)

Return the ImaCountFile instance covering the specified time, from full-HK embedded data.

Parameters

time (datetime.datetime instance.) – Time of the data

Note: This is not yet fully debugged.

irfpy.vima.scidata.get_ima_count_file(time)

Return the ImaCountFile instance covering the specified time.

The dataset is selected either from

• Full-HK embedded data (aka Leif-matfile, or aurora-matfile). get_ima_count_file_full()

• Reduced-HK embedded data (aka Herbert-matfile, or spaghetti-matfile). get_ima_count_file_reduced()

Because of slightly different name convention, this function judges which dataset user is referring automatically. Full-HK is prioritized, and definitively recommended to be used.

Parameters

time (datetime.datetime instance.) – Time of the data

Returns

Ima count file.

Return type

ImaCountFile instance.

If there is no data file at the given time, None is returned.

irfpy.vima.scidata.reshape_mat3d(mat, npol=16)

Reshape the matlab contents into MAEPT order

The function reshapes the matrix to MAEPT order (mass-azimuth-energy-polar-time).

Polar (elevaion) number should be specified, if you know it is not 16 elevation mode.

Todo

Not polar number, but mode should be specified in the future.

Returns

(spectra, masslist, azimlist, polarlist, timelist). spectra has (N, 32, 16, 96, 16) element, where N is the number of 3-D data. masslist, azimlist, polarlist has (N, 2, 16, 96, 16) shape. timelist has (N, 16, 96, 16) shape.

>>> f = get_ima_count_file(datetime.datetime(2013, 1, 17, 7))
>>> if f is not None:
...     s, m, a, e, t = reshape_mat3d(f.mat)
... else:
...     s = m = a = e = t = None

Spectra matrix, s, should have (mass, azim, ene, polar, time) shape

>>> print(s.shape)      
(32, 16, 96, 16, 19)

Mass matrix, m, should have (2 = [stardidx, stopidx], mass, azim, polar, time) shape

>>> print(m.shape)         
(2, 32, 16, 16, 19)

Time matrix, t, must have (mass, azim, polar, time) shape

>>> print(t.shape)         
(32, 16, 16, 19)

You may (forcely) change the number of elevation scan

>>> if f is not None:
...     s, m, a, e, t = reshape_mat3d(f.mat, npol=8)
... else:
...     s = m = a = e = t = None
>>> print(s.shape)      
(32, 16, 96, 8, 38)

irfpy.vima.scidata.reshape_mat(mat)

Reshape the matlab contents into MAET order.

The function reshape the matrix to MAET order.

Parameters

mat – Matlab contents.

Returns

(spectra, masslist, azimlist, elevlist, timelist)

Each output has the shape of (32, 16, 96, T) for spectra; (32, 16, T) for timelist; and (2, 32, 16, T) for others. T is the number of time.

Parameters

mat – Matlab format data file

Returns

Tuple of array. (spectra, mass, azimuth, polar, time).

>>> f = get_ima_count_file(datetime.datetime(2013, 1, 17, 7))
>>> if f is not None:
...     s, m, a, e, t = reshape_mat(f.mat)
... else:
...     s = m = a = e = t = None

spectrum, s, has the (mass, azimuth, energy, time (withpolar), ) shape.

>>> print(s.shape)   
(32, 16, 96, 304)

mass, m, has the (2 = [startindex, stopindex], mass, azimuth, time (polar), ) shape

>>> print(m.shape)   
(2, 32, 16, 304)

Time, t, has the (mass, azimuth, time (polar), ) shape

>>> print(t.shape)   
(32, 16, 304)

irfpy.vima.scidata.reshape_mat_24(mat)

(Deprecated!) Reshape the matlab contents into MAET order.

Use reshape_mat().