Class AcousticEvent

Inheritance

Object

ResultBase

EventBase

AcousticEvent

Implements

IComparable<ResultBase>

IComparable

ISpectralEvent

ISpectralBand

ITemporalEvent

IInstantEvent

Inherited Members

EventBase.SegmentStartSeconds

EventBase.Score

EventBase.SetEventStartRelative(TimeSpan, Double)

ResultBase.FileName

ResultBase.ResultStartSeconds

ResultBase.SegmentDurationSeconds

ResultBase.ResultMinute

ResultBase.CompareTo(ResultBase)

ResultBase.CompareTo(Object)

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: AudioAnalysisTools

Assembly: AudioAnalysisTools.dll

Syntax

public class AcousticEvent : EventBase, IComparable<ResultBase>, IComparable, ISpectralEvent, ISpectralBand, ITemporalEvent, IInstantEvent

Constructors

AcousticEvent()

Initializes a new instance of the AcousticEvent class. Sets some default colors for drawing an event on a spectrogram. THis is the first of three constructors.

Declaration

public AcousticEvent()

AcousticEvent(TimeSpan, Double, Double, Double, Double)

Initializes a new instance of the AcousticEvent class. This constructor requires the minimum information to establish the temporal and frequency bounds of an acoustic event.

Declaration

public AcousticEvent(TimeSpan segmentStartOffset, double eventStartSegmentRelative, double eventDuration, double minFreq, double maxFreq)

Parameters

Type	Name	Description
TimeSpan	segmentStartOffset	The start of the current segment relative to start of recording.
Double	eventStartSegmentRelative	event start with respect to start of segment.
Double	eventDuration	event end with respect to start of segment.
Double	minFreq	Lower frequency bound of event.
Double	maxFreq	Upper frequency bound of event.

Fields

DefaultBorderColor

Declaration

public static readonly Color DefaultBorderColor

Field Value

Type	Description
SixLabors.ImageSharp.Color

DefaultScoreColor

Declaration

public static readonly Color DefaultScoreColor

Field Value

Type	Description
SixLabors.ImageSharp.Color

Properties

Bandwidth

Gets the bandwidth of an acoustic event.

Declaration

public double Bandwidth { get; }

Property Value

Type	Description
Double

BorderColour

Declaration

public Color BorderColour { get; set; }

Property Value

Type	Description
SixLabors.ImageSharp.Color

DominantFreq

Declaration

public double DominantFreq { get; set; }

Property Value

Type	Description
Double

EventDurationSeconds

Gets the event duration in seconds.

Declaration

public double EventDurationSeconds { get; }

Property Value

Type	Description
Double

EventEndSeconds

Gets the end time of an event relative to the recording start.

Declaration

public double EventEndSeconds { get; }

Property Value

Type	Description
Double

EventStartSeconds

Gets the start time of an event relative to the recording start.

Declaration

public override double EventStartSeconds { get; }

Property Value

Type	Description
Double

Overrides

EventBase.EventStartSeconds

FrameCount

Declaration

public int FrameCount { get; set; }

Property Value

Type	Description
Int32

FrameDuration

Gets frame duration in seconds.

Declaration

public double FrameDuration { get; }

Property Value

Type	Description
Double

FrameOffset

Gets or sets time between frame starts in seconds. Inverse of FramesPerSecond.

Declaration

public double FrameOffset { get; set; }

Property Value

Type	Description
Double

FramesPerSecond

Gets or sets number of frame starts per second. Inverse of the frame offset.

Declaration

public double FramesPerSecond { get; set; }

Property Value

Type	Description
Double

FreqBinCount

Gets or sets required for conversions to & from MEL scale AND for drawing event on spectrum.

Declaration

public int FreqBinCount { get; set; }

Property Value

Type	Description
Int32

FreqBinWidth

Gets required for freq-binID conversions.

Declaration

public double FreqBinWidth { get; }

Property Value

Type	Description
Double

HighFrequencyHertz

Gets or sets units = Hertz.

Declaration

public double HighFrequencyHertz { get; set; }

Property Value

Type	Description
Double

HitColour

Declaration

public Color? HitColour { get; set; }

Property Value

Type	Description
Nullable<SixLabors.ImageSharp.Color>

HitElements

Declaration

public ISet<Point> HitElements { get; set; }

Property Value

Type	Description
ISet<SixLabors.ImageSharp.Point>

Intensity

Gets or sets assigned value when reading in a list of user identified events. Indicates a user assigned assessment of event intensity.

Declaration

public int Intensity { get; set; }

Property Value

Type	Description
Int32

IsMelscale

Declaration

public bool IsMelscale { get; set; }

Property Value

Type	Description
Boolean

LowFrequencyHertz

Gets or sets units = Hertz. Proxied to EventBase.MinHz.

Declaration

public double LowFrequencyHertz { get; set; }

Property Value

Type	Description
Double

Name

Declaration

public string Name { get; set; }

Property Value

Type	Description
String

Oblong

Gets or sets the bounds of an event with respect to the segment start BUT in terms of the frame count (from segment start) and frequency bin (from zero Hertz). This is no longer the preferred way to operate with acoustic event bounds. Better to use real units (seconds and Hertz) and provide the acoustic event with scale information.

Declaration

public Oblong Oblong { get; set; }

Property Value

Type	Description
Oblong

Periodicity

Gets or sets the periodicity of acoustic energy in an event. Use for events which have an oscillating acoustic energy - e.g. for frog calls.

Declaration

public double Periodicity { get; set; }

Property Value

Type	Description
Double

Profile

Gets or sets which profile (combination of settings in a config file) produced this event.

Declaration

public string Profile { get; set; }

Property Value

Type	Description
String

Quality

Gets or sets assigned value when reading in a list of user identified events. Indicates a user assigned assessment of event quality.

Declaration

public int Quality { get; set; }

Property Value

Type	Description
Int32

Score_MaxInEvent

Declaration

public double Score_MaxInEvent { get; set; }

Property Value

Type	Description
Double

Score_MaxPossible

Gets max Possible Score: set = to 5x user supplied threshold. An arbitrary value used for score normalisation - it displays well in plot.

Declaration

public double Score_MaxPossible { get; set; }

Property Value

Type	Description
Double

Score_TimeOfMaxInEvent

Declaration

public double Score_TimeOfMaxInEvent { get; set; }

Property Value

Type	Description
Double

Score2

Gets or sets second score if required.

Declaration

[Obsolete("We should use another type of Event class to represent this concept")]
public double Score2 { get; set; }

Property Value

Type	Description
Double

Score2Name

Declaration

public string Score2Name { get; set; }

Property Value

Type	Description
String

ScoreColour

Declaration

public Color ScoreColour { get; set; }

Property Value

Type	Description
SixLabors.ImageSharp.Color

ScoreNormalised

Gets or sets score normalised in range [0,1]. NOTE: Max is set = to five times user supplied threshold.

Declaration

public double ScoreNormalised { get; set; }

Property Value

Type	Description
Double

SpeciesName

Declaration

public string SpeciesName { get; set; }

Property Value

Type	Description
String

TimeEnd

Gets the time offset (in seconds) from start of current segment to end of the event. This field is NOT in EventBase. EventBase only requires TimeStart because it is designed to also accomodate points.

Declaration

[Obsolete("Bounds relative to the segment are inconsistent with our rules for always measuring from the start of the recording.")]
public double TimeEnd { get; }

Property Value

Type	Description
Double

Remarks

NOTE: TimeStart is relative to the start of a segment. This notion is obsolete! Events must always be stored relative to start of the recording.

Note: converted to private setter so we can control how this is set. Recommend using SetEventPositionRelative(TimeSpan, Double, Double) after event instantiation to modify bounds.

TimeStart

Gets the time offset from start of current segment to start of event in seconds. Proxied to EventBase.EventStartSeconds.

Declaration

[Obsolete("Bounds relative to the segment are inconsistent with our rules for always measuring from the start of the recording.")]
public double TimeStart { get; }

Property Value

Type	Description
Double

Remarks

NOTE: TimeStart is relative to the start of a segment. This notion is obsolete! Events must always be stored relative to start of the recording.

Note: converted to private setter so we can control how this is set. Recommend using SetEventPositionRelative(TimeSpan, Double, Double) after event instantiation to modify bounds.

Methods

AssignClusterIds(List<List<AcousticEvent>>)

Declaration

public static void AssignClusterIds(List<List<AcousticEvent>> clusters)

Parameters

Type	Name	Description
List<List<AcousticEvent>>	clusters

ClusterEvents(AcousticEvent[])

Although not currently used, this method and following methods could be useful in future for clustering of events.

Declaration

public static List<List<AcousticEvent>> ClusterEvents(AcousticEvent[] events)

Parameters

Type	Name	Description
AcousticEvent[]	events

Returns

Type	Description
List<List<AcousticEvent>>

ConvertEvent2Oblong(AcousticEvent)

Calculates the matrix/image indices of the acoustic event, when given the time/freq scales. This method called only by previous method:- Acousticevent.SetTimeAndFreqScales(). Translate time/freq dimensions to coordinates in a matrix. columns of matrix are the freq bins. Origin is top left - as per matrix in the sonogram class.

Declaration

public static Oblong ConvertEvent2Oblong(AcousticEvent ae)

Parameters

Type	Name	Description
AcousticEvent	ae

Returns

Type	Description
Oblong

ConvertHertzToFrequencyBin(Boolean, Int32, Int32, Int32, Double, out Int32, out Int32)

Converts the Hertz (frequency) bounds of an event to the frequency bin number. The frequency bin is an index into the columns of the spectrogram data matrix. Since the spectrogram data matrix is oriented with the origin at top left, the low frequency bin will have a lower column index than the high freq bin.

Declaration

public static void ConvertHertzToFrequencyBin(bool doMelscale, int minFreq, int maxFreq, int nyquist, double binWidth, out int leftCol, out int rightCol)

Parameters

Type	Name	Description
Boolean	doMelscale	mel scale.
Int32	minFreq	lower freq bound.
Int32	maxFreq	upper freq bound.
Int32	nyquist	Nyquist freq in Herz.
Double	binWidth	frequency scale.
Int32	leftCol	return bin index for lower freq bound.
Int32	rightCol	return bin index for upper freq bound.

ConvertIntensityArray2Events(Double[], TimeSpan, Int32, Int32, Double, Double, Double, Double, Double)

Declaration

public static List<AcousticEvent> ConvertIntensityArray2Events(double[] values, TimeSpan segmentStartOffset, int minHz, int maxHz, double framesPerSec, double freqBinWidth, double scoreThreshold, double minDuration, double maxDuration)

Parameters

Type	Name	Description
Double[]	values
TimeSpan	segmentStartOffset
Int32	minHz
Int32	maxHz
Double	framesPerSec
Double	freqBinWidth
Double	scoreThreshold
Double	minDuration
Double	maxDuration

Returns

Type	Description
List<AcousticEvent>

ConvertScoreArray2Events(Double[], Int32, Int32, Double, Double, Double, Double, Double, TimeSpan)

A general method to convert an array of score values to a list of AcousticEvents. NOTE: The score array is assumed to be temporal i.e. each element of the array is derived from a time frame. The method uses the passed scoreThreshold in order to calculate a normalised score. Max possible score := threshold * 5. normalised score := score / maxPossibleScore. Some analysis techniques (e.g. Oscillation Detection) have their own methods for extracting events from score arrays.

Declaration

public static List<AcousticEvent> ConvertScoreArray2Events(double[] scores, int minHz, int maxHz, double framesPerSec, double freqBinWidth, double scoreThreshold, double minDuration, double maxDuration, TimeSpan segmentStart)

Parameters

Type	Name	Description
Double[]	scores	the array of scores.
Int32	minHz	lower freq bound of the acoustic event.
Int32	maxHz	upper freq bound of the acoustic event.
Double	framesPerSec	the time scale required by AcousticEvent class.
Double	freqBinWidth	the freq scale required by AcousticEvent class.
Double	scoreThreshold	threshold.
Double	minDuration	duration of event must exceed this to count as an event.
Double	maxDuration	duration of event must be less than this to count as an event.
TimeSpan	segmentStart	offset.

Returns

Type	Description
List<AcousticEvent>	a list of acoustic events.

DistanceFromCluster(AcousticEvent, List<AcousticEvent>)

Declaration

public static double DistanceFromCluster(AcousticEvent ae, List<AcousticEvent> cluster)

Parameters

Type	Name	Description
AcousticEvent	ae
List<AcousticEvent>	cluster

Returns

Type	Description
Double

DrawEvent<T>(Image<T>, Double, Double, Int32)

Draws an event on the image. Allows for custom specification of variables. Drawing the event requires a time scale and a frequency scale. Hence the additional arguments.

Declaration

public void DrawEvent<T>(Image<T> imageToReturn, double framesPerSecond, double freqBinWidth, int sonogramHeight)
    where T : struct, IPixel<T>

Parameters

Type	Name	Description
SixLabors.ImageSharp.Image<T>	imageToReturn
Double	framesPerSecond
Double	freqBinWidth
Int32	sonogramHeight

Type Parameters

Name	Description
T

EventsOverlapInTime(AcousticEvent, AcousticEvent)

Determines if two events overlap in time.

Declaration

public static bool EventsOverlapInTime(AcousticEvent event1, AcousticEvent event2)

Parameters

Type	Name	Description
AcousticEvent	event1	event one.
AcousticEvent	event2	event two.

Returns

Type	Description
Boolean	true if events overlap.

ExtractScoreArrayFromEvents(List<AcousticEvent>, Int32, String)

FOR POSSIBLE DELETION! THis method called only once from a frog recogniser class that is no longer used> LitoriaCaerulea:RecognizerBase. THis method is potentially useful but can be deleted. Attempts to reconstruct an array of scores from a list of acoustic events. The events are required to have the passed name (a filter). The events are assumed to contain sufficient info about frame rate in order to populate the array.

Declaration

public static double[] ExtractScoreArrayFromEvents(List<AcousticEvent> events, int arraySize, string nameOfTargetEvent)

Parameters

Type	Name	Description
List<AcousticEvent>	events
Int32	arraySize
String	nameOfTargetEvent

Returns

Type	Description
Double[]

GetEventAsRectangle()

Should check that Oblong is not null before calling this method.

Declaration

public Rectangle GetEventAsRectangle()

Returns

Type	Description
SixLabors.ImageSharp.Rectangle

GetEventsAroundMaxima(Double[], TimeSpan, Int32, Int32, Double, TimeSpan, TimeSpan, Double, Double)

Given a time series of acoustic amplitude (typically in decibels), finds events that match the passed constraints.

Declaration

public static List<AcousticEvent> GetEventsAroundMaxima(double[] values, TimeSpan segmentStartOffset, int minHz, int maxHz, double thresholdValue, TimeSpan minDuration, TimeSpan maxDuration, double framesPerSec, double freqBinWidth)

Parameters

Type	Name	Description
Double[]	values	an array of amplitude values, typically decibel values.
TimeSpan	segmentStartOffset	not sure what this is about!.
Int32	minHz	minimum freq of event.
Int32	maxHz	maximum freq of event.
Double	thresholdValue	event threshold in same units as the value array.
TimeSpan	minDuration	minimum duration of an event.
TimeSpan	maxDuration	maximum duration of an event.
Double	framesPerSec	the time scale - required for drawing events.
Double	freqBinWidth	the frequency scale - required for drawing events.

Returns

Type	Description
List<AcousticEvent>	an array of class AcousticEvent.

GetEventsInFile(List<AcousticEvent>, String)

returns all the events in a list that occur in the recording with passed file name.

Declaration

public static List<AcousticEvent> GetEventsInFile(List<AcousticEvent> eventList, string fileName)

Parameters

Type	Name	Description
List<AcousticEvent>	eventList
String	fileName

Returns

Type	Description
List<AcousticEvent>

GetSegmentationEvents(SpectrogramStandard, Boolean, TimeSpan, Int32, Int32, Double, Double, Double, Double)

Segments or not depending value of boolean doSegmentation.

Declaration

public static Tuple<List<AcousticEvent>, double, double, double, double[]> GetSegmentationEvents(SpectrogramStandard sonogram, bool doSegmentation, TimeSpan segmentStartOffset, int minHz, int maxHz, double smoothWindow, double thresholdSD, double minDuration, double maxDuration)

Parameters

Type	Name	Description
SpectrogramStandard	sonogram	s.
Boolean	doSegmentation	segment? yes/no.
TimeSpan	segmentStartOffset	time offset.
Int32	minHz	lower limit of bandwidth.
Int32	maxHz	upper limit of bandwidth.
Double	smoothWindow	window for smoothing the acoustic intensity array.
Double	thresholdSD	segmentation threshold - standard deviations above 0 dB.
Double	minDuration	minimum duration of an event.
Double	maxDuration	maximum duration of an event.

Returns

Type	Description
Tuple<List<AcousticEvent>, Double, Double, Double, Double[]>

GetSegmentationEvents(SpectrogramStandard, TimeSpan, Int32, Int32, Double, Double, Double, Double)

Segments the acoustic energy in the passed frequency band and returns as list of acoustic events. Noise reduction is done first.

Declaration

public static Tuple<List<AcousticEvent>, double, double, double, double[]> GetSegmentationEvents(SpectrogramStandard sonogram, TimeSpan segmentStartOffset, int minHz, int maxHz, double smoothWindow, double thresholdSD, double minDuration, double maxDuration)

Parameters

Type	Name	Description
SpectrogramStandard	sonogram	the full spectrogram.
TimeSpan	segmentStartOffset	Start of current segment relative to the recording start.
Int32	minHz	Bottom of the required frequency band.
Int32	maxHz	Top of the required frequency band.
Double	smoothWindow	To smooth the amplitude array.
Double	thresholdSD	Determines the threshold for an acoustic event.
Double	minDuration	Minimum duration of an acceptable acoustic event.
Double	maxDuration	Maximum duration of an acceptable acoustic event.

Returns

Type	Description
Tuple<List<AcousticEvent>, Double, Double, Double, Double[]>	a list of acoustic events.

GetTaggedEventsInFile(List<AcousticEvent>, String)

Declaration

public static List<AcousticEvent> GetTaggedEventsInFile(List<AcousticEvent> labeledEvents, string filename)

Parameters

Type	Name	Description
List<AcousticEvent>	labeledEvents
String	filename

Returns

Type	Description
List<AcousticEvent>

InitializeAcousticEvent(TimeSpan, Oblong, Int32, Int32, Double, Double, Int32)

Initializes a new instance of the AcousticEvent class. This method works ONLY for linear Hertz scale events. It requires the event bounds to provided (using Oblong) in terms of time frame and frequency bin counts. Scale information must also be provided to convert bounds into real values (seconds, Hertz).

Declaration

public static AcousticEvent InitializeAcousticEvent(TimeSpan segmentStartOffset, Oblong o, int nyquistFrequency, int binCount, double frameDuration, double frameStep, int frameCount)

Parameters

Type	Name	Description
TimeSpan	segmentStartOffset
Oblong	o	An oblong initialized with bin and frame numbers marking location of the event.
Int32	nyquistFrequency	to set the freq scale.
Int32	binCount	Number of freq bins.
Double	frameDuration	tseconds duration of a frame - to set the time scale.
Double	frameStep	seconds between frame starts i.e. frame step; i.e. inverse of frames per second. Sets the time scale for an event.
Int32	frameCount	to set the time scale.

Returns

Type	Description
AcousticEvent

OverlapsEventInList(List<AcousticEvent>)

Returns the first event in the passed list which overlaps with this one IN THE SAME RECORDING. If no event overlaps return null.

Declaration

public AcousticEvent OverlapsEventInList(List<AcousticEvent> events)

Parameters

Type	Name	Description
List<AcousticEvent>	events

Returns

Type	Description
AcousticEvent

SetEventPositionRelative(TimeSpan, Double, Double)

Set the start and end times of an event with respect to the segment start time AND also calls method to set event start time with respect the recording/file start.

Declaration

public void SetEventPositionRelative(TimeSpan segmentStartOffset, double eventStartSegmentRelative, double eventEndSegmentRelative)

Parameters

Type	Name	Description
TimeSpan	segmentStartOffset
Double	eventStartSegmentRelative
Double	eventEndSegmentRelative

SetScores(Double, Double, Double)

Sets the passed score and also a value normalised between a min and a max.

Declaration

public void SetScores(double score, double min, double max)

Parameters

Type	Name	Description
Double	score
Double	min
Double	max

SetTimeAndFreqScales(Double, Double)

This method assumes that there is no frame overlap i.e. frame duration = frame offset.

Declaration

public void SetTimeAndFreqScales(double framesPerSec, double freqBinWidth)

Parameters

Type	Name	Description
Double	framesPerSec	frames per second assuming no overlap.
Double	freqBinWidth	Number of hertz per freq bin.

SetTimeAndFreqScales(Double, Double, Double)

Declaration

public void SetTimeAndFreqScales(double frameOffset, double frameDuration, double freqBinWidth)

Parameters

Type	Name	Description
Double	frameOffset
Double	frameDuration
Double	freqBinWidth

SetTimeAndFreqScales(Int32, Int32, Int32)

THe only call to this method is from a no-longer used recogniser. Could be deleted. It sets the time and frequency scales for an event given the sr, and window size.

Declaration

public void SetTimeAndFreqScales(int samplingRate, int windowSize, int windowOffset)

Parameters

Type	Name	Description
Int32	samplingRate
Int32	windowSize
Int32	windowOffset

Explicit Interface Implementations

ITemporalEvent.EventDurationSeconds

Declaration

double ITemporalEvent.EventDurationSeconds { get; }

Returns

Type	Description
Double

ITemporalEvent.EventEndSeconds

Declaration

double ITemporalEvent.EventEndSeconds { get; }

Returns

Type	Description
Double

IInstantEvent.EventStartSeconds

Declaration

double IInstantEvent.EventStartSeconds { get; }

Returns

Type	Description
Double

ISpectralBand.BandWidthHertz

Declaration

double ISpectralBand.BandWidthHertz { get; }

Returns

Type	Description
Double

ISpectralBand.HighFrequencyHertz

Declaration

double ISpectralBand.HighFrequencyHertz { get; }

Returns

Type	Description
Double

ISpectralBand.LowFrequencyHertz

Declaration

double ISpectralBand.LowFrequencyHertz { get; }

Returns

Type	Description
Double

Implements

System.IComparable<T>

System.IComparable

ISpectralEvent

ISpectralBand

ITemporalEvent

IInstantEvent

Extension Methods

ObjectExtensions.NotNull(Object)

ObjectExtensions.AsArray<T>(T)

ObjectExtensions.AsList<T>(T)

ObjectExtensions.Wrap<T>(T)

SystemExtensions.BinarySerialize(Object)

ConfigFileExtensions.NotNull(Object, FileInfo, String, String)

ConfigFileExtensions.ValidateNotNull(Object, String, String)

ConfigFileExtensions.ValidateLessThan<T>(Object, Nullable<T>, String, Nullable<T>, String, String)

ExtensionsXml.SerializeObject<T>(T)

EventConverters.ConvertAcousticEventToSpectralEvent(AcousticEvent)