Skip to content

API

Main Implementation

Elevation Notch Analysis

Attributes

OUTPUT_RADIOMETRIC_QUANTITY module-attribute

Python
OUTPUT_RADIOMETRIC_QUANTITY = SARRadiometricQuantity.GAMMA_NOUGHT

FILTERING_KERNEL_SIZE module-attribute

Python
FILTERING_KERNEL_SIZE = 21

Classes

Functions:

elevation_notch_analysis

Python
elevation_notch_analysis(product: QualityInputProduct, antenna_pattern: dict[str, dict[str, Dataset]] | None = None, config: ElevationNotchConfig | None = None) -> list[ElevationNotchOutput]

Performing Block-Wise Elevation Notch Analysis on a given product.

Parameters:

Name Type Description Default
product QualityInputProduct

object satisfying the QualityInputProduct protocol

 required
antenna_pattern dict[str, dict[str, Dataset]] | None

antenna pattern for the current product, by default None

Data must be provided in the following format:

Python
{
    "swath": {
        "polarization": xr.Dataset(
            {
                "gain": (
                    ["azimuth_angles", "elevation_angles"],
                    gain_data,  # in dB
                ),
                ...
            },
            coords={
                "elevation_angles": elevation_angles_axis,  # in deg
                "azimuth_angles": azimuth_angles_axis,  # in deg
                ...
            },
        )
    }
}
None
config ElevationNotchConfig | None

ElevationNotchConfig configuration dataclass, by default None

 None

Returns:

Type Description
list[ElevationNotchOutput]

an InterferometricCoherenceOutput dataclass for each channel and each block

Raises:

Type Description
RuntimeError

if Roll angle is not available in the input product

compute_parabolic_profile_fit

Python
compute_parabolic_profile_fit(profile: NDArray[floating], off_boresight_angles_rad: NDArray[floating], fitting_interval_rad: float | None = None, smoothing_kernel_size: int = 201) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], float, list[float]]

Computing a parabolic fit for the given profile and off-boresight angles around the minimum.

Parameters:

Name Type Description Default
profile NDArray[floating]

azimuth block average profile

 required
off_boresight_angles_rad NDArray[floating]

antenna off boresight angles in radians

 required
fitting_interval_rad float | None

fitting interval in radians, if not provided 0.3 deg in radians is used, by default None

 None
smoothing_kernel_size int

smoothing kernel size, by default 201

 201

Returns:

Type Description
NDArray[floating]

antenna off boresight angles axis for the parabolic fit, in radians
NDArray[floating]

parabolic fit values
float

parabola minimum in radians
list[float]

parabola coefficients

antenna_pattern_normalization

Python
antenna_pattern_normalization(antenna_pattern: Dataset, antenna_angles_rad: NDArray[floating]) -> tuple[xr.Dataset, float]

Antenna pattern linearization and normalization in the data region.

Parameters:

Name Type Description Default
antenna_pattern Dataset

antenna pattern for the current swath and polarization

 required
antenna_angles_rad NDArray[floating]

data antenna angles in radians

 required

Returns:

Type Description
Dataset

antenna pattern with linearized and normalized gain
float

elevation angle in radians at antenna pattern maximum in data region

profile_normalization

Python
profile_normalization(profile: NDArray[floating], antenna_angles_rad: NDArray[floating], elevation_angle_rad_at_max_pos: float, mask_margin_rad: float = 0.001745) -> npt.NDArray[np.floating]

Normalize the profile to the antenna pattern maximum.

Parameters:

Name Type Description Default
profile NDArray[floating]

profile to be normalized

 required
antenna_angles_rad NDArray[floating]

data antenna angles in radians

 required
elevation_angle_rad_at_max_pos float

elevation angle in radians at antenna pattern maximum in data region

 required
mask_margin_rad float

margin in radians to be applied to the mask, by default 0.001745

 0.001745

Returns:

Type Description
NDArray[floating]

normalized profile at antenna pattern maximum

residuals

Python
residuals(params: list[float, float, float], data_profile: NDArray[floating], antenna_pattern: Dataset, noise_profile: NDArray[floating], antenna_angles_from_data_rad: NDArray[floating]) -> npt.NDArray[np.floating]

Residuals function for the Least Squares optimization. It represents the difference between the data extracted profile and the antenna model profile, to be minimized. Parameters of optimization are \(\theta_{\text{mis}})\) (mispointing angle), \(k\) (gain) and \(f(\theta_{\text{off}})\) (noise floor).

\[ data_profile - k \dot p(\theta_{\text{off}} - \theta_{\text{mis}}) + noise \dot f( heta_{ ext{off}}) \]

Parameters:

Name Type Description Default
params list[float, float, float]

model parameters residuals

 required
data_profile NDArray[floating]

profile pattern extracted from data

 required
antenna_pattern Dataset

antenna pattern elevation profile

 required
noise_profile NDArray[floating]

noise profile as part of the model to be optimized

 required
antenna_angles_from_data_rad NDArray[floating]

antenna angles in radians from the data

 required

Returns:

Type Description
NDArray[floating]

residuals of data profile and antenna model

antenna_pattern_pointing_mismatch

Python
antenna_pattern_pointing_mismatch(antenna_pattern: Dataset, data_profile: NDArray[floating], noise_profile: NDArray[floating], antenna_angles_from_data_rad: NDArray[floating], initial_guess: list[float, float, float]) -> tuple[float, float, float]

Computing the pointing mismatch between a given data set and the pattern obtained from the antenna model. Optimizing the discrepancy between the data and the model to determine the best fit parameters.

Function to be optimized using Least Squares method in the [residuals][] function.

Parameters:

Name Type Description Default
antenna_pattern Dataset

antenna model elevation pattern for the current swath and polarization

 required
data_profile NDArray[floating]

profile pattern extracted from data

 required
noise_profile NDArray[floating]

noise profile extracted from data

 required
antenna_angles_from_data_rad NDArray[floating]

antenna angles in radians from the data

 required
initial_guess list[float, float, float]

initial guess for the least squares optimization

 required

Returns:

Type Description
float

mispointing angle error in radians
float

calibration constant
float

noise floor

Raises:

Type Description
RuntimeError

if optimization fails

Elevation Notch Analysis support functionalities

Classes

InvalidAntennaPatternError

Bases: Exception

Exception raised when antenna pattern is not valid.

Functions:

validate_antenna_pattern

Python
validate_antenna_pattern(antenna_pattern: Dataset) -> None

Checking antenna pattern validity.

Parameters:

Name Type Description Default
antenna_pattern Dataset

antenna pattern dataset

 required

Raises:

Type Description
InvalidAntennaPatternError

if antenna pattern is not valid

get_valid_antenna_pattern

Python
get_valid_antenna_pattern(antenna_pattern: dict[str, dict[str, Dataset]], swath: str, polarization: str) -> xr.Dataset

Getting the valid antenna pattern for the given swath and polarization from the antenna pattern dataset provided.

Parameters:

Name Type Description Default
antenna_pattern dict[str, dict[str, Dataset]]

antenna pattern dataset, as a dictionary with: swath/pol hierarchy

 required
swath str

swath for the current channel

 required
polarization str

polarization for the current channel

 required

Returns:

Type Description
Dataset

antenna pattern data set for the given swath and polarization

elevation_notch_profiles_to_netcdf

Python
elevation_notch_profiles_to_netcdf(data: list[ElevationNotchOutput], output_dir: str | Path) -> Path

Saving Elevation Notch analysis results to NetCDF file.

Hierarchy::

Text Only
root/
└── swath
    └── polarization
        ├── first_az_line_block
        ├── annotated_roll
        ├── estimated_roll
        ├── notch_minimum_position  # optional
        ├── altitude
        ├── calibration_constant  # optional
        ├── mispointing_error  # optional
        ├── noise_floor  # optional
        ├── parabola_minimum
        ├── parabola_coefficients
        ├── antenna_angles
        ├── antenna_profile_model  # optional
        └── antenna_profile

Some fields are optional and will be saved only if the Elevation Notch analysis was performed using external Antenna Pattern data.

Parameters:

Name Type Description Default
data list[ElevationNotchOutput]

list of ElevationNotchOutput results dataclasses

 required
output_dir str | Path

Path to the output directory where to save the NetCDF file

 required

Returns:

Type Description
Path

path to the NetCDF file

Functions to generate plots for Elevation Notch Analysis

Attributes

COLORS module-attribute

Python
COLORS = {'antenna_model': '#CC3D00', 'parabola': '#083B72', 'scatter_data': '#7C703C'}

Classes

Functions:

plot_elevation_notch_analysis

Python
plot_elevation_notch_analysis(data: list[ElevationNotchOutput], output_dir: str | Path) -> None

Generating the plots for the Elevation Notch Analysis.

Parameters:

Name Type Description Default
data list[ElevationNotchOutput]

list of ElevationNotchOutput results dataclasses

 required
output_dir str | Path

Path to the output directory where to save the graphs

 required

Utilities

Definition of Elevation Notch Analysis configuration

Classes

ElevationNotchConfig dataclass

Configuration for Elevation Notch Analysis

Attributes

azimuth_block_size class-attribute instance-attribute
Python
azimuth_block_size: int = 5000
range_pixel_margin class-attribute instance-attribute
Python
range_pixel_margin: int = 150

Methods:

__init__
Python
__init__(azimuth_block_size: int = 5000, range_pixel_margin: int = 150) -> None
from_dict classmethod
Python
from_dict(arg: dict) -> ElevationNotchConfig

Creating a ElevationNotchConfig object by conversion from a dictionary.

Args: arg (dict): dictionary with keys equal to the ElevationNotchConfig ones

Returns: ElevationNotchConfig: ElevationNotchConfig object

Definition of Elevation Notch Analysis specific dataclasses

Classes

ElevationNotchOutput dataclass

Attributes

product_name class-attribute instance-attribute
Python
product_name: str | None = None
channel class-attribute instance-attribute
Python
channel: str | None = None
swath class-attribute instance-attribute
Python
swath: str | None = None
polarization class-attribute instance-attribute
Python
polarization: SARPolarization | None = None
blocks_info class-attribute instance-attribute
Python
blocks_info: list[ElevationNotchBlockInfo] | None = None

Methods:

__init__
Python
__init__(product_name: str | None = None, channel: str | None = None, swath: str | None = None, polarization: SARPolarization | None = None, blocks_info: list[ElevationNotchBlockInfo] | None = None) -> None

ElevationNotchBlockInfo dataclass

Attributes

block_num class-attribute instance-attribute
Python
block_num: int | None = None
first_az_line_block class-attribute instance-attribute
Python
first_az_line_block: int | None = None
lines_block class-attribute instance-attribute
Python
lines_block: int | None = None
samples_block class-attribute instance-attribute
Python
samples_block: int | None = None
altitude_m class-attribute instance-attribute
Python
altitude_m: float | None = None
annotated_roll_deg class-attribute instance-attribute
Python
annotated_roll_deg: float | None = None
estimated_roll_deg class-attribute instance-attribute
Python
estimated_roll_deg: float | None = None
antenna_profile_from_data_db class-attribute instance-attribute
Python
antenna_profile_from_data_db: NDArray[floating] | None = None
antenna_profile_from_model_db class-attribute instance-attribute
Python
antenna_profile_from_model_db: NDArray[floating] | None = None
antenna_profile_parabolic_fit_db class-attribute instance-attribute
Python
antenna_profile_parabolic_fit_db: NDArray[floating] | None = None
parabolic_fit_axis_deg class-attribute instance-attribute
Python
parabolic_fit_axis_deg: NDArray[floating] | None = None
parabola_minimum_deg class-attribute instance-attribute
Python
parabola_minimum_deg: float | None = None
parabola_coefficients class-attribute instance-attribute
Python
parabola_coefficients: NDArray[floating] | None = None
antenna_angles_deg class-attribute instance-attribute
Python
antenna_angles_deg: NDArray[floating] | None = None
mispointing_error_deg class-attribute instance-attribute
Python
mispointing_error_deg: float | None = None
calibration_constant class-attribute instance-attribute
Python
calibration_constant: float | None = None
noise_floor class-attribute instance-attribute
Python
noise_floor: float | None = None
notch_minimum_position_deg class-attribute instance-attribute
Python
notch_minimum_position_deg: float | None = None

Methods:

__init__
Python
__init__(block_num: int | None = None, first_az_line_block: int | None = None, lines_block: int | None = None, samples_block: int | None = None, altitude_m: float | None = None, annotated_roll_deg: float | None = None, estimated_roll_deg: float | None = None, antenna_profile_from_data_db: NDArray[floating] | None = None, antenna_profile_from_model_db: NDArray[floating] | None = None, antenna_profile_parabolic_fit_db: NDArray[floating] | None = None, parabolic_fit_axis_deg: NDArray[floating] | None = None, parabola_minimum_deg: float | None = None, parabola_coefficients: NDArray[floating] | None = None, antenna_angles_deg: NDArray[floating] | None = None, mispointing_error_deg: float | None = None, calibration_constant: float | None = None, noise_floor: float | None = None, notch_minimum_position_deg: float | None = None) -> None