uwacan.analysis.ShipLevel.analyze_transits#

classmethod ShipLevel.analyze_transits(*transits, filterbank=None, propagation_model=None, background_noise=None, transit_min_angle=None, transit_min_duration=None, transit_min_length=None, reference_position=None)[source]#

Analyze ship transits to estimate source power and related metrics.

Parameters:
*transitsTransit objects

One or more Transit objects to be analyzed.

filterbankcallable, optional

A callable that applies a filterbank to the time data of the recording. If not provided, defaults to Spectrogram with 10 bands per decade between 20 Hz and 20 kHz, and a frame step of 1. The callable should have the signature:

f(time_data: uwacan.TimeData) -> uwacan.TimeFrequencyData
propagation_modelcallable or PropagationModel, optional

A callable that compensates for the propagation effects on the received power. If not provided, defaults to a MlogR propagation model with m=20. The callable should have the signature:

propagation_model(
    received_power: uwacan.FrequencyData,
    receiver: uwacan.Position,
    source: uwacan.Track
) -> uwacan.FrequencyData

with the frequency data optionally also having a time dimension.

background_noisecallable, optional

A callable that models the background noise. The callable should have the signature:

f(received_power: uwacan.FrequencyData) -> uwacan.FrequencyData

If not provided, defaults to a no-op function that returns the input received_power. A suitable callable can be created using the uwacan.background.Background class.

transit_min_anglefloat, optional

Minimum angle for segment selection during transit analysis, in degrees. The segment analyzed will cover at least this aspect angle on each side of the CPA. E.g., transit_min_angle=30 means the segment covers from -30° to +30°.

transit_min_durationfloat, optional

Minimum duration for segment selection during transit analysis, in seconds. The segment analyzed will cover at least this duration in total.

transit_min_lengthfloat, optional

Minimum length for segment selection during transit analysis, in meters. The segment analyzed will cover at least this length in total.

Returns:
ship_levelsShipLevels

An instance of the class containing the analysis results for each transit, including source power, latitude, longitude, transit time, and optionally signal-to-noise ratio (SNR).

Notes

This method processes each transit individually by:

  1. Determining the closest point of approach (CPA) time.

  2. Optionally selecting a segment around CPA.

  3. Applying the filterbank to the time data of the recording.

  4. Compensating for background noise and propagation effects.

The method returns a concatenated dataset containing the results for all provided transits. The core dimension for each transit is “segment”, which indicates the time segments used in the filterbank.