Package: s1-frame-enumerator
S1_Frame_EnumeratorThis library enumerates input single look complex (SLC) IDs for reference and secondary imagery to generate a time series of interferograms over an area of interest (AOI) usingfixed spatial frames. Such SLC imagery can then be used to generate an interferometric time series. Our focus is generating ARIA S1 Geocoded Unwrapped Interferogram (ARIA-S1-GUNW), a standardized, sensor-neutral inteferometric product as describedhereusingISCE2.BackgroundSentinel-1 SLC enumeration for interferometric processing is notoriously challenging despite its simple description. This is partly because ESA frame definitions are not spatially fixed in time and it is hard to ensure complete spatial coverage across date pairs. Our fixed frame approach attempts to circumvent this challenge by ensuring SLC pairs are enunumerated across fixed spatial areas. We also ensure consistent overlap (at least 1 burst) across inteferometric products to ensure interferometric products can be stitched for downstream analysis.This library relies onasf-searchto enumerate Sentinel-1 A/B pairs from fixed frames derived from ESA's burstmap. We describe the generation of the "fixed-frames" in thisrepository. Using this frame map (stored a zip file within this library), we enumerate SLCs that cover contiguous collection of frames. The frames Northern and Souther boundaries are aligned with latitude lines to ensure GUNW products and the frame definitions are consistent. We have two datasets the latitude-alignedframesand the expected GUNW productextents.UsageHere is a summary of the API:from shapely.geometry import Point
from s1_frame_enumerator import (get_s1_stack,
                                 get_overlapping_s1_frames,
                                 enumerate_gunw_time_series
                                 )

# Southern California
aoi_geo = Point(-120, 35).buffer(1)

# Get Frames
track_numbers = [144]
frames = get_overlapping_s1_frames(aoi_geo,
                                   track_numbers=track_numbers)

# Get Stack
df_stack = get_s1_stack(frames)

# Get Pairs for IFGs over Frames
min_temporal_baseline = 30
neighbors = 3
ifg_data = enumerate_gunw_time_series(df_stack,
                                      min_temporal_baseline_days=min_temporal_baseline,
                                      n_secondary_scenes_per_ref=neighbors,
                                      frames=frames
                                      )Then,ifg_datais a list of dictionaries, each corresponding to a inteferogram for a complete time series covering the specified frames covering the AOI. For example,ifg_data[0]returns the dictionary:{'reference': ['S1A_IW_SLC__1SDV_20230302T140018_20230302T140045_047466_05B2DB_C2B5',
  'S1A_IW_SLC__1SDV_20230302T140043_20230302T140110_047466_05B2DB_F791'],
 'secondary': ['S1A_IW_SLC__1SDV_20230125T140019_20230125T140046_046941_05A132_82DF',
  'S1A_IW_SLC__1SDV_20230125T140044_20230125T140111_046941_05A132_59E7'],
 'reference_date': Timestamp('2023-03-02 00:00:00+0000', tz='UTC'),
 'secondary_date': Timestamp('2023-01-25 00:00:00+0000', tz='UTC'),
 'frame_id': 22439,
 'geometry': <POLYGON Z ((-121.034 34.871 0, -121.037 34.871 0, -120.807 36.008 0, -117.9...>}DemonstrationSee theBasic_Demo.ipynbfor a more complete look at this library and usingGeoPandasandmatplotlibto visualize the coverage and time-series.Fixed FramesEach fixed frame consists of approximately 8 bursts and at least 1 burst overlap between GUNW extents between frames along track. The frames themselves have only.001degree overlap. However, since ISCE2 process all bursts intersecting a given bounding box (dictated by our frames), the extents have at least 1 burst overlap and often 2 or 3 depending on the swath. The fixed frames are constratined to be within 1 degree of the high resolution land mask high resolution GSHHG land maphere. See therepositoryfor a complete description of the methodology.Subtlties of Creating an Image StackThis library is aimed at a very specific type of enumeration of SLCs for Geocoded Interferograms derived fromLevel-1 IW SLCs with VV polarization. However, Sentinel-1 distributes a wide variety of products not all of which are available consistently globally. As such, there are situations when using this enumeration you will have to compare the imagery retrieved againstASFSearch. That said, we are using the following search parameters foundhere. When comparing against ASFSearch orasf-search, make sure to use these parameters.Hereis an example of some suprising behavior: there is noVVorVV+VHon this pass when S1 images Mexico, but they exist within the US continental boundaries.Generally speaking there are two competing considerations:Spatial coverage - the spatial interesection of all dates in the stackTemporal coverage - the number of dates included within a time series stackIncreasing one, decreases the other and vice versa. In theget_s1_stackutilizing the ASF metadata, there is control over spatial coverage via coverage ratios (per pass coverage and per frame coverage) which invariably will lead to smaller spatial coverage because when a given pass covers less area, its intersection across dates will go down. When excluding given frames (e.g. because a frame is mostly over ocean say), this decreases spatial coverage but since Sentinel-1 data that we care about does not exist over the ocean, this may likely increase our temporal coverage.Let's be more explicit about the possible/anticipated scenarios for modifying stacks in these situtations. We hope to provide more detailed notebooks or instructions later.An AOI has significant water making a pass disconnected (say an AOI spanning Africa and Europe over the Mediteranean) - separate into two different AOIs over each contiguous land areasA specific frame has low coverage at numerous dates being at the boundary of a product distribution boundary (e.g. US and Mexico where Sentinel-1 might switch modes) or near a coastline - remove frame at the boundary or lower per frame or per pass coverage ratiosTo ensure higher number of dates in the stack: trouble shoot with per frame and per pass coverage ratios inget_s1_stack. Lowering the per frame and pass ratios permits more dates to be included, but the total time series may have a lower spatial coverage. ISCE2 requires a minimum number of bursts to do processing. We recommend that every frame have at least 25% coverage to be safe.Enumerating (temporally dense) interferograms over island chains will likely just be hard particulary because Sentinel-1 will turn off and on over the ocean.InstallationClone the repository and navigate to itInstall the environment:mamba env update -f environment.ymlActivate the environment:conda activate s1-frame-enumeratorInstall with pip:pip install .For development, usepip install -e .so updates are instantly seen in by the interpreter.ContributingWe welcome contributions to this open-source package. To do so:Create an GitHub issue ticket desrcribing what changes you need (e.g. issue-1)Fork this repoMake your modifications in your own forkMake a pull-request (PR) in this repo with the code in your fork and tag the repo owner or a relevant contributor.We useflake8and associated linting packages to ensure some basic code quality (see theenvironment.yml). These will be checked for each commit in a PR.SupportCreate an GitHub issue ticket desrcribing what changes you would like to see or to report a bug.We will work on solving this issue (hopefully with you).