flowtracks 1.1.0__py3-none-any.whl

flowtracks/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+__version__ = '1.1.0'

flowtracks/an_scene.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+
+import tables, itertools as it, numpy as np
+from .scene import read_dual_scene, gen_query_string
+from .trajectory import Trajectory
+
+class AnalysedScene(object):
+    """
+    A class for accessing data and analyses of a scene analysed and saved in 
+    the format used by flowtracks.analysis.analyse().
+    """
+    
+    def __init__(self, analysis_file):
+        """
+        Initializes the objects according to config and data-source metadata
+        saved in the analysis file.
+        
+        Arguments:
+        analysis_file - path to the HDF file containing analysis results.
+        """
+        self._file = tables.open_file(analysis_file, "r")
+        self._table = self._file.get_node('/analysis')
+        
+        config = self._table.attrs['config']
+        self._scene = read_dual_scene(config)
+        
+        # Cache data on user-visible columsn:
+        filt = ('trajid', 'time')
+        self._keys = []
+        self._shapes = []
+        desc = self._table.coldescrs
+        for name in self._table.colnames:
+            if name in filt:
+                continue
+            self._keys.append(name)
+            shape = desc[name].shape
+            self._shapes.append(1 if len(shape) == 0 else shape[0])
+    
+    def __del__(self):
+        self._file.close()
+    
+    def keys(self):
+        """
+        Return names that may be used to access data in any of the data sources
+        available, whether analyses or inertial particles.
+        """
+        return list(self._scene.get_particles().keys()) + self._keys
+    
+    def shapes(self):
+        """
+        Return the number of components per item of each key in the order 
+        returned by :meth:`keys`.
+        """
+        return self._scene.get_particles().shapes() + self._shapes
+        
+    def _iter_frame_arrays(self, cond=None):
+        """
+        Private. Breaks the file down to its frames, and makes arrays of 
+        them, iteratively. Also allows filtering the frames.
+        
+        Arguments:
+        cond - an optional PyTables condition string to apply to each frame.
+        """
+        query_string = '(time == t)'
+        if cond is not None:
+            query_string = '&'.join([query_string, cond])
+            
+        for t in range(*self._scene.get_range()):
+            yield t, self._table.read_where(query_string)
+    
+    def collect(self, keys, where=None):
+        """
+        Get values of a given key, either some of them or the ones 
+        corresponding to a selection given by 'where'
+        
+        Arguments:
+        keys - a list of keys to take from the data
+        where - a dictionary of derived-results keys, with a tuple 
+            (min,max,invert) as values. If ``invert`` is false, the search 
+            range is between min and max. Otherwise it is anywhere except that.
+        
+        Returns:
+        a list of arrays, in the order of ``keys``.
+        """
+        # Divide the where condition into the trajectory conditions and 
+        # analysis conditions.
+        part_cond = None
+        an_cond = None
+        
+        pkeys = set(self._scene.get_particles().keys())
+        if where is not None:
+            pc_add = []
+            an_cond_add = []
+            
+            for key, rng in where.items():
+                cond_string = gen_query_string(key, rng)                
+                if key in pkeys:
+                    pc_add.append(cond_string)
+                else:
+                    an_cond_add.append(cond_string)
+            
+            if len(pc_add) != 0:
+                part_cond = ' & '.join(pc_add)
+            if len(an_cond_add) != 0:
+                an_cond = ' & '.join(an_cond_add)
+                
+        # Iterate over dual frame, each from the right source using the 
+        # divided conditions.
+        res = dict((k, []) for k in keys)
+        
+        dframe_it = it.izip(
+            self._scene.get_particles()._iter_frame_arrays(part_cond),
+            self._iter_frame_arrays(an_cond))
+            
+        for tr_frm, an_frm in dframe_it:
+            # Cross reference matching rows.
+            tp, p_arr = tr_frm
+            ta, a_arr = an_frm
+            
+            p_trids = p_arr['trajid']
+            a_trids = a_arr['trajid']
+            trajids = set(p_trids) & set(a_trids)
+            
+            # select only those from the two frames:
+            in_p = np.array([True if tr in trajids else False \
+                for tr in p_trids])
+            in_a = np.array([True if tr in trajids else False \
+                for tr in a_trids])
+            
+            if len(in_p) > 0:
+                p_arr = p_arr[in_p]
+            if len(a_arr) > 0:
+                a_arr = a_arr[in_a]
+            
+            # For each dual frame, add the columns of specified keys to the list
+            # of that key's results
+            for k in keys:
+                if k in pkeys:
+                    res[k].append(p_arr[k])
+                else:
+                    res[k].append(a_arr[k])
+        
+        # stack and return.
+        return [np.concatenate(res[k], axis=0) for k in keys]
+    
+    def trajectory_by_id(self, trid):
+        """
+        Retrieves an inertial trajectory with the respective analysis.
+        See ``iter_trajectories`` for the full documentation.
+        
+        Arguments:
+        trid - trajectory ID to fetch.
+        
+        Returns:
+        a Trajectory object with analysis keys added.
+        """
+        traj = self._scene.get_particles().trajectory_by_id(trid)
+        
+        # Trim last point of trajectory to match analysis:
+        kwds = dict((k, v[:-1]) for k, v in traj.as_dict().items())
+        kwds['trajid'] = trid
+        
+        # Fetch by foreign key from analysis:
+        query_string = '(trajid == trid)'
+        arr = self._table.read_where(query_string)
+        
+        # Update into the Trajectory object:
+        for field in arr.dtype.fields:
+            if field not in ['trajid', 'time']:
+                kwds[field] = arr[field]
+        
+        return Trajectory(**kwds)
+        
+    def iter_trajectories(self):
+        """
+        Iterator over inertial trajectories. Since the analysis is structured 
+        around the inertial particles of the internal DualScene, it is possible
+        to iterate those trajectories, adding the corresponding fields of 
+        analysis to the same object. Generates a Trajectory object for each 
+        inertial particle trajectory in the particles file (in no particular 
+        order, but the same order every time on the same PyTables version) and
+        yields it.
+        
+        Note: since analysis works on segments, it truncates the last point of 
+        each trajectory. 
+        """
+        for trid in self._scene.get_particles().trajectory_ids():
+            yield self.trajectory_by_id(trid)

flowtracks/analysis.py

@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+# Created on Mon Aug 11 15:14:21 2014
+"""
+Infrastructure for running a frame-by-frame analysis on a DualScene object.
+The main point of interest here is :func:`analysis`, which performs a segment
+iteration over a :class:`~flowtracks.scene.DualScene` and applies to each 
+a user-selected list of analyzers. Analysers are instances of a 
+:class:`GeneralAnalyser` subclass which implements the necessary methods, 
+as described in the base class documentation.
+
+There is one base class supplied here, :class:`FluidVelocitiesAnalyser`, 
+which ties in the :mod:`flowtracks.interpolation` module for analysing the 
+fluid velocity around a particle from its surrounding tracers.
+"""
+
+import numpy as np, tables
+
+def companion_indices(trids, companions):
+    """
+    Return an array giving for each companion its respective index in the 
+    trajectory ID array, or a negative number if not found.
+    """
+    comp = np.full_like(companions, -1)
+    idx = np.nonzero(trids[:,None] == companions)
+    comp[idx[1]] = idx[0]
+    return comp
+                
+class GeneralAnalyser(object):
+    """
+    This is the parent class for all analysers to be used by :func:`analysis`.
+    It does not do anything but define and document the methods that must be
+    implenmented by the child class (in other words, this class is abstract).
+    Attempting to use its methods will result in a ``NotImplementedError``.
+    """
+    def descr(self):
+        """
+        Need to return a list of tuples, each of the form 
+        (name, data type, row length), e.g. ('trajid', int, 1) 
+        """
+        raise NotImplementedError
+    
+    def analyse(self, frame, next_frame):
+        """
+        Arguments:
+        frame, next_frame - the Frame object for the currently-analysed frame
+            and the one after it, respectively.
+        
+        Returns:
+        a list of arrays, each of shape (f,d) where f is the number of 
+        particles in the current frame, and d is the row length of the
+        corresponding item returned by self.descr(). Each array's dtype also
+        corresponds to the dtype given to it by self.descr().
+        """
+        raise NotImplementedError
+
+class FluidVelocitiesAnalyser(GeneralAnalyser):
+    """
+    Finds, for each particle in the ``particles`` set of a frame, the 
+    so-called *undisturbed* fluid velocity at the particle's position, by
+    interpolating from nearby particles in the ``tracers`` set.
+    """
+    def __init__(self, interp):
+        """
+        Arguments:
+        interp - the Interpolant object to use for finding velocities.
+        """
+        self._interp = interp
+        
+    def descr(self):
+        """
+        Return a list of two tuples, each of the form 
+        (name, data type, row length), describing the arrays returned by 
+        analyse() for fluid velocity and relative velocity.
+        """
+        return [('fluid_vel', float, 3), ('rel_vel', float, 3)]
+    
+    def analyse(self, frame, next_frame):
+        """
+        Arguments:
+        frame, next_frame - the Frame object for the currently-analysed frame
+            and the one after it, respectively.
+        
+        Returns:
+        a list of two arrays, each of shape (f,3) where f is the number of 
+        particles in the current frame. 1st array - fluid velocity. 2nd array
+        - relative velocity.
+        """
+        if frame.particles.has_property('companion'):
+            comp = companion_indices(
+                frame.tracers.trajid(), frame.particles.companion())
+        else:
+            comp = None
+        self._interp.set_scene(frame.tracers.pos(), frame.particles.pos(),
+            frame.tracers.velocity(), comp)
+        vel_interp = self._interp.interpolate()
+        rel_vel = frame.particles.velocity() - vel_interp
+        
+        return [vel_interp, rel_vel]
+    
+def analysis(scene, analysis_file, conf_file, analysers, frame_range=-1):
+    """
+    Generate the analysis table for a given scene with separate data for 
+    inertial particles and tracers.
+    
+    Arguments:
+    scene - a DualScene object representing an experiment with coordinated 
+        particles and tracers data streams.
+    analysis_file - path to the file where analysis should be saved. If the 
+        file exists, it will be cloberred.
+    conf_file - name of config file used for creating the analysis.
+    analysers - a list of GeneralAnalyser subclasses that do the actual
+        analysis work and know all that is needed about output shape.
+    frame_range - if -1 no adjustment is necessary, otherwise see 
+        :meth:`DualScene.iter_segments() <flowtracks.scene.DualScene.iter_segments>`
+    """
+    # Structure the output file:
+    descr = [('trajid', int, 1), ('time', int, 1)]
+    for analyser in analysers:
+        descr.extend(analyser.descr())
+    descr = np.dtype(descr)
+    
+    outfile = tables.open_file(analysis_file, "w", title="Analysis results.")
+    table = outfile.create_table('/', 'analysis', descr)
+    table.attrs['config'] = conf_file
+    table.attrs['trajects'] = scene.get_particles_path()
+    
+    for frame, next_frame in scene.iter_segments(frame_range):
+        length = len(frame.particles)
+        arr = np.empty(length, dtype=descr)
+        arr['trajid'] = frame.particles.trajid()
+        arr['time'] = frame.particles.time()
+        
+        for analyser in analysers:
+            analysis = analyser.analyse(frame, next_frame)
+            this_descr = analyser.descr()
+            
+            for res, desc in zip(analysis, this_descr):
+                arr[desc[0]] = res
+        
+        table.append(arr)
+    
+    # Wrap up and close.
+    table.cols.trajid.create_index()
+    table.cols.time.create_index()
+    outfile.flush()
+    outfile.close()

flowtracks/format_docstrings.py

@@ -0,0 +1,64 @@
+# A Sphinx extension that, in collaboration with the autodoc extension,
+# parses the docstring format used in this project.
+
+import re
+
+# Section processing regexes:
+end_section = re.compile(r'^\s*$')
+section_title = re.compile(r'^\s*(\w+):')
+def_line = re.compile(r'(\w+(?:,\s*\w+)*)\s+-\s+(.+)')
+
+def setup(app):
+    app.connect('autodoc-process-docstring', parse_docstring)
+
+def parse_docstring(app, what, name, obj, options, lines):
+    """
+    Divides the docstring into sections, separated by an empty line in the
+    docstring. If a section starts with a line like "$some_title:", then it is
+    turned into a titled section with $some_title as its title. 
+    
+    A line starting with a python identifier, then a dash, then a definition,
+    is turned into a definition-list item.
+    """
+    out_lines = []
+    place = 0
+    section = []
+    bullet = False
+    for place in range(len(lines)):
+        line = lines[place]
+        
+        # End section: flush into out_lines.
+        m = end_section.match(line)
+        if m is not None:
+            out_lines.extend(section + [line])
+            section = []
+            bullet = False
+            continue
+        
+        if len(section) == 0:
+            # Start of a title-section:
+            m = section_title.match(line)
+            if m is not None:
+                section.extend(['*' + m.group(1) + '*', ''])
+                continue
+        
+        m = def_line.match(line)
+        if m is not None:
+            out_lines.extend(section + [''])
+            section = []
+            bullet = True
+            section.extend(['', '* ``' + m.group(1) + '``: ' + m.group(2)])
+            continue
+        
+        line = line.strip()
+        if bullet:
+            line = '  ' + line
+        section.append(line)
+    
+    # Flush last section:
+    out_lines.extend(section)
+    section=[]
+    
+    # In-place modification of `lines` is needed:
+    lines[:] = out_lines
+

flowtracks/graphics.py

@@ -0,0 +1,142 @@
+# -*- coding: utf-8 -*-
+# Created on Sun Sep 22 16:11:34 2013
+
+"""
+Various specialized graphing routines. The Probability Density Function 
+graphing is best accessed by calling :func:`pdf_graph` on the raw data, but
+you can generate the PDF from the data separately (e.g. using 
+:func:`pdf_bins`) and calling :func:`generalized_histogram_disp` on the 
+result.
+
+The other facility here is a function to plot a time-dependent 3D vector as
+3 component subplots, which is another customary presentation in fluid 
+dynamics circles. See :func:`plot_vectors`.
+"""
+
+import numpy as np, matplotlib.pyplot as pl
+
+def pdf_bins(data, num_bins, log_bins=False):
+    """
+    Generate a PDF of the given data possibly with logarithmic bins, ready for
+    using in a histogram plot.
+    
+    Arguments:
+    data - the samples to histogram.
+    bins - the number of bins in the histogram.
+    log_bins - if True, the bin edges are equally spaced on the log scale, 
+        otherwise they are linearly spaced (a normal histogram). If True, 
+        ``data`` should not contain zeros.
+    
+    Returns:
+    hist - num_bins-lenght array of density values for each bin.
+    bin_edges - array of size num_bins + 1 with the edges of the bins including
+        the ending limit of the bins.
+    """
+    if log_bins:
+        data = data[data > 0] 
+        minv = np.min(data)
+        bins = np.logspace(np.log10(minv), np.log10(data.max()), num_bins + 1)
+    else:
+        bins = num_bins
+    
+    hist, bin_edges = np.histogram(data, bins=bins, density=True)
+    return hist, bin_edges
+
+def generalized_histogram_disp(hist, bin_edges, log_bins=False, 
+    log_density=False, marker='o'):
+    """
+    Draws a given histogram  according to the visual custom of the fluid 
+    dynamics community.
+    
+    Arguments:
+    hist - an array containing the number of values (or density) for each bin.
+    bin_edges - the start value of each bin, same length as ``hist``.
+    log_bins - indicates that the bin edges are log-spaced.
+    log_densify - Show the log of the probability density value. May cause 
+        problems if ``log_bins`` is True.
+    marker - marker style for matplotlib.
+    
+    Returns:
+    the list of lines drawn, Matplotlib objects.
+    """
+    if log_bins:
+        plt = pl.loglog if log_density else pl.semilogx
+    else:
+        plt = pl.semilogy if log_density else pl.plot
+        
+    lines = plt(bin_edges, hist, marker)
+    pl.ylabel("Probability density [-]")
+    
+    return lines
+    
+def pdf_graph(data, num_bins, log=False, log_density=False, marker='o'):
+    """
+    Draw a PDF of the given data, according to the visual custom of
+    the fluid dynamics community, and possibly with logarithmic bins.
+    
+    Arguments:
+    data - the samples to histogram.
+    bins - the number of bins in the histogram.
+    log - if True, the bin edges are equally spaced on the log scale, otherwise
+        they are linearly spaced (a normal histogram). If True, ``data`` should
+        not contain zeros.
+    log_density - Show the log of the probability density value. Only if log 
+        is False.
+    marker - override the circle marker with any string acceptable to 
+        matplotlib.
+    """
+    hist, bin_edges = pdf_bins(data, num_bins, log)
+    generalized_histogram_disp(hist, bin_edges[:-1], log, log_density,
+        marker='-' + marker)
+
+def plot_vectors(vecs, indep, xlabel, fig=None, marker='-', 
+    ytick_dens=None, yticks_format=None, unit_str="", common_scale=None,
+    arrows=None, arrow_color=None):
+    """
+    Plot 3D vectors as 3 subplots sharing the same independent axis.
+    
+    Arguments:
+    vecs - an (n,3) array, with n vectors to plot against the independent
+        variable.
+    indep - the corresponding n values of the independent variable.
+    xlabel - label for the independent axis.
+    fig - an optional figure object to use. If None, one will be created.
+    ytick_dens - if not None, place this many yticks on each subplot, instead
+        of the automatic tick marks.
+    yticks_format - a pyplot formatter object.
+    unit_str - a string to add to the Y labels representing the vector's units.
+    arrows - an (n,3) array of values to represent as vertical arrows attached 
+        to each trajectory point.
+    arrow_color - a matplotlib color spec for the arrow bodies.
+    
+    Returns:
+    fig - the figure object used for plotting.
+    """
+    fig = pl.figure(None if fig is None else fig.number)
+    u = np.zeros(vecs.shape[0])
+    
+    labels = ("X " + unit_str, "Y" + unit_str, "Z" + unit_str)
+    for subplt in range(3):
+        pl.subplot(3,1,subplt + 1)
+        pl.plot(indep, vecs[:,subplt], marker)
+        pl.gca().get_xaxis().set_visible(False)
+        pl.grid()
+        pl.ylabel(labels[subplt])
+        
+        if yticks_format is not None:
+             pl.gca().get_yaxis().set_major_formatter(yticks_format)
+        
+        if common_scale is not None:
+            pl.ylim(np.r_[-common_scale, common_scale] + vecs[:,subplt].mean())
+        if ytick_dens is not None:
+            loc, _ = pl.yticks()
+            pl.yticks(np.linspace(vecs[:,subplt].min(), vecs[:,subplt].max(), 
+                    ytick_dens))
+        
+        if arrows is not None:
+            pl.quiver(indep, vecs[:,subplt], u, arrows[:,subplt], 
+                scale=30, width=1e-3, color=arrow_color)
+    
+    pl.gca().get_xaxis().set_visible(True)
+    pl.xlabel(xlabel)
+    return fig