==============================
The trajectory_compute module
==============================
Introduction
-------------
The objective of this code is to construct sets of back and forward trajectories that pass through specific regions, or objects, at a reference time, and 'families' of such sets with different reference times.

The basic class is :py:class:`trajectory_compute.Trajectories`. 
However, the class :py:class:`trajectory_compute.Trajectory_Family` is more powerful; it produces a related set, or family, of trajectories with sequential reference times so that objects which interact can be identified. Results can be plotted and animated using :doc:`trajectory_plot`.

Defining Objects
----------------
As of version 0.2, the objects are specified by providing two functions:

ref_func(dataset, time_index)
    Function to return reference trajectory positions and labels. This has two parameters: dataset, a Netcdf file handle containing data at the reference time, and time_index, the index of required time in file. It must return three variables. An array giving positions of trajectory origin points, a corresponding array of point labels (integers) and an integer giving the total number of objects.
in_obj_func(traj, tr_time, obj_ptrs)
    Function to determine which points are inside an object. This is passed a trajectory object and returns a logical array selecting points which are inside objects, and a data array corresponding to the object data criterion (e.g. cloud water). If it is also passed a time index and logical array selecting an object, it these apply to this time and object, otherwise the whole trajectory data array is used.

Both are passed a dictionary of keyword arguments to these functions via kwargs.

An example pair of functions has been provided: :py:func:`trajectory_compute.trajectory_cloud_ref` and :py:func:`trajectory_compute.in_cloud`.

.. topic:: New at 0.4 

    An alternative pair based upon George Efstathiou's code to study coherent structures in the boundary layer is included. See :py:func:`trajectory_compute.trajectory_cstruct_ref` and :py:func:`trajectory_compute.in_cstruc` (which both use :py:func:`trajectory_compute.cstruct_select`).


An example of their use is::

    import glob
    import os
    import numpy as np
    from trajectory_compute import *

    dir = 'C:/Users/paclk/OneDrive - University of Reading/traj_data/r16/'
    files = glob.glob(dir+"diagnostics_3d_ts_*.nc")
    files.sort(key=file_key)
    ref_prof_file = glob.glob(dir+'diagnostics_ts_*.nc')[0]
    dt = 60
    first_ref_time = 50*dt
    last_ref_time =  90*dt
    tr_back_len = 40*dt
    tr_forward_len = 30*dt
    ref = 40
    kwa={'thresh':1.0E-5}
    
    tfm = trajectory_family(files, ref_prof_file, \
                     first_ref_time, last_ref_time, \
                     tr_back_len, tr_forward_len, \
                     100.0, 100.0, 40.0, \
                     trajectory_cloud_ref, in_cloud, \
                     kwargs=kwa )
                     
Using Trajectories objects
--------------------------

The most important attributes of the Trajectories class are: trajectory, data, traj_times, labels and nobjects. The trajectory array gives the trajectory positions, and is dimensioned [nt, m, 3] where nt is total number of times, m the number of trajectory points at a given time and last index gives x,y,z (index 0, 1, 2). The data array contains the associated model variables interpolated to the trajectory and is dimensioned [nt, m, n] where n is the number of variables in variable_list. 

The variable list can be supplied to the trajectory_family and trajectory classes but default to the following::

    variable_list = { \
          "u":r"$u$ m s$^{-1}$", \
          "v":r"$v$ m s$^{-1}$", \
          "w":r"$w$ m s$^{-1}$", \
          "th":r"$\theta$ K", \
          "p":r"Pa", \
          "q_vapour":r"$q_{v}$ kg/kg", \
          "q_cloud_liquid_mass":r"$q_{cl}$ kg/kg", \
          }

Note this is a dictionary with keys the NetCDF variable names in the MONC output, pointing to format strings for plotting. Unfortunately, the data array is not in the same order as the variable list, due to a quirk in the way python orders dictionaries. The :py:meth:`trajectory_compute.Trajectories.var()` method is provided to convert a variable name to an index.

.. topic:: New at 0.4 

    Some derived variables can be specfied, such as 'th_L'. 
    Variables can have have operators (such as spatial derivatives, deviation from mean) applied.
    See documentation for :py:func:`trajectory_compute.get_data` for more detail. 
    Users are encouraged to expand this functionality, or suggest required expansions.

The traj_times array dimensioned[nt] with times corresponding to trajectory.

The labels array is dimensioned [m] and identifies which object trajectory points and associated data with labels 0 to nobjects-1. Thus, in a trajectory object traj, the points corresponding to object iobj can be found using traj.trajectory[:, traj.labels==iobj, :], and the associated data traj.data[:, traj.labels==iobj, :].


Detailed Module Contents
------------------------
The entire module is documented below.

.. automodule:: trajectory_compute
   :member-order: bysource
   :members: