GEOS5FP Python Package

The GEOS5FP Python package generates rasters of near-real-time GEOS-5 FP near-surface meteorology.

Gregory H. Halverson (they/them)
gregory.h.halverson@jpl.nasa.gov
NASA Jet Propulsion Laboratory 329G

Installation

This package is available on PyPi as a pip package called GEOS5FP.

pip install GEOS5FP

Usage

Import this package as GEOS5FP.

from GEOS5FP import GEOS5FPConnection
from datetime import datetime

Creating a Connection

# Create connection to GEOS-5 FP data
conn = GEOS5FPConnection()

Generating Raster Data

Generate georeferenced raster data for a specific time and optional target geometry:

from rasters import RasterGeometry

# Define target geometry (optional - if not provided, uses native GEOS-5 FP grid)
target_geometry = RasterGeometry.open("target_area.tif")

# Get air temperature raster for a specific time
time_utc = datetime(2024, 11, 15, 12, 0)
temperature_raster = conn.Ta_K(time_UTC=time_utc, geometry=target_geometry)

# Get soil moisture raster
soil_moisture_raster = conn.SM(time_UTC=time_utc, geometry=target_geometry)

# Get leaf area index raster
lai_raster = conn.LAI(time_UTC=time_utc, geometry=target_geometry)

# Save raster to file
temperature_raster.to_geotiff("temperature.tif")

Available raster methods include:

• Ta_K() - Air temperature (Kelvin)
• Ts_K() - Surface temperature (Kelvin)
• SM() / SFMC() - Soil moisture
• LAI() - Leaf area index
• RH() - Relative humidity
• Ca() / CO2SC() - Atmospheric CO2 concentration (ppmv)
• And many more (see Available Variables section below)

Note: For point queries and multi-variable queries, use the .query() method described in the next section.

Generating Table Data with .query()

The .query() method is the recommended way to retrieve GEOS-5 FP data as tabular data (pandas DataFrames). It provides a flexible interface that supports:

• Single point queries - Data at one location and time
• Time series queries - Multiple timesteps at one location
• Multi-variable queries - Multiple variables in a single request
• Vectorized spatio-temporal queries - Multiple locations and times efficiently
• Validation table generation - Add GEOS-5 FP data to existing datasets

Single Point Query

# Get data for single point at specific time
time_utc = datetime(2024, 11, 15, 12, 0)
lat, lon = 34.05, -118.25  # Los Angeles

result = conn.query(
    target_variables="Ta_K",
    time_UTC=time_utc,
    lat=lat,
    lon=lon
)
print(result)  # Returns DataFrame with temperature value

Time Series Query

from datetime import timedelta

# Define time range
end_time = datetime(2024, 11, 15, 0, 0)
start_time = end_time - timedelta(days=7)  # 7 days of data

# Get time series for a point location
lat, lon = 34.05, -118.25
df = conn.query(
    target_variables="Ta_K",
    time_range=(start_time, end_time),
    lat=lat,
    lon=lon
)
print(df)  # Returns DataFrame with time series

Multi-Variable Query

# Query multiple variables at once
variables = ["Ta_K", "SM", "LAI"]
df_multi = conn.query(
    target_variables=variables,
    time_range=(start_time, end_time),
    lat=lat,
    lon=lon
)
print(df_multi)  # Returns DataFrame with columns for each variable

Validation Table Generation

import geopandas as gpd
from shapely.geometry import Point

# Create a table with existing data
targets = gpd.GeoDataFrame({
    'time_UTC': [datetime(2024, 11, 15, 12), datetime(2024, 11, 15, 13)],
    'geometry': [Point(-118.25, 34.05), Point(-74.0, 40.7)],
    'site_name': ['Los Angeles', 'New York']
})

# Query variables and add as new columns to the table
result = conn.query(
    target_variables=["Ta_C", "RH", "SM"],
    targets_df=targets
)
print(result)  # Returns original table with new columns for each variable

Vectorized Spatio-Temporal Query

import pandas as pd
import geopandas as gpd

# Load spatio-temporal data from CSV
data = pd.read_csv("locations.csv")  # Should have columns: time_UTC, lat, lon
data['time_UTC'] = pd.to_datetime(data['time_UTC'])

# Create geometries
gdf = gpd.GeoDataFrame(
    data,
    geometry=gpd.points_from_xy(data['lon'], data['lat'])
)

# Query all points and times at once (vectorized operation)
results = conn.query(
    target_variables=["Ta_K", "SM", "LAI"],
    time_UTC=gdf['time_UTC'],
    geometry=gdf['geometry']
)
print(results)  # Returns DataFrame with results for all locations and times

Using Raw GEOS-5 FP Variables

You can query variables using either:

• Predefined variable names (e.g., "Ta_K", "SM", "RH") - recommended for convenience
• Raw GEOS-5 FP variable names (e.g., "T2M", "SFMC", "QV2M") - requires dataset parameter

# Using predefined variable name (dataset automatically determined)
df = conn.query(
    target_variables="Ta_K",
    time_range=(start_time, end_time),
    lat=lat,
    lon=lon
)

# Using raw GEOS-5 FP variable name (dataset required)
df = conn.query(
    target_variables="T2M",  # Raw GEOS-5 FP variable name
    dataset="tavg1_2d_slv_Nx",  # Must specify product
    time_range=(start_time, end_time),
    lat=lat,
    lon=lon
)

See Available Variables section below for the complete list.

Computed Variables

The package automatically computes derived meteorological variables from base GEOS-5 FP data. You can query these just like any other variable:

# Query computed variables
results = conn.query(
    target_variables=["wind_speed_mps", "Ta_C", "RH", "VPD_kPa"],
    time_UTC=time_utc,
    lat=lat,
    lon=lon
)

Available computed variables:

The package automatically retrieves only the necessary base variables and returns just the computed results.

Available Variables

The package provides access to a comprehensive set of GEOS-5 FP variables, organized by category. All variables can be queried using the .query() method or their corresponding dedicated methods.

Soil and Vegetation

Temperature

Pressure and Humidity

Wind

Atmospheric Composition

Radiation

Albedo

Variable Aliases

Many variables have multiple names for convenience:

• SM ↔ SFMC (Soil moisture)
• Ta ↔ Ta_K (Air temperature)
• Ts ↔ Ts_K (Surface temperature)
• Tmin ↔ Tmin_K (Minimum temperature)
• Ca ↔ CO2SC (CO2 concentration)
• vapor_kgsqm ↔ vapor_gccm (Water vapor)
• ozone_dobson ↔ ozone_cm (Ozone)

Temporal Resolution

• Hourly (tavg1_*): 1-hour time-averaged data
• 3-Hourly (tavg3_*, inst3_*): 3-hour time-averaged or instantaneous data

Complete Variable Reference

For detailed information about all variables, including formulas for computed variables and usage examples, see:

• QUERYABLE_VARIABLES.md - Comprehensive variable guide
• GEOS5FP/variables.csv - Machine-readable variable mappings

Data Source & Citation

This package accesses GEOS-5 FP (Forward Processing) data produced by the Global Modeling and Assimilation Office (GMAO) at NASA Goddard Space Flight Center.

Data Access

GEOS-5 FP data is accessed through:

• OPeNDAP Server: https://opendap.nccs.nasa.gov/dods/GEOS-5/fp/
• HTTP Server: https://portal.nccs.nasa.gov/datashare/gmao/geos-fp/das

Data is provided by NASA's Center for Climate Simulation (NCCS).

Citation

When using GEOS-5 FP data in publications, please cite:

Data Product:

Global Modeling and Assimilation Office (GMAO) (2015), GEOS-5 FP: GEOS Forward 
Processing for Instrument Support, Greenbelt, MD, USA, Goddard Earth Sciences 
Data and Information Services Center (GES DISC). 
Accessed: [Date]

Acknowledgment:

GEOS-5 FP data used in this study were provided by the Global Modeling and 
Assimilation Office (GMAO) at NASA Goddard Space Flight Center through the 
NASA Center for Climate Simulation (NCCS).

For more information about GEOS-5 FP, visit: https://gmao.gsfc.nasa.gov/GEOS/