gov.usgs.earthquake.nshmp.mfd

Class Mfds

java.lang.Object

gov.usgs.earthquake.nshmp.mfd.Mfds

public final class Mfds
extends Object

Factory and utility methods for working with magnitude frequency distributions (Mfds). TODO note application guidance implied by floats() TODO should Incremental Mfds really descend from EvenlyDiscretizedFunction; if someone passes in non-uniformely spaced mag values, there will be problems

Author:

Peter Powers

Field Summary

Fields

Modifier and Type	Field and Description
static Range<Double>	TIMESPAN_RANGE Supported timespans for Poisson probabilities: [1..10000] years.

Method Summary

Modifier and Type	Method and Description
static Converter<Double,Double>	annualRateToProbabilityConverter() Return a converter between annual rate and Poisson probability over a 1-year time span.
static Converter<Double,Double>	annualRateToProbabilityConverter(double timespan) Return a converter between annual rate and Poisson probability over the specified time span.
static XySequence	combine(IncrementalMfd... mfds) Deprecated.
static double	grRate(double a, double b, double M) Returns the Gutenberg Richter event rate for the supplied a- and b-values and magnitude.
static double	incrRate(double a, double b, double mMin) Computes the Gutenberg-Richter incremental rate at the supplied magnitude.
static int	magCount(double mMin, double mMax, double dMag) Determines the number of magnitude bins for the supplied arguments.
static gov.usgs.earthquake.nshmp.mfd.GaussianMfd	newGaussianMFD(double mean, double sigma, int size, double cumRate, boolean floats) Creates a new GaussianMfd that is doubly-truncated at 2*sigma.
static gov.usgs.earthquake.nshmp.mfd.GaussianMfd	newGaussianMoBalancedMFD(double mean, double sigma, int size, double moRate, boolean floats) Creates a new moment-balanced GaussianMfd that is doubly-truncated at 2*sigma.
static gov.usgs.earthquake.nshmp.mfd.GutenbergRichterMfd	newGutenbergRichterMFD(double min, double delta, int size, double b, double cumRate) Creates a new GutenbergRichterMfd.
static gov.usgs.earthquake.nshmp.mfd.GutenbergRichterMfd	newGutenbergRichterMoBalancedMFD(double min, double delta, int size, double b, double moRate) Creates a new moment-balanced GutenbergRichterMfd.
static IncrementalMfd	newIncrementalMFD(double[] mags, double[] rates) Creates a new IncrementalMfd with the supplied magnitudes and rates.
static IncrementalMfd	newSingleMFD(double mag, double cumRate, boolean floats) Creates a new single magnitude IncrementalMfd.
static IncrementalMfd	newSingleMoBalancedMFD(double mag, double moRate, boolean floats) Creates a new single magnitude moment-balanced IncrementalMfd.
static IncrementalMfd	newTaperedGutenbergRichterMFD(double min, double delta, int size, double a, double b, double corner, double weight)
static double	probToRate(double P, double timespan) Given the Poisson probability of the occurence of some event over a specified time period, method returns the annual rate of occurrence of that event.
static double	rateToProb(double rate, double timespan) Given an observed annual rate of occurrence of some event (in num/yr), method returns the Poisson probability of occurence over the specified time period.
static XySequence	toCumulative(XySequence incremental)
static XySequence	toMutableSequence(IncrementalMfd mfd) Convert an IncrementalMfd to a mutable XySequence.
static XySequence	toSequence(IncrementalMfd mfd) Convert an IncrementalMfd to an immutable XySequence.
static double	totalMoRate(double mMin, int nMag, double dMag, double a, double b) Computes total moment rate as done by NSHMP code from supplied magnitude info and the Gutenberg-Richter a- and b-values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TIMESPAN_RANGE

public static final Range<Double> TIMESPAN_RANGE

Supported timespans for Poisson probabilities: [1..10000] years.

Method Detail

newSingleMFD

public static IncrementalMfd newSingleMFD(double mag,
                                          double cumRate,
                                          boolean floats)

Creates a new single magnitude IncrementalMfd.

Parameters:

mag - for MFD

cumRate - total cumulative event rate for lone magnitude bin

floats - true if ruptures referencing this mfd should float; false otherwise

Returns:

a new IncrementalMfd

newSingleMoBalancedMFD

public static IncrementalMfd newSingleMoBalancedMFD(double mag,
                                                    double moRate,
                                                    boolean floats)

Creates a new single magnitude moment-balanced IncrementalMfd.

Parameters:

mag - for MFD

moRate - total moment rate of lone magnitude bin

floats - true if ruptures referencing this mfd should float; false otherwise

Returns:

a new IncrementalMfd

newIncrementalMFD

public static IncrementalMfd newIncrementalMFD(double[] mags,
                                               double[] rates)

Creates a new IncrementalMfd with the supplied magnitudes and rates. For the MFD returned, IncrementalMfd.floats() always returns true.

NOTE: This method expects evenly spaced magnitudes; if they are not, results are undefined.

Parameters:

mags - for MFD

rates - for MFD

Returns:

a new IncrementalMfd

newGaussianMFD

public static gov.usgs.earthquake.nshmp.mfd.GaussianMfd newGaussianMFD(double mean,
                                                                       double sigma,
                                                                       int size,
                                                                       double cumRate,
                                                                       boolean floats)

Creates a new GaussianMfd that is doubly-truncated at 2*sigma.

Parameters:

mean - magnitude

sigma - standard deviation

size - number of magnitude bins inclusive of min and max magnitudes

cumRate - total cumulative rate

floats - true if ruptures referencing this mfd should float; false otherwise

Returns:

a new GaussianMfd

newGaussianMoBalancedMFD

public static gov.usgs.earthquake.nshmp.mfd.GaussianMfd newGaussianMoBalancedMFD(double mean,
                                                                                 double sigma,
                                                                                 int size,
                                                                                 double moRate,
                                                                                 boolean floats)

Creates a new moment-balanced GaussianMfd that is doubly-truncated at 2*sigma. For the MFD returned, IncrementalMfd.floats() always returns false.

Parameters:

mean - magnitude

sigma - standard deviation

size - number of magnitude bins inclusive of min and max magnitudes

moRate - total moment rate

floats - true if ruptures referencing this mfd should float; false otherwise

Returns:

a new GaussianMfd

newGutenbergRichterMFD

public static gov.usgs.earthquake.nshmp.mfd.GutenbergRichterMfd newGutenbergRichterMFD(double min,
                                                                                       double delta,
                                                                                       int size,
                                                                                       double b,
                                                                                       double cumRate)

Creates a new GutenbergRichterMfd. For the MFD returned, IncrementalMfd.floats() always returns true.

Parameters:

min - magnitude

delta - magnitude

size - number of magnitude bins inclusive of min and max magnitudes

b - value (slope of GR relation)

cumRate - total cumulative rate

Returns:

a new GutenbergRichterMfd

newGutenbergRichterMoBalancedMFD

public static gov.usgs.earthquake.nshmp.mfd.GutenbergRichterMfd newGutenbergRichterMoBalancedMFD(double min,
                                                                                                 double delta,
                                                                                                 int size,
                                                                                                 double b,
                                                                                                 double moRate)

Creates a new moment-balanced GutenbergRichterMfd. For the MFD returned, IncrementalMfd.floats() always returns true.

Parameters:

min - magnitude

delta - magnitude

size - number of magnitude bins inclusive of min and max magnitudes

b - value (slope of GR relation)

moRate - total moment rate

Returns:

a new GutenbergRichterMfd

newTaperedGutenbergRichterMFD

public static IncrementalMfd newTaperedGutenbergRichterMFD(double min,
                                                           double delta,
                                                           int size,
                                                           double a,
                                                           double b,
                                                           double corner,
                                                           double weight)

totalMoRate

public static double totalMoRate(double mMin,
                                 int nMag,
                                 double dMag,
                                 double a,
                                 double b)

Computes total moment rate as done by NSHMP code from supplied magnitude info and the Gutenberg-Richter a- and b-values. Note: the a- and b-values assume an incremental distribution.

Parameters:

mMin - minimum magnitude (after adding dMag/2)

nMag - number of magnitudes

dMag - magnitude bin width

a - value (incremental and defined wrt dMag for M0)

b - value

Returns:

the total moment rate

grRate

public static double grRate(double a,
                            double b,
                            double M)

Returns the Gutenberg Richter event rate for the supplied a- and b-values and magnitude.

Parameters:

a - value (log10 rate of M=0 events)

b - value

M - magnitude of interest

Returns:

the rate of magnitude M events

incrRate

public static double incrRate(double a,
                              double b,
                              double mMin)

Computes the Gutenberg-Richter incremental rate at the supplied magnitude. Convenience method for N(M) = a*(10^-bm). TODO is this confusing? the NSHMP stores a-values in different ways [a A] where a = log10(A); should users just supply grRate() with

Parameters:

a - value (incremental and defined wrt dMag for M0)

b - value

mMin - minimum magnitude of distribution

Returns:

the rate at the supplied magnitude

magCount

public static int magCount(double mMin,
                           double mMax,
                           double dMag)

Determines the number of magnitude bins for the supplied arguments. If dMag does not divide evenly into mMax - mMin, and the result of this method is used to build a Gutenberg-Richter MFD, the maximum magnitude of the MFD may not equal the mMax supplied here.

Parameters:

mMin - minimum magnitude to consider

mMax - maximum magnitude to consider

dMag - magnitude delta

Returns:

the number of magnitude bins

rateToProb

public static double rateToProb(double rate,
                                double timespan)

Given an observed annual rate of occurrence of some event (in num/yr), method returns the Poisson probability of occurence over the specified time period.

Parameters:

rate - (annual) of occurence of some event

timespan - of interest

Returns:

the Poisson probability of occurrence in the specified time

probToRate

public static double probToRate(double P,
                                double timespan)

Given the Poisson probability of the occurence of some event over a specified time period, method returns the annual rate of occurrence of that event.

Parameters:

P - the Poisson probability of an event's occurrence

timespan - of interest

Returns:

the annnual rate of occurrence of the event

annualRateToProbabilityConverter

public static Converter<Double,Double> annualRateToProbabilityConverter()

Return a converter between annual rate and Poisson probability over a 1-year time span. The converter expects probabilities to be represented as fractions of 1.0.

annualRateToProbabilityConverter

public static Converter<Double,Double> annualRateToProbabilityConverter(double timespan)

Return a converter between annual rate and Poisson probability over the specified time span. The converter expects probabilities to be represented as fractions of 1.0.

toSequence

public static XySequence toSequence(IncrementalMfd mfd)

Convert an IncrementalMfd to an immutable XySequence.

Parameters:

mfd - to convert

Returns:

a sequence populated with the values of the supplied IncrementalMfd.

toMutableSequence

public static XySequence toMutableSequence(IncrementalMfd mfd)

Convert an IncrementalMfd to a mutable XySequence.

Parameters:

mfd - to convert

Returns:

a sequence populated with the values of the supplied IncrementalMfd.

combine

@Deprecated
public static XySequence combine(IncrementalMfd... mfds)

Deprecated.

Combine all mfds into a single sequence.

Parameters:

mfds -

toCumulative

public static XySequence toCumulative(XySequence incremental)