Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NASAARSET/PM2.5_AQ_Online_2026/llms.txt

Use this file to discover all available pages before exploring further.

F_subset_and_combine is the primary data-ingestion utility in the ARSET PM2.5 workflow. It accepts a list of file paths (typically NetCDF or HDF5 files from satellite products such as SatPM2.5 or MERRA-2), opens and concatenates them along the time dimension, and then trims the merged dataset to the latitude/longitude bounding box and the start/end timestamps you specify. The result is a compact, analysis-ready xarray.Dataset that only contains the region and period of interest — making every downstream step faster and less memory-intensive. Use this function at the very beginning of a notebook session, right after you have assembled your file list with glob.glob or a similar utility, and before calling F_plot_map or F_compute_metrics.

​
Parameters

​
l_files
list[str]
required
List of file paths to load and concatenate. All files must share the same grid structure and variable names. Typical source: the output of glob.glob('/path/to/SatPM/*.nc') sorted chronologically.
​
n_lon_min
float
required
Minimum (western) longitude of the spatial bounding box, in decimal degrees. Use negative values for the Western Hemisphere (e.g., -76.0 for western Chile).
​
n_lat_min
float
required
Minimum (southern) latitude of the spatial bounding box, in decimal degrees. Use negative values for the Southern Hemisphere (e.g., -46.0 for southern Patagonia).
​
n_lon_max
float
required
Maximum (eastern) longitude of the spatial bounding box, in decimal degrees.
​
n_lat_max
float
required
Maximum (northern) latitude of the spatial bounding box, in decimal degrees.
​
t_start
numpy.datetime64
required
Start of the time window of interest. Must be a numpy.datetime64 object. Records with timestamps strictly before this value are excluded.
import numpy as np
t_start = np.datetime64('2023-01-01')
​
t_end
numpy.datetime64
required
End of the time window of interest. Must be a numpy.datetime64 object. Records with timestamps strictly after this value are excluded.
t_end = np.datetime64('2023-12-31')
​
s_lat
str
default:"'lat'"
Name of the latitude dimension/coordinate in the source files. Override this if your files use a non-standard name such as 'latitude', 'Lat', or 'y'.
​
s_lon
str
default:"'lon'"
Name of the longitude dimension/coordinate in the source files. Override this if your files use 'longitude', 'Lon', or 'x'.
​
s_time
str
default:"'time'"
Name of the time dimension/coordinate in the source files. Override this if your files use 'Time', 'datetime', etc.
​
F_time_from_file
callable | None
default:"None"
An optional function that accepts a file path string and returns a numpy.datetime64 timestamp. Provide this when the source files do not contain an embedded time coordinate (e.g., monthly SatPM2.5 files whose timestamp is encoded only in the filename). The returned timestamp is used to populate the time dimension for that file before concatenation.
# Example: parse 'SatPM_202301.nc' → numpy.datetime64('2023-01')
def time_from_filename(path):
    import re, numpy as np
    m = re.search(r'(\d{6})', path)
    return np.datetime64(f'{m.group(1)[:4]}-{m.group(1)[4:]}')

​
Return Value

​
a_data
xarray.Dataset | xarray.DataArray
An xarray.Dataset (or DataArray) containing all variables from the source files, trimmed to the specified spatial bounding box and time window. Dimension coordinates are lat, lon, and time (or the custom names supplied via s_lat, s_lon, s_time). The dataset is suitable for direct use with F_plot_map and F_compute_metrics.

​
Usage Example

The following example loads monthly SatPM2.5 files for the Biobío region of Chile (covering the 2023 calendar year), parses timestamps from filenames, and clips to the region bounding box. 
import glob
import numpy as np

# 1. Collect files
l_files = sorted(glob.glob('/data/SatPM2.5/monthly/SatPM_2023*.nc'))

# 2. Define the Biobío bounding box
n_lon_min, n_lon_max = -74.0, -71.0
n_lat_min, n_lat_max = -39.0, -36.0

# 3. Define the time window
t_start = np.datetime64('2023-01-01')
t_end   = np.datetime64('2023-12-31')

# 4. Helper to extract timestamp from filename
def time_from_filename(path):
    import re
    m = re.search(r'SatPM_(\d{4})(\d{2})', path)
    return np.datetime64(f'{m.group(1)}-{m.group(2)}')

# 5. Load, combine, and clip
a_data_SatPM = F_subset_and_combine(
    l_files          = l_files,
    n_lon_min        = n_lon_min,
    n_lat_min        = n_lat_min,
    n_lon_max        = n_lon_max,
    n_lat_max        = n_lat_max,
    t_start          = t_start,
    t_end            = t_end,
    F_time_from_file = time_from_filename,
)

print(a_data_SatPM)
# <xarray.Dataset>
# Dimensions:  (lat: 12, lon: 12, time: 12)
# ...
All files in l_files are opened with xarray.open_dataset and concatenated with xarray.concat along the time dimension before the spatial and temporal subsetting is applied. For very large collections of files, consider pre-filtering the list to only those files that fall within the time window before passing it to F_subset_and_combine.
t_start and t_end must be numpy.datetime64 objects, not Python datetime objects or strings. Passing the wrong type will raise a TypeError during the comparison. Convert with np.datetime64('YYYY-MM-DD').

Build docs developers (and LLMs) love

Get started for freeTalk to us