New time series interface

This commit is similar to what was done for radial profiles in commit
d794fa1.

In particular:
- items of sdat.tseries are named tuples with values, time, and
  meta fields;
- EXTRA variables are accessible through the same interface as
  regular variables;
- processing functions no longer have tstart/tend as arguments;
- time_series.get_time_series is removed, replaced by tseries[];
- tseries.tslice replaces sdat.tseries_between;
- tseries.time offers easy access to the time coordinate.

Moreover compstat is now a list of time variable for which statistics
are desired.

Author: amorison

docs/sources/stagyydata.rst

@@ -89,7 +89,7 @@ Radial profiles
 Radial profile data are accessible trough the :attr:`~stagpy._step.Step.rprofs`
 attribute of a :class:`~stagpy._step.Step` instance.  This attribute implements
 getitem to access radial profiles.  Keys are the names of available
-variables (such as e.g. ``'Tmean'`` and ``'ftop'``).  Items are named tuples
+variables (such as e.g. ``'Tmean'`` and ``'vzabs'``).  Items are named tuples
 with three fields:
 
 - :data:`values`: the profile itself;
@@ -108,29 +108,27 @@ the 1000th timestep.
 Time series
 -----------
 
-Temporal data are contained in the
+Temporal data are accessible through the
 :attr:`~stagpy.stagyydata.StagyyData.tseries` attribute of a
-:class:`~stagpy.stagyydata.StagyyData` instance. This attribute is a
-:class:`pandas.DataFrame`. Its :attr:`columns` are the names of available
-variables. Its :attr:`index` is the time steps number (:attr:`istep`). The list
-of available variables can be obtained by running ``% stagpy var``.
-
-The temporal data of a given time step can be accessed from
-:attr:`_Step.timeinfo <stagpy.stagyydata._Step.timeinfo>`.  For example,
-``sdat.steps[1000].timeinfo`` is equivalent to ``sdat.tseries.loc[1000]``. Both
-are :class:`pandas.Series` indexed by the available variables.
-
-As an example, the following lines are three ways of accessing the average
-temperature at the 1000th timestep::
-
-    # extract time series info available for the 1000th timestep,
-    # and then take the average temperature
-    sdat.steps[1000].timeinfo['Tmean']
-    # extract the temperature time series,
-    # and then take the 1000th timestep
-    sdat.tseries['Tmean'][1000]
-    # direct access to the wanted info
-    sdat.tseries.loc[1000, 'Tmean']
+:class:`~stagpy.stagyydata.StagyyData` instance. This attribute implements
+getitem to access time series.  Keys are the names of available variables
+(such as e.g. ``'Tmean'`` and ``'ftop'``).  Items are named tuples with
+three fields:
+
+- :data:`values`: the series itself;
+- :data:`time`: the times at which the series is evaluated;
+- :data:`meta`: metadata of the series, also a named tuple with:
+
+    - :data:`description`: explanation of what the series is;
+    - :data:`kind`: the category of series;
+    - :data:`dim`: the dimension of the series (if applicable) in SI units.
+
+The list of available variables can be obtained by running ``% stagpy var``.
+
+The time series data at a given time step can be accessed from
+:attr:`Step.timeinfo <stagpy._step.Step.timeinfo>`.  For example,
+``sdat.steps[1000].timeinfo`` is equivalent to ``sdat.tseries.at_step(1000)``.
+Both are :class:`pandas.Series` indexed by the available variables.
 
 
 Geometry

stagpy/_step.py

@@ -529,13 +529,8 @@ def geom(self):
 
     @property
     def timeinfo(self):
-        """Time series data of the time step.
-
-        Set to None if no time series data is available for this time step.
-        """
-        if self.istep not in self.sdat.tseries.index:
-            return None
-        return self.sdat.tseries.loc[self.istep]
+        """Time series data of the time step."""
+        return self.sdat.tseries.at_step(self.istep)
 
     @property
     def isnap(self):

stagpy/config.py

@@ -144,7 +144,9 @@ def _index_collection(arg):
     ('style',
         Conf('-', True, None, {},
              True, 'matplotlib line style')),
-    ('compstat', switch_opt(False, None, 'compute steady state statistics')),
+    ('compstat',
+        Conf('', True, None, {'nargs': '?', 'const': ''},
+             False, 'compute mean and rms of listed variables')),
     ('tstart',
         Conf(None, True, None, {'type': float},
              False, 'beginning time')),

stagpy/misc.py

@@ -121,6 +121,22 @@ def set_of_vars(lovs):
     return set(var for pvars in lovs for svars in pvars for var in svars)
 
 
+def find_in_sorted_arr(value, array, after=False):
+    """Return position of element in a sorted array.
+
+    Returns:
+        int: the maximum position i such as array[i] <= value.  If after is
+            True, it returns the min i such as value <= array[i] (or 0 if such
+            an indices does not exist).
+    """
+    ielt = array.searchsorted(value)
+    if ielt == array.size:
+        ielt -= 1
+    if not after and array[ielt] != value and ielt > 0:
+        ielt -= 1
+    return ielt
+
+
 class InchoateFiles:
     """Context manager handling files whose names are not known yet.
 

stagpy/processing.py

@@ -11,97 +11,75 @@
 from .error import NotAvailableError
 
 
-def dtime(sdat, tstart=None, tend=None):
+def dtime(sdat):
     """Time increment dt.
 
     Compute dt as a function of time.
 
     Args:
         sdat (:class:`~stagpy.stagyydata.StagyyData`): a StagyyData instance.
-        tstart (float): time at which the computation should start. Use the
-            beginning of the time series data if set to None.
-        tend (float): time at which the computation should end. Use the
-            end of the time series data if set to None.
     Returns:
         tuple of :class:`numpy.array`: dt and time arrays.
     """
-    tseries = sdat.tseries_between(tstart, tend)
-    time = tseries['t'].values
+    time = sdat.tseries.time
     return time[1:] - time[:-1], time[:-1]
 
 
-def dt_dt(sdat, tstart=None, tend=None):
+def dt_dt(sdat):
     """Derivative of temperature.
 
     Compute dT/dt as a function of time using an explicit Euler scheme.
 
     Args:
         sdat (:class:`~stagpy.stagyydata.StagyyData`): a StagyyData instance.
-        tstart (float): time at which the computation should start. Use the
-            beginning of the time series data if set to None.
-        tend (float): time at which the computation should end. Use the
-            end of the time series data if set to None.
     Returns:
         tuple of :class:`numpy.array`: derivative of temperature and time
         arrays.
     """
-    tseries = sdat.tseries_between(tstart, tend)
-    time = tseries['t'].values
-    temp = tseries['Tmean'].values
+    temp, time, _ = sdat.tseries['Tmean']
     dtdt = (temp[1:] - temp[:-1]) / (time[1:] - time[:-1])
     return dtdt, time[:-1]
 
 
-def ebalance(sdat, tstart=None, tend=None):
+def ebalance(sdat):
     """Energy balance.
 
     Compute Nu_t - Nu_b + V*dT/dt as a function of time using an explicit
     Euler scheme. This should be zero if energy is conserved.
 
     Args:
         sdat (:class:`~stagpy.stagyydata.StagyyData`): a StagyyData instance.
-        tstart (float): time at which the computation should start. Use the
-            beginning of the time series data if set to None.
-        tend (float): time at which the computation should end. Use the
-            end of the time series data if set to None.
     Returns:
         tuple of :class:`numpy.array`: energy balance and time arrays.
     """
-    tseries = sdat.tseries_between(tstart, tend)
     rbot, rtop = sdat.steps[-1].rprofs.bounds
     if rbot != 0:  # spherical
         coefsurf = (rtop / rbot)**2
         volume = rbot * ((rtop / rbot)**3 - 1) / 3
     else:
         coefsurf = 1.
         volume = 1.
-    dtdt, time = dt_dt(sdat, tstart, tend)
-    ftop = tseries['ftop'].values * coefsurf
-    fbot = tseries['fbot'].values
-    radio = tseries['H_int'].values
+    dtdt, time = dt_dt(sdat)
+    ftop = sdat.tseries['ftop'].values * coefsurf
+    fbot = sdat.tseries['fbot'].values
+    radio = sdat.tseries['H_int'].values
     ebal = ftop[1:] - fbot[1:] + volume * (dtdt - radio[1:])
     return ebal, time
 
 
-def mobility(sdat, tstart=None, tend=None):
+def mobility(sdat):
     """Plates mobility.
 
     Compute the ratio vsurf / vrms.
 
     Args:
         sdat (:class:`~stagpy.stagyydata.StagyyData`): a StagyyData instance.
-        tstart (float): time at which the computation should start. Use the
-            beginning of the time series data if set to None.
-        tend (float): time at which the computation should end. Use the
-            end of the time series data if set to None.
     Returns:
         tuple of :class:`numpy.array`: mobility and time arrays.
     """
-    tseries = sdat.tseries_between(tstart, tend)
-    steps = sdat.steps[tseries.index[0]:tseries.index[-1]]
     time = []
     mob = []
-    for step in steps.filter(rprofs=True):
+    for step in sdat.steps.filter(rprofs=True):
         time.append(step.timeinfo['t'])
         mob.append(step.rprofs['vrms'].values[-1] / step.timeinfo['vrms'])
     return np.array(mob), np.array(time)