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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

To change the trajectories array.

startdate

Return the starting date of the trajectories

variables

Return the names of the variables

write(filename, fileformat='netcdf')[source]

Method to write the trajectories to a file

write_ascii(filename, gz=False, digit=3, mode='w')[source]

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.
  • 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')[source]

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, no_tmp_dir=False)[source]

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.
  • no_tmp_dir (bool, optional) – If set to True, do not create temporary folder. Useful only for special version of lagranto, and if the system as no tmp filesystem.
caltra(startdate, enddate, filename='', outfile='', **kwargs)[source]

Compute trajectories for the given startdate

clear()[source]

Remove the output directory

create_startf(date, specifier, filename='', tolist=False, **kwargs)[source]

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)[source]

Return the density of trajectories

run(caltra_kw=None, trace_kw=None, startf_kw=None, **kwargs)[source]

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)[source]

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)[source]

Perform selection of trajectories

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

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)[source]

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 –