edu.nrao.sss.measure
Class FrequencySpectrum

java.lang.Object
  edu.nrao.sss.measure.FrequencySpectrum

All Implemented Interfaces:

Cloneable

public class FrequencySpectrum
extends Object
implements Cloneable

A collection of disjoint (non-overlapping, non-contiguous) frequency ranges. These ranges are said to be "covered" portions of the spectrum.

The span of this spectrum goes from the low frequency of its lowest covered range through the high frequency of its highest covered range. This spectrum contains only covered frequency ranges -- it does not handle covered frequency points. (An approximation of a covered single frequency can be made by using an extremely narrow range.)

Version Info:

$Revision$

$Date$

$Author$

Since:

2007-01-11

Author:

David M. Harland

Constructor Summary

FrequencySpectrum()
Creates a new spectrum with no covered ranges and, therefore, a span of zero Hertz.

FrequencySpectrum(Collection<FrequencyRange> ranges)
Creates a new spectrum using the given collection of covered ranges.

Method Summary

FrequencySpectrum	addCoveredRange(FrequencyRange newRange) Adds a new frequency range to our set of covered ranges.
void	addCoveredRanges(String spectrumText) Adds new covered ranges to this spectrum by parsing spectrumText.
void	clear() Removes all covered ranges from this spectrum.
FrequencySpectrum	clone() Returns a copy of this spectrum.
boolean	covers(Frequency frequency) Returns true if this spectrum covers the given frequency.
boolean	equals(Object o) Returns true if o is equal to this spectrum.
Frequency	getAmountCovered() Returns the amount of this spectrum that is covered.
Frequency	getAmountCovered(FrequencyRange targetRange) Returns the amount of the target range that is covered by the covered portions of this spectrum.
double	getAmountCoveredAsFractionOf(FrequencyRange targetRange) Returns a number that represents the portion of the target range that is covered by the covered portions of this spectrum.
SortedSet<FrequencyRange>	getCoveredRanges() Returns the regions of this spectrum that are covered.
double	getFractionCovered() Returns a number that represents the portion of this spectrum that is covered.
FrequencyRange	getSmallestGapTo(FrequencyRange targetRange) Returns a quantity that represents the smallest gap between targetRange and the nearest of the covered ranges of this spectrum.
FrequencyRange	getSpan() Returns a range whose low frequency is that of the lowest covered range in this spectrum and whose high frequency is that of the highest covered range.
int	hashCode() Returns a hash code value for this spectrum.
FrequencySpectrum	intersectWith(FrequencyRange targetRange) Modifies this spectrum to be the intersection of its covered ranges with targetRange.
static FrequencySpectrum	parse(String spectrumText) Creates and returns a new frequency spectrum, based on spectrumText.
static FrequencySpectrum	parse(String spectrumText, String rangeSeparator) Creates and returns a new frequency spectrum, based on spectrumText.
static FrequencySpectrum	parse(String spectrumText, String rangeSeparator, String endPointSeparator) Creates and returns a new frequency spectrum, based on spectrumText.
FrequencySpectrum	removeCoveredRange(FrequencyRange unwantedRange) Removes a frequency range from our set of covered ranges.
void	set(String spectrumText) Removes all covered ranges from this spectrum and adds new ranges found in spectrumText.
void	setCoveredRanges(String spectrumText) Deprecated. Use set(String).
String	toString() Creates a text representation of this spectrum.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FrequencySpectrum

public FrequencySpectrum()

Creates a new spectrum with no covered ranges and, therefore, a span of zero Hertz.

FrequencySpectrum

public FrequencySpectrum(Collection<FrequencyRange> ranges)

Creates a new spectrum using the given collection of covered ranges.

Parameters:

ranges - the portions of this spectrum that are covered.

Method Detail

getCoveredRanges

public SortedSet<FrequencyRange> getCoveredRanges()

Returns the regions of this spectrum that are covered. The returned ranges are copies of those held by this spectrum, so they may be altered by the client without affecting this object.

Returns:

the regions of this spectrum that are covered.

getSpan

public FrequencyRange getSpan()

Returns a range whose low frequency is that of the lowest covered range in this spectrum and whose high frequency is that of the highest covered range.

For example if this spectrum has these covered ranges: 10GHz-15GHz and 50GHz-60GHz, then the span of this spectrum is 10GHz-60GHz.

Returns:

a range representing the lowest and highest frequencies covered herein.

covers

public boolean covers(Frequency frequency)

Returns true if this spectrum covers the given frequency.

Parameters:

frequency - the frequency to be tested for containment.

Returns:

true if this spectrum covers the given frequency.

getAmountCovered

public Frequency getAmountCovered()

Returns the amount of this spectrum that is covered.

For example if this spectrum has these covered ranges: 10GHz-15GHz and 50GHz-60GHz, then the amount covered is 15GHz (5GHz + 10GHz).

Returns:

the amount of this spectrum that is covered.

getAmountCovered

public Frequency getAmountCovered(FrequencyRange targetRange)

Returns the amount of the target range that is covered by the covered portions of this spectrum. In other words, the amount returned is the size of the intersection between the covered portions of this spectrum and the target range.

This method is useful when the range you want to test for coverage has a different span than the natural span of this spectrum. The span of this spectrum is defined by the low frequency of the lowest covered portion and the high frequency of the highest covered portion of this spectrum.

For example if this spectrum has these covered ranges: 10GHz-15GHz and 50GHz-60GHz, and if the target range is 0GHz-100GHz, then the amount covered is 15GHz. If, however, the target range is 35GHz-55GHz, then the amount covered is 5GHz.

Parameters:

targetRange - a range to be tested for coverage.

Returns:

the amount of the target range that is covered by the covered portions of this spectrum.

getFractionCovered

public double getFractionCovered()

Returns a number that represents the portion of this spectrum that is covered.

For example if this spectrum has these covered ranges: 10GHz-15GHz and 50GHz-60GHz, then the portion of this spectrum that is covered is 0.30. (The covered range is 15GHz and the total span is 50GHz.)

Returns:

the fraction of this spectrum that is covered. The value returned is between zero and one, inclusive (i.e., [0-1]).

getAmountCoveredAsFractionOf

public double getAmountCoveredAsFractionOf(FrequencyRange targetRange)

Returns a number that represents the portion of the target range that is covered by the covered portions of this spectrum.

For example if this spectrum has these covered ranges: 10GHz-15GHz and 50GHz-60GHz, and if the target range is 0GHz-100GHz, then the portion of this spectrum that is covered is 0.15. If, however, the target range is 35GHz-55GHz, then the portion of this spectrum that is covered is 0.25 (5GHz of overlap with the 20GHz-wide target range).

Parameters:

targetRange - a range to be tested for coverage.

Returns:

the fraction of the target range that is covered by the covered portions of this spectrum. The value returned is between zero and one, inclusive (i.e., [0-1]).

getSmallestGapTo

public FrequencyRange getSmallestGapTo(FrequencyRange targetRange)

Returns a quantity that represents the smallest gap between targetRange and the nearest of the covered ranges of this spectrum.

If the target range overlaps one or more of this spectrum's covered ranges, the returned range will have a width of zero and an arbitrary center frequency. If this spectrum has no covered ranges, the size of the range returned will be infinite.

Parameters:

targetRange - the range for which a gap is calculated.

Returns:

the smallest gap between targetRange and the nearest of this spectrum's covered ranges.

clear

public void clear()

Removes all covered ranges from this spectrum.

setCoveredRanges

@Deprecated
public void setCoveredRanges(String spectrumText)

Deprecated. Use set(String).

set

public void set(String spectrumText)

Removes all covered ranges from this spectrum and adds new ranges found in spectrumText. See parse(String) for details about the parsing methodology.

Parameters:

spectrumText - text representation of a FrequencySpectrum.

addCoveredRanges

public void addCoveredRanges(String spectrumText)

Adds new covered ranges to this spectrum by parsing spectrumText. See parse(String) for details about the parsing methodology.

Parameters:

spectrumText - text representation of a FrequencySpectrum.

addCoveredRange

public FrequencySpectrum addCoveredRange(FrequencyRange newRange)

Adds a new frequency range to our set of covered ranges.

The addition of a new range can take one of several tracks:

1. If newRange is null, this object is not changed.
2. If newRange has no overlap with any existing range, nor is contiguous with any existing range, then a copy of it is added to this object.
3. If newRange overlaps, or is continguous, with one or more existing ranges, the single union of all those ranges replaces those ranges.

Examples:

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   New Range:                       +++
   After Addition:  ~~~~~~~~  ~~~~  ~~~ ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   New Range:                             +++
   After Addition:  ~~~~~~~~  ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   New Range:          +++++
   After Addition:  ~~~~~~~~  ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   New Range:          +++++++++
   After Addition:  ~~~~~~~~~~~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   New Range:          ++++++++++++++++++++++++++++++++++++
   After Addition:  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   ~~~~~~~~~
 

Parameters:

newRange - the range to be added to our set of covered ranges.

Returns:

this instance.

removeCoveredRange

public FrequencySpectrum removeCoveredRange(FrequencyRange unwantedRange)

Removes a frequency range from our set of covered ranges.

Examples:

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   Unwanted Range:                  ---
   After Removal:   ~~~~~~~~  ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   Unwanted Range:                        ---
   After Removal:   ~~~~~~~~  ~~~~      ~~   ~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   Unwanted Range:     -----
   After Removal:   ~~~       ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   Unwanted Range:     ---------
   After Removal:   ~~~         ~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
 

   Existing Ranges: ~~~~~~    ~~~~      ~~~~~~~~~~~~    ~~~~~~~   ~~~~~~~~~
   Unwanted Range:     ------------------------------------
   After Removal:   ~~~                                    ~~~~   ~~~~~~~~~
 

Parameters:

unwantedRange - the range to be removed from our set of covered ranges.

Returns:

this instance.

intersectWith

public FrequencySpectrum intersectWith(FrequencyRange targetRange)

Modifies this spectrum to be the intersection of its covered ranges with targetRange. If this range does not intersect with other, it will have no covered ranges after the intersection.

Parameters:

targetRange - the frequency range with which this spectrum should be intersected.

Returns:

this spectrum after the intersection.

toString

public String toString()

Creates a text representation of this spectrum.

Overrides:

toString in class Object

parse

public static FrequencySpectrum parse(String spectrumText)

Creates and returns a new frequency spectrum, based on spectrumText.

This is a convenience method that is equivalent to calling FrequencySpectrum.parse(spectrumText, ",", "-").

Parameters:

spectrumText - text representation of a FrequencySpectrum.

Returns:

a new spectrum, based on spectrumText.

parse

public static FrequencySpectrum parse(String spectrumText,
                                      String rangeSeparator)

Creates and returns a new frequency spectrum, based on spectrumText.

This is a convenience method that is equivalent to calling FrequencySpectrum.parse(spectrumText, rangeSeparator, "-").

Parameters:

spectrumText - text representation of a FrequencySpectrum.

rangeSeparator - text used to separate the endpoints of a frequency range.

Returns:

a new spectrum, based on spectrumText.

parse

public static FrequencySpectrum parse(String spectrumText,
                                      String rangeSeparator,
                                      String endPointSeparator)

Creates and returns a new frequency spectrum, based on spectrumText.

The spectrumText is nothing more than a list of delimited frequency ranges. To learn more about how frequency ranges are parsed, see FrequencyRange.parse(String). Each of these ranges is delimited by rangeSeparator.

This method will attempt to parse the entire text and make use of any ranges that are successfully interpreted. If there are any parsing errors, an IllegalArgumentException will be thrown, listing each of the errors in its message.

If spectrumText is null or the empty string (""), the returned range will be equal to one created via the no-argument constructor.

Parameters:

spectrumText - text representation of a FrequencySpectrum.

rangeSeparator - text used to separate the endpoints of a frequency range.

endPointSeparator - text that separates one frequency range from another in spectrumText.

Returns:

a new spectrum, based on spectrumText.

clone

public FrequencySpectrum clone()

Returns a copy of this spectrum.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this spectrum.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this spectrum.

Overrides:

hashCode in class Object