Skip to content

mkstratos/stj_pv

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

STJ-PV

A subtropical jet finding framework, including the STJPV method introduced in

Maher, et al. (2019): Is the subtropical jet shifting poleward? Climate Dynamics.

DOI

Documentation Status GitHub Code DOI

Running the code

We reccomend:

  • Anaconda Python distribution
  • Python >= 3.6 (>= 3.5 required)
  • Creating a new Anaconda environment (so package versions do not conflict between this and other projects)

SETUP

Create a new Anaconda environment using:

conda create -n stjpv python

Activate your new environment with

conda activate stjpv

Then install the required packages as below.

Installing STJ_PV

Clone (or fork) this repository

git clone git@github.com:mkstratos/stj_pv.git

Enter the code's top level directory

cd stj_pv

Install the prerequisites conda install --file requirements.txt -c conda-forge

Note: basemap==1.0.7 available from Anaconda is not compatible with Python >= 3. Thus the conda-forge channel with v1.1.0 must be used.

Install this module (STJ_PV) in development mode (-e)

pip install -e .

Note the trailing "." this will use the setup.py file to install this module, and allow it to be imported using import STJ_PV or from STJ_PV import run_stj for example

Testing with sample data

Enter the top-level code directory, and try the sample case:


cd stj_pv/STJ_PV
python run_stj.py --sample

This will output a file called: NCEP_NCAR_DAILY_STJPV_pv2.0_fit6_y010.0_yN65.0_zmean_2009-01-23_2009-01-25.nc which has the latitude and theta position, and intensity in northern and southern hemispheres, each their own variable.

Required Python modules

Required for running the jet metric:


dask
netCDF4
numpy
psutil
PyYAML
scipy
xarray

Required for diagnostic plots:


basemap
matplotlib
seaborn
pandas

Data dependencies


Monthly data is recommended but daily data is an option.

Required fields on isobaric levels if isentropic potential vorticity is not available:

  • zonal wind (u)
  • meridional wind (v)
  • atmospheric temperature (T)

If isobaric potential vorticity is available, then on isobaric levels:

  • zonal wind (u)
  • atmospheric temperature (T)
  • potential vorticity (pv)

If isentropic potential vorticity is available, then on isentropic levels:

  • zonal wind (u)
  • potential vorticity (pv)

Code structure and organization:


The highest level code is run_stj.py. Within this file the following changes are required:

  1. Two YAML configuration files are used
    • STJ config (for properties of jet finding metric)
    • The data configuration file is set within the STJ configuration file.
    • Examples of both can be found in the conf/ directory.
  2. Set start and end dates
  3. Select sensitivity or normal run

STJ finding Configuration: stj_config_default.yml

Variable Name Description
data_cfg Location of data config file
freq Input data frequency
zonal_opt Output zonal mean (if 'mean') or individual longitude positions (if != 'mean')
method Jet metric to use. Included are STJPV and STJUMax
log_file Log file name and location. If {} is included within this string (e.g. stj_find_{}.log) the current time (from datetime.now()) at which the finder was initialised will be put into the file name (e.g. stj_find_2017-11-02_14-08-32.log)
pv_value Potential vorticity level on which potential temperature is interpolated to find the jet (if using STJPV metric)
fit_deg Also for STJPV metric, use this degree (integer) polynomial to fit the potential temperature on the pv_value surface
min_lat Minimum latitude boundary (equatorward) on which to perform interpolation
max_lat Maximum latitude boundary (poleward) on which to perform interpolation
update_pv If isentropic PV (IPV) file(s) exist already, re-create them if this is set to True. If not, use files that exist
year_s Year to start jet finding (Jan 1 of this year)
year_e Year to end jet finding (Dec 31 of this year)
Dates may also be set in run_stj.main() function
poly Polynomial to use, one of 'cheby', 'legendre', or 'poly' for Chebyshev, Legendre, or polynomial fit respectively
See comments within conf/stj_config_default.yml for further details

Data configuration: data_config_default.yml

Variable Name Description
path Absolute path of input data
wpath If path is not writeable, absolute path to directory where IPV data can be written
short_name String name to call this dataset
single_var_file Each variables has its own file (if True)
single_year_file Each year has its own file (if True)
file_paths Names (within path) of input / output files for atmospheric variables
If single_var_file==True then file_paths has: uwnd, vwnd, tair (in), and ipv (output)
If single_var_file==False, then file_paths has: all (in), and ipv (output)
lon Name within netCDF file of 'longitude' variable
lat Name within netCDF file of 'latitude' variable
lev Name within netCDF file of 'level' variable
time Name within netCDF file of 'time' variable
ztype Type of levels (pressure, potential temperature, etc.)
pfac Multiply pressure by this (float) to get units of Pascals
uwnd Name within netCDF file of zonal wind variable
vwnd Name within netCDF file of meridional wind variable
tair Name within netCDF file of atmospheric temperature variable
ipv Name within netCDF file of isentropic pv variable

See comments within conf/data_config_default.yml for further details

How the STJPV metric works

  1. The run_stj.main() function creates a run_stj.JetFindRun object, based on configuration parameters.

  2. Start and end dates are set, and the run_stj.JetFindRun.run() method starts the run, where configuration files are checked then the selected metric computes the jet position in each hemisphere at each time.

  3. If Isentropic PV input data does not exist, this is created and written as defined in the data configuration file

  4. When using the STJPV metric the jet is identified in the following process:

    1. Interpolate to obtain potential temperature ($\Theta$) as a function of latitude on a surface of constant IPV, chosen in configuration file

    2. Numerically compute meridional gradient of this surface using a polynomial fit (Chebyshev polynomials of degree 8 used by default)

    3. The jet location is determined to be at a relative maximum in the northern hemisphere, or minimum in the southern hemisphere of the meridional gradient of potential temperature on the PV surface at each time and longitude

    4. If multiple extrema exist, the jet latitude has the largest zonal wind shear between the potential vorticity surface and the lowest available level (called the "surface")

    5. The zonal mean jet position for each time is then computed as the zonal median of the identified positions at all longitudes, ignoring those longitudes where no position is identified, if the zonal_opt is set to "mean" in the configuration, otherwise the position is output at each longitude