A Python3 post processing tool for TIE-GCM
Project description
TIEGCMPY
tiegcmpy is a tool used for TIE-GCM post processing and plot generation.
Updated documentation on readthedocs
https://tiegcm-docs.readthedocs.io/en/latest/
Installation
pip install tiegcmpy
Requrements
- Python >= 3.8.0
- Python pip >= 23.2.1
- cartopy >= 0.21.1
- numpy >= 1.24.4
- matplotlib >= 3.7.2
- xarray >= 2023.1.0
Usage
tiegcmpy can be run in two modes:
-
Mode: API
For use in custom python scripts or juypter notebooks
-
Mode: Command Line Interface
For a command line interface with arguments
a) Single Plot
Load database for generation of a single plot to a single file
b) Multiple Plot
Load database for generation of multiple plots to a single or multiple files
Mode: API
Importing tiegcmpy
import tiegcmpy as ty
Load datasets
a) Loading a single dataset
ty.load_dataset(directory, dataset_filter)
b) Loading multiple datasets
ty.load_datasets(directory, dataset_filter)
Plot generation
The following plots can be made:
a)Latitude vs Longitude plots: plt_lat_lon
b)Pressure level vs Variable Value plots: plt_lev_var
c)Pressure level vs Longitude pltos: plt_lev_lon
d)Pressure level vs Latitude plots: plt_lev_lat
e)Pressure level vs Time plots: plt_lev_time
f)Latitude vs Time plots: plt_lat_time
Example:
ty.plt_lat_lon(datasets, variable_name, level, localtime)
Look at functionality section for list of all plot types with required and optional arguments.
Mode: CLI (Command Line Interface)
Single Plot
Example:
tiegcmpy --plot_type {plot_type} -dir {directory of datasets} --dataset_filter {primary or secondary files} --output_format {format of output plot} --[Other optional arguments for specific plots]
Multiple Plots
Option 1: Initiate Interactive mode to generate multiple plots from different datasets
tiegcmpy -rec
Wait for the command input request.
Entering Interactive Mode
Enter command or 'exit' to terminate:
Type the arguments to request a plot with the dataset and output file information
--plot_type {plot_type} -dir {directory of datasets} --dataset_filter {primary or secondary files} --output_format {format of output plot} --[Other optional arguments for specific plots]
Wait for input request. Type another command or 'exit'
Option 2: Load dataset for multiple plot generation to multiple files
tiegcmpy -rec -dir {directory of datasets} --dataset_filter {primary or secondary files}
Loads datasets into memory and requests for input.
Entering Interactive Mode
Loading datasets globally.
Enter command or 'exit' to terminate:
Type the arguments to request a plot with the output file information
--plot_type {plot_type} --output_format {format of output plot} --[Other optional arguments for specific plots]
Wait for input request. Type another command or 'exit'
Option 3: Load dataset for multiple plot generation to a single PDF file
tiegcmpy -rec -dir {directory of datasets} --dataset_filter {primary or secondary files} --multiple_output {Output PDF file name}
Loads datasets into memory, generates the PDF file and requests for input.
Entering Interactive Mode
Loading datasets globally.
Enter command or 'exit' to terminate:
Type the arguments to request a plot.
--plot_type {plot_type} --[Other optional arguments for specific plots]
Wait for input request. Type another command or 'exit'
Functionality
Latitude vs Longitude Contour Plots
This function generates a contour plot of a variable against latitude and longitude.
ty.plt_lat_lon (datasets, variable_name, time= None, mtime=None, level = None, variable_unit = None, contour_intervals = None, contour_value = None, coastlines=False, latitude_minimum = None, latitude_maximum = None, longitude_minimum = None, longitude_maximum = None, localtime_minimum = None, localtime_maximum = None )
Parameters:
- datasets (xarray): The loaded dataset/s using xarray.
- variable_name (str): The name of the variable with latitude, longitude, ilev dimensions.
- time (np.datetime64, optional): The selected time e.g., '2022-01-01T12:00:00'.
- mtime (array, optional): The selected time as a list e.g., [1, 12, 0] for 1st day, 12 hours, 0 mins.
- level (float, optional): The selected lev/ilev value.
- variable_unit (str, optional): The desired unit of the variable.
- contour_intervals (int, optional): The number of contour intervals. Defaults to 20.
- contour_value (int, optional): The value between each contour interval.
- coastlines (bool, optional): Shows coastlines on the plot. Defaults to False.
- latitude_minimum (float, optional): Minimum latitude to slice plots. Defaults to -87.5.
- latitude_maximum (float, optional): Maximum latitude to slice plots. Defaults to 87.5.
- longitude_minimum (float, optional): Minimum longitude to slice plots. Defaults to -180.
- longitude_maximum (float, optional): Maximum longitude to slice plots. Defaults to 175.
- localtime_minimum (float, optional): Minimum localtime to slice plots.
- localtime_maximum (float, optional): Maximum localtime to slice plots.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
value_of_mtime = [360, 0, 0, 0]
pressure_level = 4.0
unit_of_variable = 'K'
intervals = 20
- Generate Latitude vs Longitude contour plot:
plot = ty.plt_lat_lon (
datasets,
variable_name,
mtime=value_of_mtime,
level = pressure_level,
variable_unit = unit_of_variable,
contour_intervals = intervals
)
Pressure Level vs Variable Line Plot
This function generates a line plot of a variable at a specific latitude and optional longitude, time, and local time.
ty.plt_lev_var(datasets, variable_name, latitude, time= None, mtime=None, longitude = None, localtime = None, variable_unit = None, level_minimum = None, level_maximum = None)
Parameters:
- datasets (xarray): The loaded dataset(s) using xarray.
- variable_name (str): The name of the variable with latitude, longitude, and ilev dimensions.
- latitude (float): The specific latitude value for the plot.
- time (np.datetime64, optional): The selected time, e.g., '2022-01-01T12:00:00'.
- mtime (array, optional): The selected time as a list, e.g., [1, 12, 0] for the 1st day, 12 hours, 0 minutes.
- longitude (float, optional): The specific longitude value for the plot.
- localtime (float, optional): The specific local time value for the plot.
- variable_unit (str, optional): The desired unit of the variable.
- level_minimum (float, optional): Minimum level value for the plot. Defaults to -8.
- level_maximum (float, optional): Maximum level value for the plot. Defaults to 8.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
latitude = 30.0
time_value = '2022-01-01T12:00:00'
longitude_value = 45.0
unit_of_variable = 'K'
- Generate a Level vs Variable line plot:
plot = ty.plt_lev_var(
datasets,
variable_name,
latitude,
time=time_value,
longitude=longitude_value,
variable_unit=unit_of_variable,
)
Pressure level vs Longitude Contour Plot
This function generates a contour plot of a variable at a specific latitude against longitude, with optional time and local time.
ty.plt_lev_lon(datasets, variable_name, latitude, time= None, mtime=None, variable_unit = None, contour_intervals = 20, contour_value = None, level_minimum = None, level_maximum = None, longitude_minimum = None, longitude_maximum = None, localtime_minimum = None, localtime_maximum = None)
Parameters:
- datasets (xarray): The loaded dataset(s) using xarray.
- variable_name (str): The name of the variable with latitude, longitude, and ilev dimensions.
- latitude (float): The specific latitude value for the plot.
- time (np.datetime64, optional): The selected time, e.g., '2022-01-01T12:00:00'.
- mtime (array, optional): The selected time as a list, e.g., [1, 12, 0] for the 1st day, 12 hours, 0 minutes.
- variable_unit (str, optional): The desired unit of the variable.
- contour_intervals (int, optional): The number of contour intervals. Defaults to 20.
- contour_value (int, optional): The value between each contour interval.
- level_minimum (float, optional): Minimum level value for the plot. Defaults to -6.75.
- level_maximum (float, optional): Maximum level value for the plot. Defaults to 6.75.
- longitude_minimum (float, optional): Minimum longitude value for the plot. Defaults to -180.
- longitude_maximum (float, optional): Maximum longitude value for the plot. Defaults to 175.
- localtime_minimum (float, optional): Minimum localtime value for the plot.
- localtime_maximum (float, optional): Maximum localtime value for the plot.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
latitude = 30.0
time_value = '2022-01-01T12:00:00'
unit_of_variable = 'K'
contour_intervals = 20
- Generate a Level vs Longitude contour plot:
plot = ty.plt_lev_lon(
datasets,
variable_name,
latitude,
time=time_value,
variable_unit=unit_of_variable,
contour_intervals=contour_intervals,
)
Pressure Level vs Latitude Contour Plot
This function generates a contour plot of a variable at a specified level against latitude, with optional time, longitude, and local time.
ty.plt_lev_lat(datasets, variable_name, time= None, mtime=None, longitude = None, localtime = None, variable_unit = None, contour_intervals = 20, contour_value = None, level_minimum = None, level_maximum = None, latitude_minimum = None,latitude_maximum = None):
Parameters:
- datasets (xarray): The loaded dataset(s) using xarray.
- variable_name (str): The name of the variable with latitude, longitude, and ilev dimensions.
- time (np.datetime64, optional): The selected time, e.g., '2022-01-01T12:00:00'.
- mtime (array, optional): The selected time as a list, e.g., [1, 12, 0] for the 1st day, 12 hours, 0 minutes.
- longitude (float, optional): The specific longitude value for the plot.
- localtime (float, optional): The specific local time value for the plot.
- variable_unit (str, optional): The desired unit of the variable.
- contour_intervals (int, optional): The number of contour intervals. Defaults to 20.
- contour_value (int, optional): The value between each contour interval.
- level_minimum (float, optional): Minimum level value for the plot. Defaults to -6.75.
- level_maximum (float, optional): Maximum level value for the plot. Defaults to 6.75.
- latitude_minimum (float, optional): Minimum latitude value for the plot. Defaults to -87.5.
- latitude_maximum (float, optional): Maximum latitude value for the plot. Defaults to 87.5.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
time_value = '2022-01-01T12:00:00'
unit_of_variable = 'K'
contour_intervals = 20
- Generate a Level vs Latitude contour plot:
plot = ty.plt_lev_lat(
datasets,
variable_name,
time=time_value,
variable_unit=unit_of_variable,
contour_intervals=contour_intervals,
)
Pressure Level vs Time Contour Plot
This function generates a contour plot of a variable at a specified level against time, with optional latitude, longitude, and local time.
ty.plt_lev_lat(datasets, variable_name, time= None, mtime=None, longitude = None, localtime = None, variable_unit = None, contour_intervals = 20, contour_value = None, level_minimum = None, level_maximum = None, latitude_minimum = None,latitude_maximum = None)
Parameters:
- datasets (xarray): The loaded dataset(s) using xarray.
- variable_name (str): The name of the variable with latitude, longitude, time, and ilev dimensions.
- latitude (float): The specific latitude value for the plot.
- longitude (float, optional): The specific longitude value for the plot.
- localtime (float, optional): The specific local time value for the plot.
- variable_unit (str, optional): The desired unit of the variable.
- contour_intervals (int, optional): The number of contour intervals. Defaults to 20.
- contour_value (int, optional): The value between each contour interval.
- level_minimum (float, optional): Minimum level value for the plot. Defaults to -6.75.
- level_maximum (float, optional): Maximum level value for the plot. Defaults to 6.75.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
latitude_value = 30.0
longitude_value = 45.0
unit_of_variable = 'K'
contour_intervals = 20
- Generate a Level vs Time contour plot:
plot = ty.plt_lev_time(
datasets,
variable_name,
latitude=latitude_value,
longitude=longitude_value,
variable_unit=unit_of_variable,
contour_intervals=contour_intervals,
)
Latitude vs Time Contour Plot
This function generates a contour plot of a variable at a specified latitude against time, with optional level, longitude, and local time.
Parameters:
- datasets (xarray): The loaded dataset(s) using xarray.
- variable_name (str): The name of the variable with latitude, longitude, time, and ilev dimensions.
- level (float): The specific level value for the plot.
- longitude (float, optional): The specific longitude value for the plot.
- localtime (float, optional): The specific local time value for the plot.
- variable_unit (str, optional): The desired unit of the variable.
- contour_intervals (int, optional): The number of contour intervals. Defaults to 10.
- contour_value (int, optional): The value between each contour interval.
- latitude_minimum (float, optional): Minimum latitude value for the plot. Defaults to -87.5.
- latitude_maximum (float, optional): Maximum latitude value for the plot. Defaults to 87.5.
Example:
- Load datasets:
datasets = ty.load_datasets(directory, dataset_filter)
- Set variable values:
variable_name = 'TN'
level_value = 4.0
longitude_value = 45.0
unit_of_variable = 'K'
contour_intervals = 10
- Generate a Latitude vs Time contour plot:
plot = ty.plt_lat_time(
datasets,
variable_name,
level=level_value,
longitude=longitude_value,
variable_unit=unit_of_variable,
contour_intervals=contour_intervals,
)
File Structure
├── src # Directory for all tiegcmpy source files
│ ├── tiegcmpy
│ ├── __init__.py # Initialize functions for API
│ ├── convert_units.py # Contains unit conversion functions
│ ├── data_parse.py # Contains data extraction and parsing functions
│ ├── plot_gen.py # Contains plot generation functions
│ ├── io.py # Contains Input Output functions for API
│ ├── getoptions.py # Contains argument parser for the Command Line Interface
│ └── main.py # Main python file to run
├── README.md # README
├── benchmark_template.py # Template for running benchmark routines
├── p3postproc.py # Testing file
├── requirements.txt # List of required libraries
└── setup.py # PIP package builder
License
"""License Information"""
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.