Basic examples — Lagranto 0.1 documentation

# Basic examples

In a first step, let’s simply read the trajectories:

    >>> from lagranto import Tra
    >>> filename = 'lsl_20110123_10'
    >>> trajs = Tra()
    >>> trajs.load_ascii(filename)

or to read a netcdf file:

    >>> filename = 'lsl_20110123_10.4'
    >>> trajs.load_netcdf(filename)

The proprieties of the trajectories can be shown as follow::

      >>> print(trajs)
      24 trajectories with 41 time steps.
      Available fields: time/lon/lat/p/Q/RH/TH/BLH
      total duration: -14400.0 minutes
      >>> print(trajs.variables())
      ['time', 'lon', 'lat', 'p', 'Q', 'RH', 'TH', 'BLH']
      >>> print(trajs['Q'].shape)
      (24, 41)

# DocStrings

## Tra

class `lagranto.` `Tra`(filename='', usedatetime=True, array=None, **kwargs)

  Class to work with LAGRANTO output.

  Read trajectories from a LAGRANTO file and return a structured numpy array

  Parameters: | filename (string) – File containing lagranto trajectories usedatetime (bool) – Read times as datetime objects, default True array (structured array) – If defined creates a new Tra object filled with the array
  Returns: | structured array (Tra)
  Return type: | trajs(ntra,ntime) with variables as tuple.

  Examples

      >>>    filename = 'mylslfile.nc'
      >>>    trajs = Tra()
      >>>    trajs.load_netcdf(filename)
      >>>    trajs['lon'][0,:]  # return the longitudes for the first trajectory.

      >>> trajs = Tra(filename)
      >>> selected_trajs = Tra(array=trajs[[10, 20, 30], :])

  Author : Nicolas Piaget, ETH Zurich , 2014
    Sebastiaan Crezee, ETH Zurich , 2014
  `append`(trajs)

    append trajectories

    Parameters: | trajs (single Tra or list of Tra) – Trajectories to concatenate with the current one

    Examples

        >>> files = ['lsl_20001010_00.4', 'lsl_2001010_01.4']
        >>> filename = files[0]
        >>> trajs = Tra(filename)
        >>> newtrajs = [Tra(f) for f in files]
        >>> trajs.append(newtrajs)

  `concatenate`(trajs, time=False, inplace=False)

    To concatenate trajectories together.

    Concatenate trajectories together and return a new object. The trajectories should contain the same variables. if time=False, the number of timestep in each trajs should be the same if time=True, the number of trajectories in each Tra should be the same

    Parameters: | trajs (Tra or list of Tra) – Trajectories to concatenate with the current one time (bool, default False) – if True concatenate along the time dimension inplace (bool, default False) – if True append the trajs to current Tra object and return None
    Returns: | Return a new Tra (trajectories) object
    Return type: | Tra

    Examples

    Create a new Tra object which include trajs and all newtrajs

        >>> files = ['lsl_20001010_00.4', 'lsl_2001010_01.4']
        >>> filename = files[0]
        >>> trajs = Tra(filename)
        >>> newtrajs = [Tra(f) for f in files]
        >>> alltrajs = trajs.concatenate(newtrajs)

    Append newtrajs to trajs

        >>> trajs = Tra(filename)
        >>> newtrajs = [Tra(f) for f in files]
        >>> trajs.concatenate(newtrajs, inplace=True)

  `duration`

    Time duration in minutes.

  `get_array`()

    Return the trajectories array as numpy object

  `initial`

    Give the initial time of the trajectories.

  `load_ascii`(filename, usedatetime=True, msv=-999.999, gz=False)

    Load trajectories from an ascii file

    Parameters:

    usedatetime: bool, default True
      If true return the dates as datetime object
    msv: float, default -999.999
      Change <msv> value into np.nan
    gzip: bool, default False
      If true read from gzip file
  `load_netcdf`(filename, usedatetime=True, msv=-999, unit='hours', **kwargs)

    Load trajectories from a netcdf

    Parameters: | filename (string,) – path to a netcdf file containing trajectories usedatetime (bool, default True) – If True then return time as datetime object msv (float, default -999) – Define the missing value unit (string, default hours) – Define the units of the times (hours, seconds or hhmm) exclude (list of string, default empty) – Define a list of variables to exclude from reading date (datetime or list) – Can be used to select particular dates, for example to read in a single timestep indices (list or tuple) – Can be used to select particular trajectories

  `ntime`

    Return the number of time steps

  `ntra`

    Return the number of trajectories

  `set_array`(array)

    To change the trajectories array.

  `startdate`

    Return the starting date of the trajectories

  `variables`

    Return the names of the variables

  `write`(filename, fileformat='netcdf')

    Method to write the trajectories to a file

  `write_ascii`(filename, gz=False, digit=3, mode='w')

    Write the trajectories in an ASCII format

    > Parameters:

    > filename : string
    >   filename where the trajectories are written
    > mode : string, default w
    >   define the mode for opening the file. By default in write mode (‘w’), append (a) is another option

    Parameters: | filename (string) – filename where the trajectories are written mode (string, default w) – define the mode for opening the file. By default in write mode (‘w’), append (‘a’) is another option. gz (boolean, default False) – If true write the file as a gzip file digit (int, default 3) – Number of digit after the comma to use for lon, lat; Only 3 or 2 digits allowed

  `write_netcdf`(filename, exclude=None, unit='hours')

    Write the trajectories in a netCDF file

    Parameters: | trajs (Tra) – A Tra instance filename (string) – The name of the output file exclude (list, optional) – A list of variables to exclude unit (string, optional) – The unit of the dates, can be hours, seconds or hhmm

## LagrantoRun

class `lagranto.` `LagrantoRun`(dates, workingdir='.', outputdir='.', startf='startf.4', lslname='lsl_{:%Y%m%d%H}.4', tracevars='', field='', version='cosmo', linkfiles=None, nprocesses=10, sdate=None, fresh=False, cmd_header=None)

  Perform Lagranto calculation.

  Parameters: | dates (list) – list of (startdate, enddate) tuple workingdir (string, optional) – path to the model output directory, default to current outputdir (string, optional) – path to the trajectory utput directory, defautl to current startf (string, optional) – name of the startf to use (or to create), default to startf.4 The format parameter date can be used, for ex: startf_{date:%Y%m%d%H}.4 lslname (string, optional) – name of the lsl file, define its type, default to lsl_{:%Y%m%d%H}.4 tracevars (string, optional) – name of a tracevars file as used by trace, default to none field (string, optional) – name of a single field to trace, default to none version (string, optional) – name of the model version to use, currently only cosmo (default) linkfiles (function, optional) – function used to overwrite link_files in run. Should be used if COSMO output is not standard netcdf nprocesses (int, optional) – Number of processes used when running in parallel, default to 10 sdate (datetime object,) – Starting date of the simulation; useful if files are named in forecast mode fresh (bool, optional) – Fresh start. Remove output directory first. cmd_header (string, optional) – Change the header using for running the command; see `run_cmd` help for more details.

  `caltra`(startdate, enddate, filename='', outfile='', **kwargs)

    Compute trajectories for the given startdate

  `clear`()

    Remove the output directory

  `create_startf`(date, specifier, filename='', tolist=False, **kwargs)

    Create a file with the starting position of the trajectories.

    Parameters: | date (datetime) – date for which the startf date is produced specifier (string) – detailed description of starting positions; (see LAGRANTO documentations for more details) filename (string) – filename where starting positions are saved; the default is defined by LagrantoRun Can make use of the format parameter date, for example: startf_{date:%Y%m%d%H}.4 tolist (bool) – If the starting position should be saved as a list of points; Useful if the same file is used for different starting times kwargs (dict) – key, value options, possible values are listed bellow; cmd_header: header to add to the shell command; (see run_cmd for more details) options: list of options to pass to the startf function; (see the LAGRANTO documentation for more details)

  `density`(inpfile=None, outfile=None, **kwargs)

    Return the density of trajectories

  `run`(caltra_kw=None, trace_kw=None, startf_kw=None, **kwargs)

    Run caltra, trace, and/or create_startf.

    Run single_run for each dates tuple See single_run description for more details.

    Parameters: | caltra_kw (dictionary) – Arguments to pass to the caltra function trace_kw (dictionary) – Arguments to pass to the trace function startf_kw (dictionary) – Arguments to pass to the create_startf function kwargs – Arguments to pass to the single_run function
    Returns: | A list of single_run result
    Return type: | list

  `run_parallel`(caltra_kw=None, trace_kw=None, startf_kw=None, nprocesses=None, **kwargs)

    Run caltra, trace, and/or create_startf in parallel.

    Run single_run for each dates tuple using multiprocessing.Pool. See single_run description for more details.

    Warning: If you use run_parallel with create_startf and if the starting file is not a list, be sure that every starting file has a different name, for example doing as follow:

        >>> LagrantoRun(startf='startf_{date:%Y%m%d_%H.4}', ...)

    Parameters: | caltra_kw (dictionary) – Arguments to pass to the caltra function trace_kw (dictionary) – Arguments to pass to the trace function startf_kw (dictionary) – Arguments to pass to the create_startf function nprocesses (int,) – Number of processors to use kwargs – Arguments to pass to the single_run function
    Returns: | A list of single_run results
    Return type: | list

  `select`(inpfile=None, outfile=None, **kwargs)

    Perform selection of trajectories

  `single_run`(sd, ed, caltra_kw=None, trace_kw=None, startf_kw=None, type='both', debug=False, **kwargs)

    Run caltra, trace and/or create_startf for a given starting date

    Compute a trajectory set using caltra, trace and/or create_startf in a temporary directory. Need a working installation of LAGRANTO.

    If caltra, trace or create_startf return a error, single_run return a LagrantoException error with the path of the temporary directory. In this case, the temporary directory is not deleted.

    Parameters: | sd (datetime) – Starting date of the trajectory ed (datetime) – Ending date of the trajectory caltra_kw (dictionary) – Arguments to pass to the caltra function trace_kw (dictionary) – Arguments to pass to the trace function startf_kw (dictionary) – Arguments to pass to the create_startf function type (string (default both)) – Define the type a run to perform: both: caltra + trace caltra: caltra trace: trace all: create_startf + caltra + trace create: create_startf + caltra debug (Boolean) – If True raise LagrantoException instead of return it as string kwargs (dictionnary) – Arguments to pass to the link_files function
    Returns: | output of caltra, trace and/or create_startf
    Return type: | str

  `trace`(date, filename='', outfile='', tracevars='', tracevars_content='', field='', **kwargs)

    Trace variable along a trajectory.

    Trace meteorological fields along trajectories

    Parameters: | date (datetime object) – starting date of the trajectories to trace filename (string, optional) – If not specified use LagrantoRun.lslname outfile (string, optional) – If not specified same as filename tracevars (string, optional) – Name of the file with the field to trace; If not specified use LagrantoRun.tracevars tracevars_content (string, optional) – Content of the tracevars file; ”“”n QV 1000. P 1n PV 1. T 1n “”“ field (string,) – Specify a field to trace as follow: QV 1. kwargs –