irfpy.util.timeseries

Time sereis related classes.

Code author: Yoshifumi Futaana

ScalarSeries(time_array, data_array)	Represents time series of floating point scalar data.
Vector3dSeries(time_array, x_array, y_array, ...)	Time series of 3-D vector.
dtrange(t0, t1, delta)	Return a regularly separated list of datatime objects.

These classes stores a time series of scalar / vector values. For example, these may be used to represent a time profile of the plasma density, or a time series of magnetic field vector.

Note

There is similar class, irfpy.util.julday.JdSeries. The irfpy.util.julday.JdSeries class is slow and not easy to handle. Thus, developers may consider using ScalarSeries and Vector3dSeries.

Note

The ScalarSeries only handles float data. Vector3dSeries only treats 3-D vector of float. Internally they use ndarray, thus they are quicker and more flexible.

exception irfpy.util.timeseries.DataNotFound(value)

Bases: IrfpyException

Exception raised when the data is not found.

class irfpy.util.timeseries.ObjectSeries(time_array, data_sequence)

Bases: _TimeSeriesABC

Represents time series of any object.

Parameters:

• time_array – Sequence of time in datetime.dattime objects

• data_array – Sequecne of data in any format.

Represent time-tagged data. If the data is floating point, ScalarSeries can be used. If the data is 3-D real floating, VectorSeries can be used.

This class is for arbitrary object.

Initialize the series.

Parameters:

• time_array – Array of time.

• data_sequence – Array of data.

>>> tlist = [datetime.datetime(2001, 1, 10, 3),
...          datetime.datetime(2001, 1, 10, 1),
...          datetime.datetime(2001, 1, 10, 7),
...          datetime.datetime(2001, 1, 10, 18),
...          datetime.datetime(2001, 1, 10, 2)]
>>> print(len(tlist))
5
>>> dlist = [(3,), (1,), (7,), (18,), (2,)]
>>> tser = ObjectSeries(tlist, dlist)
>>> tlist2 = tser.times
>>> from pprint import pprint
>>> pprint(tlist2)
[datetime.datetime(2001, 1, 10, 1, 0),
 datetime.datetime(2001, 1, 10, 2, 0),
 datetime.datetime(2001, 1, 10, 3, 0),
 datetime.datetime(2001, 1, 10, 7, 0),
 datetime.datetime(2001, 1, 10, 18, 0)]
>>> dlist2 = tser.data
>>> print(dlist2)
[(1,), (2,), (3,), (7,), (18,)]

>>> pprint(tser.get_data())
((datetime.datetime(2001, 1, 10, 1, 0),
  datetime.datetime(2001, 1, 10, 2, 0),
  datetime.datetime(2001, 1, 10, 3, 0),
  datetime.datetime(2001, 1, 10, 7, 0),
  datetime.datetime(2001, 1, 10, 18, 0)),
 ((1,), (2,), (3,), (7,), (18,)))

>>> pprint(tser.get_data(datetime.datetime(2001, 1, 10, 2), datetime.datetime(2001, 1, 10, 7)))
((datetime.datetime(2001, 1, 10, 2, 0),
  datetime.datetime(2001, 1, 10, 3, 0),
  datetime.datetime(2001, 1, 10, 7, 0)),
 ((2,), (3,), (7,)))

>>> pprint(tser.get_data(datetime.datetime(2030, 1, 1), datetime.datetime(2040, 1, 1)))
((), ())

>>> for t, d in tser.iter():
...     print(t, d)
2001-01-10 01:00:00 (1,)
2001-01-10 02:00:00 (2,)
2001-01-10 03:00:00 (3,)
2001-01-10 07:00:00 (7,)
2001-01-10 18:00:00 (18,)
>>> tser2 = tser.clipped(datetime.datetime(2001, 1, 10, 2), datetime.datetime(2001, 1, 10, 7))
>>> print(len(tser2))
3
>>> pprint(tser2.get_data())
((datetime.datetime(2001, 1, 10, 2, 0),
  datetime.datetime(2001, 1, 10, 3, 0),
  datetime.datetime(2001, 1, 10, 7, 0)),
 ((2,), (3,), (7,)))

>>> tser3 = tser.clipped(datetime.datetime(2030, 10, 1), datetime.datetime(2010, 10, 1))
>>> print(len(tser3))
0

t0()

Return the time of the first data

Returns:

The earliest time.

Return type:

datetime.datetime

t1()

Return the time of the last data.

Returns:

The latest time.

Return type:

datetime.datetime

getobstime()

Return the list of the observation time.

Returns:

List of the observation time.

get_data(t0=None, t1=None)

Return the registered data.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive).

• t1 (datetime.datetime) – End time (inclusive).

Returns:

(tlist, dlist) where tlist is the list of the time as in datetime instance, and dlist is the data as in ndarray instance.

clipped(t0, t1)

Return clipped data.

Parameters:

• t0 – Start time (inclusive)

• t1 – Stop time (inclusive)

Returns:

Clipped object. It should be the same class as self.

at(t)

Return the data at the time of t.

The data at the time of t. The time should be exact. Usually you can get the time of the data by ObjectSeries.getobstime() method. If not data is available at t, DataNotFound error is raised.

nextof(t)

Return the data next of t. The next data time should be tdata > t.

Parameters:

t – Time

Returns:

A tuple, (tnext, dnext)

Exception:

If the next data is not available, DataNotFound error is raised.

>>> tlist = [datetime.datetime(2001, 1, 10, 3),
...          datetime.datetime(2001, 1, 10, 1),
...          datetime.datetime(2001, 1, 10, 7),
...          datetime.datetime(2001, 1, 10, 18),
...          datetime.datetime(2001, 1, 10, 2)]
>>> print(len(tlist))
5
>>> dlist = [(3,), (1,), (7,), (18,), (2,)]
>>> tser = ObjectSeries(tlist, dlist)
>>> t, d = tser.nextof(datetime.datetime(2001, 1, 10, 0))
>>> print(t, d)
2001-01-10 01:00:00 (1,)
>>> t, d = tser.nextof(datetime.datetime(2001, 1, 10, 3))
>>> print(t, d)
2001-01-10 07:00:00 (7,)

>>> t, d = tser.nextof(datetime.datetime(2001, 1, 10, 17))
>>> print(t, d)
2001-01-10 18:00:00 (18,)

>>> t, d = tser.nextof(datetime.datetime(2001, 1, 10, 18))    
Traceback (most recent call last):
...
timeseries.DataNotFound:

>>> t, d = tser.nextof(datetime.datetime(2001, 1, 10, 20))    
Traceback (most recent call last):
...
timeseries.DataNotFound:

previousof(t)

Return the data previous of t. The previous data time should be tdata < t.

Parameters:

t – Time

Returns:

A tuple, (tnext, dnext)

Exception:

If the previous data is not available, DataNotFound error is raised.

>>> tlist = [datetime.datetime(2001, 1, 10, 3),
...          datetime.datetime(2001, 1, 10, 1),
...          datetime.datetime(2001, 1, 10, 7),
...          datetime.datetime(2001, 1, 10, 18),
...          datetime.datetime(2001, 1, 10, 2)]
>>> print(len(tlist))
5
>>> dlist = [(3,), (1,), (7,), (18,), (2,)]
>>> tser = ObjectSeries(tlist, dlist)

>>> t, d = tser.previousof(datetime.datetime(2001, 1, 10, 20))
>>> print(t, d)
2001-01-10 18:00:00 (18,)
>>> t, d = tser.previousof(datetime.datetime(2001, 1, 10, 18))
>>> print(t, d)
2001-01-10 07:00:00 (7,)

>>> t, d = tser.previousof(datetime.datetime(2001, 1, 10, 2))
>>> print(t, d)
2001-01-10 01:00:00 (1,)

>>> t, d = tser.previousof(datetime.datetime(2001, 1, 10, 1))    
Traceback (most recent call last):
...
timeseries.DataNotFound:

>>> t, d = tser.previousof(datetime.datetime(2001, 1, 10, 0))    
Traceback (most recent call last):
...
timeseries.DataNotFound:

nearest(t)

Return the nearest data.

Parameters:

t –

Returns:

nearest_no_later(t)

Return the data point observed earlier than or equal to t, but the latest one.

Parameters:

t –

Returns:

nearest_later_or_at(t)

Return the data point observed earlier than or equal to t, but the latest one.

Parameters:

t –

Returns:

nearest_no_earlier(t)

Return the data point observed later than or equal to t, but the earliest one.

Parameters:

t –

Returns:

nearest_earlier_or_at(t)

Return the data point observed later than or equal to t, but the earliest one.

Parameters:

t –

Returns:

concatenate(other, strategy='overwrite')

Concatenate other series to return a new series.

Parameters:

• other – The other ObjectSeries

• strategy – Strategy to concatenate. Default is 'overwrite', in which the same data points are overwritten by the other data. If 'nooverwrite' is given, the same data points are kept as self data.

Returns:

New OtherSeries

Concatenate two series. If duplication happens, it overwrites by the second one (default), or kept original (nooverwrite).

>>> t0 = [datetime.datetime(2008, 12, 1),
...         datetime.datetime(2008, 12, 3),
...         datetime.datetime(2008, 12, 5)]
>>> d0 = [1.5, 2.5, 3.5]
>>> tser0 = ObjectSeries(t0, d0)
>>> print(len(tser0))
3

>>> t1 = [datetime.datetime(2008, 12, 5),
...         datetime.datetime(2008, 12, 8),
...         datetime.datetime(2008, 12, 9)]
>>> d1 = [4.5, 6.5, 9.5]
>>> tser1 = ObjectSeries(t1, d1)
>>> print(len(tser1))
3

Concatenate! Note that ther is one duplication. Latter (tser1) prioritized.

>>> tser2 = tser0.concatenate(tser1)
>>> print(len(tser2))
5

>>> t2, d2 = tser2.get_data()
>>> from pprint import pprint
>>> pprint(t2)
(datetime.datetime(2008, 12, 1, 0, 0),
 datetime.datetime(2008, 12, 3, 0, 0),
 datetime.datetime(2008, 12, 5, 0, 0),
 datetime.datetime(2008, 12, 8, 0, 0),
 datetime.datetime(2008, 12, 9, 0, 0))
>>> print(d2)
(1.5, 2.5, 4.5, 6.5, 9.5)

Or, tser0 could be prioritzed.

>>> tser3 = tser0.concatenate(tser1, strategy='nooverwrite')
>>> print(tser3.nearest(datetime.datetime(2008, 12, 5))[1])
3.5

iter()

class irfpy.util.timeseries.ScalarSeries(time_array, data_array)

Bases: _TimeSeriesABC

Represents time series of floating point scalar data.

Parameters:

• time_array – Sequence of time in datetime.datetime objects.

• data_array – Sequence of data in float.

Internally, the time is in matplotlib.dates number; however, most of the methods use datetime.datetime object as interface.

Sample follows.

First, prepare the list of the time and corresponding data.

>>> tlist = [datetime.datetime(2009, 1, 10, 12),
...          datetime.datetime(2009, 1, 10, 8),
...          datetime.datetime(2009, 1, 10, 4),
...          datetime.datetime(2009, 1, 10, 16),
...          datetime.datetime(2009, 1, 10, 0),]
>>> dlist = [0, 1, 2, 3, 4]

Then, instance the ScalarSeries object.

>>> ts = ScalarSeries(tlist, dlist)
>>> ts.shape
(2, 5)
>>> len(ts)
5
>>> tlist1, dlist1 = ts.get_data()
>>> print(dlist1)   
[4.  2.  1.  0.  3.]

If the time array has duplication, the last data is validated. In this case, the created ScalarSeries length will be 2, not 3.

>>> tlist2 = [datetime.datetime(2009, 2, 5, 12),
...           datetime.datetime(2009, 2, 5, 13),
...           datetime.datetime(2009, 2, 5, 13),]
>>> dlist2 = [100, 200, 500]
>>> ts2 = ScalarSeries(tlist2, dlist2)
>>> ts2.shape
(2, 2)
>>> avg = ts2.get_average(ts2.t0(), ts2.t1())
>>> print(avg)
300.0

The coverage of the data can be get via methods of t0() and t1().

>>> print(ts.t0())
2009-01-10 00:00:00

>>> print(ts.t1(fmt="mdates"))
733417.6666666666

To get the data, you can use get_data() method. get_average() and get_moment() methods will calculate the average and variance of the given data. To get the data with inter (and extra) polation, use spline_interpolate() method. concatenate() method will concatenate the other given ScalarSeries object.

Todo

Zero size ScalarSeries should be implemented. However, to do this you may need to separate the data array? TBC.

t0(fmt=None)

Returns the first data.

Parameters:

fmt – If "mdates" is specified, the corresponding object is returned.

Returns:

The earliest time.

Return type:

datetime.datetime or float.

t1(fmt=None)

Returns the first data.

Parameters:

fmt – If "mdates" is specified, the corresponding object is returned.

Returns:

The latest time.

Return type:

datetime.datetime or float.

getobstime()

Return the observation time.

Returns:

List of observation time.

>>> scalar_series = ScalarSeries.sample_data()
>>> print(len(scalar_series))
8
>>> tlist = scalar_series.getobstime()
>>> print(len(tlist))
8
>>> print(tlist[3])
2009-01-10 08:00:00

get_data(t0=None, t1=None)

Return the registered data.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive). Default is t0().

• t1 (datetime.datetime) – End time (inclusive). Default is t1().

Returns:

(tlist, dlist) where tlist is the list of the time as in datetime instance, and dlist is the data as in ndarray instance.

>>> tlist = dtrange(datetime.datetime(2009, 1, 30),
...                 datetime.datetime(2009, 1, 31),
...                 datetime.timedelta(hours=1))
>>> data = [i ** 2 for i in range(len(tlist))]
>>> ts = ScalarSeries(tlist, data)
>>> tlist2, data2 = ts.get_data(
...                     datetime.datetime(2009, 1, 30, 11, 30),
...                     datetime.datetime(2009, 1, 30, 13, 0))
>>> print(len(tlist2), len(data2))
2 2
>>> print(tlist2[0], tlist2[1])
2009-01-30 12:00:00 2009-01-30 13:00:00
>>> print('%.0f %.0f' % (data2[0], data2[1]))
144 169

get_average(t0=None, t1=None)

Return the average between t0 and t1.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive)

• t1 (datetime.datetime) – End time (inclusive)

Returns:

Average.

Use get_moment() for more precise use.

>>> tlist = dtrange(datetime.datetime(2009, 1, 30),
...                 datetime.datetime(2009, 1, 31),
...                 datetime.timedelta(hours=1))
>>> data = [i ** 2 for i in range(len(tlist))]
>>> ts = ScalarSeries(tlist, data)

The average below should be (144+169+196)/3 = 169.667.

>>> print('%.3f' % ts.get_average(
...                     datetime.datetime(2009, 1, 30, 11, 30),
...                     datetime.datetime(2009, 1, 30, 14, 0)))
169.667

get_moment(t0=None, t1=None)

Return the number of data, average and variance.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive)

• t1 (datetime.datetime) – End time (inclusive)

Returns:

(number of data, average, variance)

>>> tlist = dtrange(datetime.datetime(2009, 1, 30),
...                 datetime.datetime(2009, 1, 31),
...                 datetime.timedelta(hours=1))
>>> data = [i ** 2 for i in range(len(tlist))]
>>> ts = ScalarSeries(tlist, data)

The average below should be (121+144+169+196)/4 = 157.5 Variance is (36.5^2 + 13.5^2 + 11.5^2 + 38.5^2)/4 = 782.25

>>> ndat, ave, var = ts.get_moment(
...                     datetime.datetime(2009, 1, 30, 11, 0),
...                     datetime.datetime(2009, 1, 30, 14, 0))
>>> print(ndat)
4
>>> print('%.3f' % ave)
157.500
>>> print('%.3f' % var)
782.250

nearest(t)

Return the nearest data.

Parameters:

t – Scalar or list of time.

linear_interpolate(t)

Linear interpolation.

Parameters:

t – Time or a sequence of times.

Returns:

Interpolated data.

>>> tlist = [datetime.datetime(2009, 1, 10, 12),
...          datetime.datetime(2009, 1, 10, 8),
...          datetime.datetime(2009, 1, 10, 4),
...          datetime.datetime(2009, 1, 10, 16),
...          datetime.datetime(2009, 1, 10, 0),]
>>> dlist = [1, 2, 3, 2, 2]

>>> ts = ScalarSeries(tlist, dlist)

>>> print(ts.linear_interpolate(datetime.datetime(2009, 1, 10, 6)))
2.5

>>> print(ts.linear_interpolate([datetime.datetime(2009, 1, 10, 6), datetime.datetime(2009, 1, 10, 14)]))
[2.5 1.5]

spline_interpolate(t, extrapolate=False)

Interpolate using spline fitting.

Interpolation can be done using Spline fitting.

Parameters:

• t (datetime.datetime) – Time, sequence allowed.

• extrapolate – Extrapolation handling. If True is set, extrapolation is allowed. If False is set (default), extrapolation is not allowed. You may also set datetime.timedelta object here to set “glues” of the data. In this case, the inter/extra-polation between (t0() - extrapolate) and (t1() + extrapolate) is allowed.

Raises:

ValueError – If non-allowed extrapolation was executed.

By default extrapolation is not allowed, because it may produce unrealistic values.

>>> tlist = [datetime.datetime(2009, 1, 10, 12),
...          datetime.datetime(2009, 1, 10, 8),
...          datetime.datetime(2009, 1, 10, 4),
...          datetime.datetime(2009, 1, 10, 16),
...          datetime.datetime(2009, 1, 10, 0),]
>>> dlist = [1, 2, 3, 2, 2]

>>> ts = ScalarSeries(tlist, dlist)
>>> print('%.3f' % (
...      ts.spline_interpolate(datetime.datetime(2009, 1, 10, 8))))
2.000
>>> print('%.3f' % (
...      ts.spline_interpolate(datetime.datetime(2009, 1, 10, 6))))
2.625

You may give a list as argumnet, too.

>>> vals = ts.spline_interpolate([datetime.datetime(2009, 1, 10, 1),
...             datetime.datetime(2009, 1, 10, 5),
...             datetime.datetime(2009, 1, 10, 9),])
>>> print('%.3f %.3f %.3f' % (vals[0], vals[1], vals[2]))
2.547 2.859 1.672

Extrapolation is not allowed by default, but you can set extrapolation keyword to do it.

>>> print('%.3f' % (
...      ts.spline_interpolate(datetime.datetime(2009, 1, 11, 0),
...      extrapolate=True)))
18.000

You may also allow the extrapolation-allowed range with datetime.timedelta object. See scripts/timeseries_sample1 also (TBD).

>>> print('%.3f' % (
...      ts.spline_interpolate(datetime.datetime(2009, 1, 9, 0),
...      extrapolate=datetime.timedelta(days=1))))
-158.000

clear_cache()

Clear cache (for spline)

concatenate(other, strategy='overwrite')

Concatenate other series to return a new series.

Parameters:

• other – The other ScalarSeries

• strategy – Strategy to concatenate. Default is 'overwrite', in which the same data points are overwritten by the other data. If 'nooverwrite' is given, the same data points are kept as self data.

Returns:

New ScalarSeries

Prepare the first ScalarSeries with 3 records.

>>> t0 = [datetime.datetime(2008, 12, 1),
...         datetime.datetime(2008, 12, 3),
...         datetime.datetime(2008, 12, 5)]
>>> d0 = [1.5, 2.5, 3.5]
>>> ts0 = ScalarSeries(t0, d0)

Then, create the second ScalarSeries with 3 records.

>>> t1 = [datetime.datetime(2008, 12, 5),
...         datetime.datetime(2008, 12, 8),
...         datetime.datetime(2008, 12, 9)]
>>> d1 = [4.5, 6.5, 9.5]
>>> ts1 = ScalarSeries(t1, d1)

Concatenate them. Remember 1 record is duplicated. Therefore, only 5 records are in the new ScalarSeries.

>>> ts2 = ts0.concatenate(ts1)
>>> print(len(ts2))
5

The duplicated record is overwritten by ts1.

>>> print(ts2.nearest(datetime.datetime(2008, 12, 5)))
4.5

If ‘nooverwrite strategy is taken, ts0 is used.

>>> ts2 = ts0.concatenate(ts1, strategy='nooverwrite')
>>> print(ts2.nearest(datetime.datetime(2008, 12, 5)))
3.5

classmethod sample_data()

Get a sample data.

clipped(t0, t1)

Return clipped ScalarSeries.

Parameters:

• t0 – Start time

• t1 – Stop time

Returns:

clipped data between t0 and t1.

Return type:

ScalarSeries

>>> scalar_series = ScalarSeries.sample_data()
>>> print(len(scalar_series))
8
>>> clipped_scalar_series = scalar_series.clipped(
...                             datetime.datetime(2009, 1, 10, 7),
...                             datetime.datetime(2009, 1, 10, 15))
>>> print(len(clipped_scalar_series))
4
>>> print(clipped_scalar_series.t0())
2009-01-10 08:00:00
>>> print(clipped_scalar_series.t1())
2009-01-10 15:00:00

class irfpy.util.timeseries.Vector3dSeries(time_array, x_array, y_array, z_array)

Bases: _TimeSeriesABC

Time series of 3-D vector.

Internally each component uses ScalarSeries. This is a redundunt approch (time_array is repeated three times) but simple implementation wins.

>>> tlist = [datetime.datetime(2009, 1, 10, 0),
...          datetime.datetime(2009, 1, 10, 4),
...          datetime.datetime(2009, 1, 10, 8),
...          datetime.datetime(2009, 1, 10, 12),
...          datetime.datetime(2009, 1, 10, 16),]
>>> xlist = [0, 0.5, 1, 0.5, 0]
>>> ylist = [1, 0.5, 0, -0.5, -1]
>>> zlist = [0, 1, 2, 3, 4]
>>> vs = Vector3dSeries(tlist, xlist, ylist, zlist)

To get the data, you can use get_data() method.

>>> t0 = datetime.datetime(2009, 1, 10, 1)
>>> t1 = datetime.datetime(2009, 1, 10, 8)
>>> t, v = vs.get_data(t0, t1)
>>> print(len(t))
2
>>> print(t[0])
2009-01-10 04:00:00
>>> print(t[1])
2009-01-10 08:00:00
>>> print(v.shape)
(3, 2)
>>> print(v[:, 0])   
[0.5  0.5  1. ]
>>> print(v[:, 1])   
[1.  0.  2.]

You may also use get_average() and get_moment() methods for the average or moment values.

>>> ave = vs.get_average(t0, t1)
>>> print('%.2f %.2f %.2f' % (ave[0], ave[1], ave[2]))
0.75 0.25 1.50

>>> n, ave, var = vs.get_moment(t0, t1)
>>> print(n)
2
>>> print(ave)   
[0.75  0.25  1.5 ]
>>> print(var)   
[0.0625  0.0625  0.25  ]

For interpolation, you can use spline_interpolate().

>>> t_interpol = [t0, t1]
>>> val_interpol = vs.spline_interpolate(t_interpol)
>>> from irfpy.util.with_context import printoptions
>>> with printoptions(precision=2, suppress=True):
...     print(val_interpol.shape)
...     print(val_interpol[:, 0])   
... #    print val_interpol[:, 1]
(3, 2)
[0.04  0.88  0.25]

# [ 1. 0. 2.]

Todo

The doctest may make non-unique solution (0. or -0.) so that I disabled the test on 2013-09-03. One has to make better test routine here.

Instance the Vector3dSeries object

Parameters:

• time_array – Sequence of time in datetime.datetime objects.

• x_array – Sequence of x-component in float.

• y_array – Sequence of y-component in float.

• z_array – Sequence of z-component in float.

spline_interpolate(t, extrapolate=False)

Spline interpolation.

Returns the spline interpolation. Interpolation is component-wise. See also ScalarSeries.spline_interpolate() for details.

Parameters:

• t – datetime.datetime object or sequence of it.

• extrapolate – Extrapolation handling. See ScalarSeries.spline_interpolate() for details.

Returns:

Interpolated vector (component wise). If t is a datetime.datetime object, np.array with shape of (3, ) is returned. If t is a sequence of datetime.datetime with N length, np.array with shape of (3, N) is returned.

t0()

Return the first data time

t1()

Return the last data time

getobstime()

Return the observation time.

Returns:

List of observation time.

get_data(t0=None, t1=None)

Return the data in between t0 and t1.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive)

• t1 (datetime.datetime) – End time (inclusive)

Returns:

The data in between t0 and t1. ndarray with the shape of (3, N) where N is the number of data.

get_timeseries_magnitude()

Return the time series of the magnitude data.

Returns:

Time series of magnitude data.

Return type:

ScalarSeries.

>>> vecseries = Vector3dSeries.sample_data()
>>> print(len(vecseries))
5
>>> t, v = vecseries.get_data()
>>> magseries = vecseries.get_timeseries_magnitude()
>>> t, l = magseries.get_data()
>>> print(v)
[[ 0.   0.5  1.   0.5  0. ]
 [ 1.   0.5  0.  -0.5 -1. ]
 [ 0.   1.   2.   3.   4. ]]
>>> print(l)   
[1.          1.22474487  2.23606798  3.082207    4.12310563]

clipped(t0, t1)

Return clipped Vector3dSeries.

Parameters:

• t0 – Start time

• t1 – Stop time

Returns:

New Vector3dSeries

>>> tser3d = Vector3dSeries.sample_data()
>>> print(len(tser3d))
5
>>> tser3d = tser3d.clipped(datetime.datetime(2009, 1, 10, 6),
...                         datetime.datetime(2009, 1, 10, 15))
>>> print(len(tser3d))
2
>>> tlist, dlist = tser3d.get_data()
>>> print(dlist)
[[ 1.   0.5]
 [ 0.  -0.5]
 [ 2.   3. ]]

get_average(t0=None, t1=None)

Return the average.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive)

• t1 (datetime.datetime) – End time (inclusive)

Returns:

Average

Return type:

ndarray with shape of (3,)

get_moment(t0=None, t1=None)

Return the moment.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive)

• t1 (datetime.datetime) – End time (inclusive)

Returns:

A tuple. (number of data, average in (3,) ndarray, variance in (3,) ndarray)

clear_cache()

nearest(t)

concatenate(other, strategy='overwrite')

Concatenate other series to return a new series.

Parameters:

• other – The other Vector3dSeries

• strategy – Strategy to concatenate. Default is 'overwrite', in which the same data points are overwritten by the other data. If 'nooverwrite' is given, the same data points are kept as self data.

Returns:

New VectorSeries

>>> t0 = dtrange(datetime.datetime(2005, 1, 1),
...              datetime.datetime(2005, 1, 2),
...              datetime.timedelta(hours=6))    # 4 elements
>>> print(len(t0))
4
>>> x0 = [0, 1, 2, 3]
>>> y0 = [0, -1, -2, -3]
>>> z0 = [0, 0, 0, 0]
>>> v0 = Vector3dSeries(t0, x0, y0, z0)

>>> t1 = dtrange(datetime.datetime(2005, 1, 2),
...              datetime.datetime(2005, 1, 2, 12),
...              datetime.timedelta(hours=4))   # 3 elements
>>> x1 = [4, 5, 6]
>>> y1 = [-2, -1, 0]
>>> z1 = [1, 1, 1]
>>> v1 = Vector3dSeries(t1, x1, y1, z1)

>>> v2 = v0.concatenate(v1)
>>> print(len(v2))
7
>>> t2, d2 = v2.get_data()
>>> print(d2.shape)
(3, 7)
>>> print(d2[0, :])   
[0.  1.  2.  3.  4.  5.  6.]
>>> print(d2[1, :])
[ 0. -1. -2. -3. -2. -1.  0.]
>>> print(d2[2, :])   
[0.  0.  0.  0.  1.  1.  1.]

classmethod sample_data()

Return a sample data.

class irfpy.util.timeseries.TimeStepScalarField3D(time_list, field_list)

Bases: _TimeSeriesABC

Time series of scalar field.

This class extends the functionality of irfpy.util.fields.ScalarField3D class and their derivatives in order to support the time series of fields.

Note

This contains several ScalarField3D, so that the system should sometimes have a very large memory. No memory handling is supported. This means that all the data is on memory.

Sample

Let’s look at a scalar field, i.e. gravity potential, produced by a moving point of mass: \((x_m=vt, 0, 0)\).

The gravity potential is obtained from irfpy.util.fields.GravityPotential class. First, just create the potential field at t=0, i.e. x_m=0. The mass is taken as \(M=\frac{1}{6.67408\times 10^{-11}}\), then, \(GM=1\).

Note that the time should be datetime.datetime object. Thus, a dummy time (with respective to a given epoch).

>>> import datetime
>>> t0 = datetime.datetime(2010, 1, 1, 0, 0, 0)   # An epoch. This case, it is a dummy time.

\[\phi(r) = -\frac{GM}{r} = -\frac{1}{r}\]

>>> import irfpy.util.fields
>>> m = 1 / 6.67408e-11
>>> potential_t0 = irfpy.util.fields.GravityPotential(m, center=(0, 0, 0))

Just to confirm if it works, check the potential at (0, 4, 0).

>>> print(potential_t0([0, 4, 0]))
-0.25

Then, as time goes, the point of mass moves. Here I take v=2.5.

>>> v=2.5

At time t=1, the position of the mass is at x_m = v (=2.5).

>>> t=1
>>> xm_1 = (v * t, 0, 0)
>>> potential_t1 = irfpy.util.fields.GravityPotential(m, center=xm_1)

Now the observer at (0, 4, 0) see different potential, the distance is now \(|(2.5, 4.0, 0)|=4.717\) and the potential is \(\phi(r, t=1)=-1/r=-0.212\).

>>> print('{:.3f}'.format(potential_t1([0, 4, 0])))
-0.212

At time t=3, the position moves to x_m = 3v = 7.5.

>>> t=3
>>> xm_3 = (v * t, 0, 0)
>>> potential_t3 = irfpy.util.fields.GravityPotential(m, center=xm_3)
>>> print('{:.3f}'.format(potential_t3([0, 4, 0])))
-0.118

A bit more time steps are added as follows.

>>> si = (0, 1, 3, 5, 8)
>>> ti = [t0 + datetime.timedelta(seconds=_t) for _t in si]
>>> potential_list = []
>>> for _t in si:
...     xm_t = (v * _t, 0, 0)
...     potential_t = irfpy.util.fields.GravityPotential(m, center=xm_t)
...     potential_list.append(potential_t)

Now it is time to create a TimeStepScalarField.

>>> tsfield = TimeStepScalarField3D(ti, potential_list)

First, you can get the field directly. The following is the same as

>>> print('{:.3f}'.format(tsfield((0, 4, 0), t0 + datetime.timedelta(seconds=0))))    # At (0, 4, 0) at t=0
-0.250
>>> print('{:.3f}'.format(tsfield((0, 4, 0), t0 + datetime.timedelta(seconds=1))))     # At (0, 4, 0) at t=1
-0.212
>>> print('{:.3f}'.format(tsfield((0, 4, 0), t0 + datetime.timedelta(seconds=3))))     # At (0, 4, 0) at t=3
-0.118

Timewise, the linear interpolated value is returned. Spacewise, the default interpolation of the given field (irfpy.util.fields.ScalarField3D) is used.

>>> print('{:.3f}'.format(tsfield((0, 4, 0), t0 + datetime.timedelta(seconds=2))))     # At (0, 4, 0) at t=2 is not given, but the returned is linear interpolation.
-0.165

>>> print(tsfield.index_of_time(t0))
0
>>> print(tsfield.index_of_time(t0 + datetime.timedelta(seconds=4)))
2
>>> print(tsfield.index_of_time(t0 + datetime.timedelta(seconds=9)))
4

t0()

Return the time of the first data

Returns:

The earliest time.

Return type:

datetime.datetime

t1()

Return the time of the last data.

Returns:

The latest time.

Return type:

datetime.datetime

getobstime()

Return the list of the observation time.

Returns:

List of the observation time.

get_data(t0=None, t1=None)

Return the registered data.

Parameters:

• t0 (datetime.datetime) – Start time (inclusive).

• t1 (datetime.datetime) – End time (inclusive).

Returns:

(tlist, dlist) where tlist is the list of the time as in datetime instance, and dlist is the data as in ndarray instance.

clipped(t0, t1)

Return clipped data.

Parameters:

• t0 – Start time (inclusive)

• t1 – Stop time (inclusive)

Returns:

Clipped object. It should be the same class as self.

index_of_time(t)

irfpy.util.timeseries.dtrange(t0, t1, delta)

Return a regularly separated list of datatime objects.

Parameters:

• t0 (datetime.datetime) – Start

• t1 (datetime.datetime) – Stop (not inclusive)

• delta (datetime.timedelta.) – Delta

Returns:

List of datetime.datetime.

>>> r0 = dtrange(datetime.datetime(2009, 1, 1),
...              datetime.datetime(2009, 1, 2),
...              datetime.timedelta(hours=1))
>>> print(len(r0))
24
>>> print(r0[0])
2009-01-01 00:00:00
>>> print(r0[-1])
2009-01-01 23:00:00