Skip to content

Commit

Permalink
Enhance docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
Alexey Pechnikov committed Aug 14, 2024
1 parent 492a3d3 commit e4ec42a
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 20 deletions.
94 changes: 86 additions & 8 deletions pygmtsar/pygmtsar/ASF.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,31 +33,84 @@ def _get_asf_session(self):
import asf_search
return asf_search.ASFSession().auth_with_creds(self.username, self.password)

def download(self, basedir, scenes_or_bursts, subswaths=None, polarization='VV',
session=None, n_jobs=4, joblib_backend='loky', skip_exist=True, debug=False):
def download(self, basedir, scenes_or_bursts, subswaths=None, polarization='VV', **kwargs):
"""
Downloads the specified subswaths or bursts extracted from Sentinel-1 SLC scenes.
Parameters
----------
basedir : str
The directory where the downloaded scenes will be saved.
scenes_or_bursts : list of str
List of scene and bursts identifiers to download.
subswaths : list of str
Number representing the subswaths to download for each scene (e.g., 1 or 123). Ignored if a burst ID is provided.
polarization : str, optional
The polarization to download ('VV' by default). Ignored if the burst ID is provided.
session : asf_search.ASFSession, optional
The session object for authentication. If None, a new session is created.
n_jobs : int, optional
The number of concurrent download jobs. Default is 8.
joblib_backend : str, optional
The backend for parallel processing. Default is 'loky'.
skip_exist : bool, optional
If True, skips downloading scenes that already exist. Default is True.
debug : bool, optional
If True, prints debugging information. Default is False.
Returns
-------
pandas.DataFrame
A DataFrame containing the list of downloaded scenes and bursts.
"""
import pandas as pd

bursts = [item for item in scenes_or_bursts if item.endswith('-BURST')]
scenes = [item[:-4] if item.endswith('-SLC') else item for item in scenes_or_bursts if item not in bursts]

results = []
if len(bursts):
result = self.download_bursts(basedir, bursts,
session=session,
n_jobs=n_jobs, joblib_backend=joblib_backend, skip_exist=skip_exist, debug=debug)
result = self.download_bursts(basedir, bursts, **kwargs)
if result is not None:
results.append(result.rename({'burst': 'burst_or_scene'}, axis=1))
if len(scenes):
result = self.download_scenes(basedir, scenes, subswaths=subswaths, polarization=polarization,
session=session,
n_jobs=n_jobs, joblib_backend=joblib_backend, skip_exist=skip_exist, debug=debug)
result = self.download_scenes(basedir, scenes, subswaths=subswaths, polarization=polarization, **kwargs)
if result is not None:
results.append(result.rename({'scene': 'burst_or_scene'}, axis=1))
if len(results):
return pd.concat(results)

def download_scenes(self, basedir, scenes, subswaths, polarization='VV', session=None,
n_jobs=4, joblib_backend='loky', skip_exist=True, debug=False):
"""
Downloads the specified subswaths extracted from Sentinel-1 SLC scenes.
Parameters
----------
basedir : str
The directory where the downloaded scenes will be saved.
scenes : list of str
List of scene identifiers to download.
subswaths : list of str
Number representing the subswaths to download for each scene (e.g., 1 or 123).
polarization : str, optional
The polarization to download ('VV' by default).
session : asf_search.ASFSession, optional
The session object for authentication. If None, a new session is created.
n_jobs : int, optional
The number of concurrent download jobs. Default is 4.
joblib_backend : str, optional
The backend for parallel processing. Default is 'loky'.
skip_exist : bool, optional
If True, skips downloading scenes that already exist. Default is True.
debug : bool, optional
If True, prints debugging information. Default is False.
Returns
-------
pandas.DataFrame
A DataFrame containing the list of downloaded scenes.
"""
import pandas as pd
import numpy as np
import asf_search
Expand Down Expand Up @@ -189,6 +242,31 @@ def download_scene(scene, subswaths, polarization, basedir, session):

# https://asf.alaska.edu/datasets/data-sets/derived-data-sets/sentinel-1-bursts/
def download_bursts(self, basedir, bursts, session=None, n_jobs=8, joblib_backend='loky', skip_exist=True, debug=False):
"""
Downloads the specified bursts extracted from Sentinel-1 SLC scenes.
Parameters
----------
basedir : str
The directory where the downloaded bursts will be saved.
bursts : list of str
List of burst identifiers to download.
session : asf_search.ASFSession, optional
The session object for authentication. If None, a new session is created.
n_jobs : int, optional
The number of concurrent download jobs. Default is 8.
joblib_backend : str, optional
The backend for parallel processing. Default is 'loky'.
skip_exist : bool, optional
If True, skips downloading bursts that already exist. Default is True.
debug : bool, optional
If True, prints debugging information. Default is False.
Returns
-------
pandas.DataFrame
A DataFrame containing the list of downloaded bursts.
"""
import rioxarray as rio
from tifffile import TiffFile
import xmltodict
Expand Down
49 changes: 38 additions & 11 deletions pygmtsar/pygmtsar/S1.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,32 @@ class S1(tqdm_joblib):
@staticmethod
def download_orbits(basedir: str, scenes: list | pd.DataFrame,
n_jobs: int = 8, joblib_backend='loky', skip_exist: bool = True):
"""
Downloads orbit files corresponding to the specified Sentinel-1 scenes.
Parameters
----------
basedir : str
The directory where the downloaded orbit files will be saved.
scenes : list or pandas.DataFrame
List of scene identifiers or a DataFrame containing scenes for which the orbits are to be downloaded.
n_jobs : int, optional
The number of concurrent download jobs. Default is 8.
joblib_backend : str, optional
The backend for parallel processing. Default is 'loky'.
skip_exist : bool, optional
If True, skips downloading orbits that already exist. Default is True.
Returns
-------
pandas.Series
A Series containing the names of the downloaded orbit files.
Raises
------
ValueError
If an invalid scenes argument is provided or no suitable orbit files are found.
"""
import pandas as pd
import requests
import os
Expand Down Expand Up @@ -151,16 +177,12 @@ def download_orbit(basedir, url):
@staticmethod
def scan_slc(datadir, orbit=None, mission=None, subswath=None, polarization=None):
"""
Initialize an instance of the Stack class.
Scans the specified directory for Sentinel-1 SLC (Single Look Complex) data and filters it based on the provided parameters.
Parameters
----------
datadir : str
The directory containing the data files.
dem_filename : str, optional
The filename of the DEM (Digital Elevation Model) WGS84 NetCDF file. Default is None.
landmask_filename : str, optional
The filename of the landmask WGS84 NetCDF file. Default is None.
orbit : str, optional
Filter for orbit direction. Use 'A' for Ascending, 'D' for Descending, or None for no filter. Default is None.
mission : str, optional
Expand All @@ -169,11 +191,16 @@ def scan_slc(datadir, orbit=None, mission=None, subswath=None, polarization=None
Filter for subswath number. Use a single or sequential numbers 1, 2, 3, 12, 23, 123, or None for no filter. Default is None.
polarization : str, optional
Filter for polarization. Use 'VV', 'VH', 'HH', 'HV', or None for no filter. Default is None.
Examples
--------
Initialize an Stack object with the data directory 'data':
stack = S1('data')
Returns
-------
pandas.DataFrame
A DataFrame containing metadata about the filtered SLC scenes, including their paths and other relevant properties.
Raises
------
ValueError
If the filtered scenes contain inconsistencies, such as mismatched .tiff and .xml files, or if invalid filter parameters are provided.
"""
import os
import shutil
Expand Down
8 changes: 7 additions & 1 deletion pygmtsar/pygmtsar/XYZTiles.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,12 +67,18 @@ def download(self, geometry, zoom, filename=None, url='https://mt1.google.com/vt
This is typically referred to as an Area of Interest (AOI).
zoom : int
The zoom level for the map tiles. Higher zoom levels correspond to higher resolution.
filename : str or None, optional
The name of the file to save the downloaded DEM. If None, a default name will be generated. Default is None.
url : str, optional
The URL template of the tile map service. The placeholders {x}, {y}, {z} should be present in the URL.
Default is Google Satellite Hybrid 'https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}'.
n_jobs : int, optional
The number of concurrent download jobs. Default is 8.
skip_exist : bool, optional
If True, skips the download if the file already exists. Default is True.
debug : bool, optional
If True, prints debugging information. Default is False.
Returns
-------
Xarray
Expand Down

0 comments on commit e4ec42a

Please sign in to comment.