Package gov.usgs.earthquake.nshmp.mfd

Class Mfd

java.lang.Object

gov.usgs.earthquake.nshmp.mfd.Mfd

public final class Mfd
extends Object

Entry point for creating a magnitude frequency distribution (MFD). An MFD defines the incremental rate of earthquakes at one or more magnitudes. MFD values are backed by an immutable XySequence, however their construction is varied.

Factory methods are provided to directly create incremental MFD builders for different MFD types. Note that the Mfd.Builder class also includes factory methods to initialize builders from data or a copy of an existing MFD. Once obtained, a builder can be used to scale and shape the MFD prior to calling build(). Example:

 Mfd mfd = Mfds.newGutenbergRighterBuilder(5.0, 7.5, 0.1, 1.0)
     .scaleToCumulativeRate(0.02)
     .transform(p -> p.set((p.x() > 6.5) ? p.y() * 0.667 : p.y()))
     .build()
 

In the example above, an MFD with a Gutenberg–Richter distribution of rates is initialized from M=5.0 to M=7.5 with a step size of 0.1 magnitude units. The resultant MFD will have magnitudes [5.05, 5.15, 5.25, ... , 7.35, 7.45] centered on the 0.1 magnitude intervals spanning the magnitude range [5.0..7.5]. The MFD is then scaled to the cumulative rate of 0.02 events/year, and lastly those rates above M=6.5 are scaled to ⅔ of their present value. Note that an MFD builder executes methods in the order defined, so reversing scaleToCumulativeRate() and transform() in the example above results in two different MFDs. Note also that builders are reusable, but any calls to Mfd.Builder.transform(Consumer) can irrevocably change the state of the builder between build() calls.

MFD Mfd.Properties hold references to the parameters used to initialize an MFD, including its Mfd.Type. Properties objects may be constructed directly and support a Mfd.Properties.toBuilder() method. The the Mfd.Type will be INCREMENTAL if the MFD was created directly from magnitude and rate data or is the result of combining more than one MFD via Mfds.combine(java.util.Collection). Similarly, properties may not align with an associated MFD downstream if a builder initialized with a set of properties has been used to create multiple MFDs with variably scaled rates or transformed in various ways. Note also that when MFDs are combined, the resulting combined MFD will be of type: Mfd.Type.INCR.

Users of MFDs are encouraged take advantage of the conveniences of the underlying XySequence, especially streaming support. For example, to compute the cumulative rate of events in an MFD, one should use mfd.data().yValues().sum().

Author:

U.S. Geological Survey

See Also:

Mfds, XySequence

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Mfd.Builder	Magnitude frequency distribution (MFD) builder.
static class	Mfd.Properties	Properties object associated with a MFD.
static class	Mfd.Type	Magnitude-frequency distribution (MFD) type identifier.

Method Summary

Modifier and Type	Method	Description
static Mfd	create(double[] magnitudes, double[] rates)	Create an MFD from copies of the supplied arrays.
static Mfd	create(XySequence xy)	Create an MFD from the supplied sequence.
static Mfd	create(XySequence xy, Mfd.Properties props)	Create an MFD from the supplied sequence and properties.
XySequence	data()	The immutable values representing this MFD.
static Mfd.Builder	newGaussianBuilder(double m, int nm, double sigma, int nSigma)	Create an Mfd.Builder for a doubly-truncated Gaussian MFD.
static Mfd.Builder	newGutenbergRichterBuilder(double b, double mDelta, double mMin, double mMax)	Create an Mfd.Builder for a truncated Gutenberg–Richter MFD.
static Mfd.Builder	newSingleBuilder(double magnitude)	Create an Mfd.Builder for a single magnitude with a rate of one.
static Mfd.Builder	newTaperedGutenbergRichterBuilder(double b, double mDelta, double mMin, double mMax, double mc)	Create an Mfd.Builder for a truncated Gutenberg–Richter MFD with an exponential taper.
Mfd.Properties	properties()	The properties used to initialize the MFD.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

data

public XySequence data()

The immutable values representing this MFD.

properties

public Mfd.Properties properties()

The properties used to initialize the MFD.

toString

public String toString()

Overrides:

toString in class Object

create

public static Mfd create(double[] magnitudes,
                         double[] rates)

Create an MFD from copies of the supplied arrays. The returned MFD will be of type: Mfd.Type.INCR.

Parameters:

magnitudes - to wrap in a MFD

rates - to wrap in a MFD

Throws:

IllegalArgumentException - if magnitudes is empty

IllegalArgumentException - if magnitudes and rates are not the same size

IllegalArgumentException - if magnitudes does not increase monotonically or contains repeated values

IllegalArgumentException - if magnitudes or rates contain invalid values per Earthquakes.checkMagnitude(double) and Mfds.checkRate(double)

create

public static Mfd create(XySequence xy)

Create an MFD from the supplied sequence. The returned MFD will be of type: Mfd.Type.INCR. The supplied sequence will only be copied if necessary.

Parameters:

xy - data to wrap in an MFD

Throws:

IllegalArgumentException - if sequence contains invalid magnitudes (x-values) or rates (y-values) per Earthquakes.checkMagnitude(double) and Mfds.checkRate(double)

create

public static Mfd create(XySequence xy,
                         Mfd.Properties props)

Create an MFD from the supplied sequence and properties. This method assumes the supplied sequence has been created consistent with the supplied properties. Users will have little use for this method; it is used internally for magnitude array optimizations.

Parameters:

xy - data to wrap in an MFD

props -

Throws:

IllegalArgumentException - if sequence contains invalid magnitudes (x-values) or rates (y-values) per Earthquakes.checkMagnitude(double) and Mfds.checkRate(double)

newSingleBuilder

public static Mfd.Builder newSingleBuilder(double magnitude)

Create an Mfd.Builder for a single magnitude with a rate of one.

Parameters:

magnitude -

Throws:

IllegalArgumentException - if magnitude is outside the range [-2.0..9.7]

newGaussianBuilder

public static Mfd.Builder newGaussianBuilder(double m,
                                             int nm,
                                             double sigma,
                                             int nSigma)

Create an Mfd.Builder for a doubly-truncated Gaussian MFD. Gaussian MFDs are typically used to represent aleatory variability in magnitude. When building the underlying magnitude distribution, this implementation rounds each magnitude to 5 decimal places. This implementation constructs a distribution that is m ± 2σ wide and represented by nm evenly distributed magnitude values. The initial distribution integrates to one. The MFD, once built, will be of type: Mfd.Type.SINGLE as it represents a single magnitude combined with a model of uncertainty. In the context of a hazard model, a normal distribution of magnitudes is typically used to represent aleatory variability.

Parameters:

m - the mean magnitude

nm - the number of magnitudes in the resultant distribution

sigma - the standard deviation

nSigma - the number of standard deviations about m

Throws:

IllegalArgumentException - if m is outside the range [-2.0..9.7]

IllegalArgumentException - if nm is outside the range [1..21]

IllegalArgumentException - if sigma is outside the range (0..0.5]

IllegalArgumentException - if nSigma is outside the range [0..5]

newGutenbergRichterBuilder

public static Mfd.Builder newGutenbergRichterBuilder(double b,
                                                     double mDelta,
                                                     double mMin,
                                                     double mMax)

Create an Mfd.Builder for a truncated Gutenberg–Richter MFD. When building the underlying magnitude distribution, this implementation rounds each magnitude to 4 decimal places. Note that mMin and mMax define the lowermost and uppermost magnitude bin edges in a magnitude distribution, respectively, and that magnitude values in a Gutenberg-Richter MFD are defined as bin centers. That is, if mMin = 5.0 and Δm = 0.1, the first magnitude in the distribution will be mMin + Δm / 2 = 5.05.

Parameters:

b - the Gutenberg-Richter b-value

mDelta - the magnitude step of the distribution

mMin - the minimum truncation magnitude

mMax - the maximum truncation magnitude

Throws:

IllegalArgumentException - if mMin or mMax is outside the range [-2.0..9.7]

IllegalArgumentException - if mMin > mMax

IllegalArgumentException - if mDelta > mMax - mMin

IllegalArgumentException - if b is outside the range [0..3]

newTaperedGutenbergRichterBuilder

public static Mfd.Builder newTaperedGutenbergRichterBuilder(double b,
                                                            double mDelta,
                                                            double mMin,
                                                            double mMax,
                                                            double mc)

Create an Mfd.Builder for a truncated Gutenberg–Richter MFD with an exponential taper. This implementation uses the scalar seismic moment based distribution of Kagan (2002), Equation 11 (see Mfds.paretoRate(double, double, double, double) for reference) to compute scale factors for each magnitude bin that are then applied to a standard Gutenberg–Richter distribution. When building the underlying magnitude distribution, this implementation rounds each magnitude to 4 decimal places. Note that mMin and mMax define the lowermost and uppermost magnitude bin edges in a magnitude distribution, respectively, and that magnitude values in a Gutenberg-Richter MFD are defined as bin centers. That is, if mMin = 5.0 and Δm = 0.1, the first magnitude in the distribution will be mMin + Δm / 2 = 5.05.

Parameters:

mMin - the minimum truncation magnitude

mMax - the maximum truncation magnitude

mDelta - the magnitude step of the distribution

b - the Gutenberg-Richter b-value

mc - the corner magnitude of the distribution

Throws:

IllegalArgumentException - if mMin, mMax, or mc is outside the range [-2.0..9.7]

IllegalArgumentException - if mMin > mMax or mc is not mMin < mc < mMax

IllegalArgumentException - if mDelta > mMax – mMin

IllegalArgumentException - if b is outside the range [0..3]