Welcome to pyPSCF’s documentation!

Install

pyPSCF is written in python 3 so the first thing to do is to… well, install python.

• Linux: it should be already installed. However, depending on your distribution, you may have python 2 by default. We do not ensure the compatibility.
• Windows/macOS: just use python throught anaconda. It’s way more easier. But use anaconda for python 3.

Hysplit

The GUI has the ability to compute HYSPLIT backtrajectories. To do so, you will need Hysplit installed.

Hysplit is freely available for Windows, Linux and Mac on the NOAA website.

You may also need the NCEP reanalyse GDAS, available in by the NOAA.

pyPSCF

Install latest release version via pip

pip install pyPSCF

Install latest release version via conda

conda install -c webersa pypscf

Mannual install (not recommanded)

pyPSCF use the following library:

• matplotlib
• numpy
• scipy
• pandas
• cartopy

The first fourth are quite heavily used and easy to install (or already installed). You can use pip to install them:

pip install matplotlib numpy scipy pandas

Cartopy is a bit tricky to install as it requires an extra library: GEOS. In debian related system, install it via:

sudo apt install libgeos-3.6.2 libgeos++-dev

Due to some cartopy related issue, you may also need cython. Install it via conda or pip such as:

pip install cython
pip install cartopy

Using the GUI

In order to be available for a broader audience, a GUI is also provided. However, the GUI is not part of the pypi or conda package yet. You have to download it mannually from the git repo ( direct link ).

There are several way to run the GUI, depending on what you are familiar with.

• From the terminal: navigate where the GUI.pyw file is, then enter

python3 GUI.pyw

• Using spyder/ipython

%run GUI.pyw

• Graphically: simply double click on GUI.pyw. It may work. Maybe.

If it doesn’t start, ensure that you are running python 3 and not python 2.

Initialization

The script looks for files in parameters named localParamBackTraj.json, localParamPSCF.json, locationStation.json. The package gives you the same three file, with a _default.json extension. Copy and rename them in order to have the correct one in parameters:

parameters
├── SETUP_backTraj.CFG
├── localParamBackTraj.json
├── localParamBackTraj_default.json
├── localParamPSCF.json
├── localParamPSCF_default.json
├── locationStation.json
└── locationStation_default.json

Compute the back-trajectories

Hysplit

The back-trajectories have to be computed before running the PSCF script. We use here the HYSPLIT program from the NOAA. As HYSPLIT is a relatively big software with many option and configuration, we developed a tool to compute the back trajectory in a easy way. However, you still need the HYSPLIT program. You can found it at http://ready.arl.noaa.gov/HYSPLIT.php.

GUI description

Once the script starts, you should see the window presented in the figure above. Navigate to the Back-trajectory tab on the top if it is not already open. This window presents the different parameters use to compute the back-trajectories. Let’s describe each of its field.

• Button frame
  • Run Back-traj: Save the parameters show in this tab in parameters/localParamBackTraj.json then compute the back-trajectories with theses parameters.
  • Save BackTraj: Save the parameters in the parameters/localParamBackTraj.json file without running the computation.
  • Exit: Quit the GUI without saving the parameters.
• Meteo (GDAS) directory: select the path to the GDAS files. GDAS is a file format uses to store meteorological data and are freely available from the NOAA website or ftp.
• Hysplit directory: select the root path of the Hysplit directory’s installation. It should contain the subdirectories working, exec, script etc.
• Output directory: select where the back-trajectories files will be save.
• Station frame
  • Station: select the desired reference point. If the station is not in the list you have to add yourself the station in the parameters/locationStation.json file.
  • Longitude/Latitude: enter the longitude/latitude of the station. It should be updated automatically with the selection of the station.
  • Altitude: enter the altitude (in meter from the surface) of the back-trajectory starting point.

Development

This tool is a work-in-progress tool. Feel free to contribute. Here is a non-exhaustif list of TODO:

• add tests
• add examples
• expand documentation
• multi-site PSCF
• add windrose tool in the GUI
• add a propor setup.py file… and use pypi
• …

Code is hosted at https://gricad-gitlab.univ-grenoble-alpes.fr/webersa/pyPSCF/ .

Issues

You can submit issues or suggestion directly throught github using the issue tracker

Install the git version

• Fork repository:

  git clone https://gricad-gitlab.univ-grenoble-alpes.fr/webersa/pyPSCF.git
  cd pyPSCF
  python3 -m venv venv  # create a virtual environment
  python3 -m pip install -r requirements.txt  # install the requirements
  source venv/bin/activate
  

• Create a branch which fix a given issue

• Submit pull requests

pyPSCF

pyPSCF package

Submodules

pyPSCF.BackTrajHysplit module

class pyPSCF.BackTrajHysplit.BT(station=None, lat=None, lon=None, alt=None, dateMin=None, dateMax=None, stepHH=None, hBT=None, dirOutput=None, dirGDAS=None, dirHysplit=None, cpu=None)

Bases: object

Compute the back-trajectory for the given station between dateMin and dateMax.

Parameters:

• station (str) – The station
• lat (float) – Latitude of the starting point
• lon (float) – Longitude of the starting point
• alt (float) – Altitude of the starting point
• dateMin (str) – Starting date “YYYY-MM-DD HH:MM”
• dateMax (str) – Ending date “YYYY-MM-DD HH:MM”
• stepHH (int) – Interval between 2 starting hour
• hBT (int (negative)) – Number of hour to go in the past
• dirOutput (str) – path to the output directory
• dirGDAS (str) – path to the GDAS meteorological directory
• dirHysplit (str) – path to the hysplit root directory
• cpu (int) – Number of CPU to use. Beware, each of them is use to its maximum.

compute_BT(date, filename)

Compute the BT for the given datetime

Parameters:

• date (datetime) – The datetime to compute
• filename (str) – The name of the output file

compute_BTs()

Compute all the BT from dateMin to dateMax

get_currentFile(station, d)

Return the name of the file given a station and a date

Parameters:

• station (str) – The name of the station
• d (datetime) – The datetime of the backtrajectory

Returns:

currentFile – traj_{station}_{YYMMDDHH}

Return type:

str

run()

Run compute_BTs one time per cpu each in a subprocess.

update_date(d, stepHH)

Update the date by a given step

Parameters:

• d (datetime) – Previous datetime
• stepHH (int) – Number of hour to go forward

Returns:

datetime – d + stepHH

Return type:

datetime

write_CONTROL_file(curDate, currentFile)

Create the correct CONTROL file for the given date

Parameters:

• curDate (datetime) – The datetime to compute
• currentFile (str) – The name of the file

write_SETUP_file()

Well… write the setup file

pyPSCF.pyPSCF module

class pyPSCF.pyPSCF.PSCF(station, specie, lat0, lon0, folder, prefix, add_hour, concFile, dateMin, dateMax, percentile=75, threshold=None, wfunc=True, wfunc_type='auto', resQuality='110m', smoothplot=True, mapMinMax=None, cutWithRain=True, hourinthepast=72, plotBT=True, plotPolar=True, pd_kwarg=None)

Bases: object

Parameters:

• station (str) – The name of the station.
• specie (str) – The specie to study. Must be specified in the concentration file.
• lat0 (float) – The latitude of the starting point.
• lon0 (float) – The longitude of the starting point.
• folder (str, path) – Path to the backtrajectories files.
• prefix (str) – Prefix of all backtrajectories. Something like ‘traj_OPE_’
• add_hour (list or array) –

  List of backtrajecories starting hours around the reference hour. Example: add_hour=[-3,0,3] and reference hour of 2017-03-15 09:00, the following backtrajectories will be used:

  • 2017-03-15 06:00
  • 2017-03-15 09:00
  • 2017-03-15 12:00

  All theses backtrajecories are associated to the concentration of the refrence hour.

• concFile (str, path.) – The path to the concentration file.
• dateMin (str or datetime object) – The minimal date to account.
• dateMax (str or datetime object) – The maximal date to account.
• percentile (int, default 75) – The percentile to use as threshold.
• threshold (float, default None) – The concentration threshold. It overrides the percentile value.
• wfunc (boolean, default True) – Either or not use a weighting function.
• wfunc_type ("manual" or "auto", default "auto") – Type of weighting function. “auto” is continuous.
• mapMinMax (dict) – Dictionary of minimun/maximum of lat/lon for the map. Example: mapMinMax = {‘latmin’: 37.5, ‘latmax’: 60, ‘lonmin’: -10, ‘lonmax’: 20} This example is the default (France centered).
• cutWithRain (boolean, default True) – Either or not cut the backtrajectory to the last rainning date.
• hourinthepast (integer, default 72) – Number of hour considered for the backtrajectory life.
• resQuality ('110m' or '50m', default '110m') – The quality of the map.
• smoothplot (boolean, default True) – Use a gaussian filter to smooth the map plot.
• plotBT (boolean, default True) – Either or not plot all the backtraj in a new axe.
• plotPolar (boolean, default True) – Either or not plot the direction the distribution of the PSCF in a polar plot.

Other Parameters:  

pd_kwarg (dict, optional) – Dictionary of option pass to pd.read_csv to read the concentration file. By default, pd_kwarg={‘index_col’=0, ‘parse_date’=[‘date’]}.

extractBackTraj()

Sum up back trajectories file into a pandas DataFrame according to the class parameters.

Returns:df Return type:pd.DataFrame

onclick(event, plotType)

Find the BT which pass through the clicked cell.

plot_PSCF()

Plot the PSCF map.

plot_PSCF_polar()

Plot a polar plot of the PSCF

plot_backtraj()

Plot a map of all trajectories.

run()

Run the PSCF model and add 4 attributes to the PSCF object:

Returns:

• ngrid_ (ndarray) – The number of end-point of back-trajectories in each grid cell
• mgrid_ (ndarray) – The number of en-point of back-trajectories in each grid cell accociated with concentration > self.concCrit
• PSCF_ (ndarray) – mgrid/ngrid, the PSCF data.
• trajdensity_ (ndarray) – log_10(ngrid)

toRad(x)

Module contents

Indices and tables

• Index
• Module Index
• Search Page