create_spectra

create_spectra

This module contains end user functions for creating the TS spectra from the tabulated parameters

create_enveloped_spectra(location_id: str, apoe_n: int, site_class_list: List[str], periods: List[float] = DEFAULT_PERIODS, precision: int = 3) -> pdt.DataFrame

Creates a set of site class spectra for a given location_id and APoE

Parameters:

Name	Type	Description	Default
location_id	str	label for a TS location (e.g., 'Wellington' or '-47.3~167.8')	required
apoe_n	int	shorthand for APoE (1/n) # this is commonly known as a return period	required
site_class_list	List[str]	list of TS site class label (e.g., ['III',IV'])	required
periods	List[float]	list of periods [seconds] at which to calculate the spectrum	DEFAULT_PERIODS
precision	int	number of decimals to include in output	3

Returns:

Name	Type	Description
enveloped_spectra	pdt.DataFrame	dataframe of spectra for each period (rows), spectrum and the combined envelope (columns)

Source code in nzssdt_2023/end_user_functions/create_spectra.py

def create_enveloped_spectra(
    location_id: str,
    apoe_n: int,
    site_class_list: List[str],
    periods: List[float] = DEFAULT_PERIODS,
    precision: int = 3,
) -> "pdt.DataFrame":
    """Creates a set of site class spectra for a given location_id and APoE

    Args:
        location_id: label for a TS location (e.g., 'Wellington' or '-47.3~167.8')
        apoe_n: shorthand for APoE (1/n)  # this is commonly known as a return period
        site_class_list: list of TS site class label (e.g., ['III',IV'])
        periods: list of periods [seconds] at which to calculate the spectrum
        precision: number of decimals to include in output

    Returns:
        enveloped_spectra: dataframe of spectra for each period (rows), spectrum and the combined envelope (columns)

    """

    df = pd.DataFrame()
    df["Period"] = periods

    for sc in site_class_list:
        pga, sas, tc, td = retrieve_sa_parameters(location_id, apoe_n, sc)
        df[sc] = create_spectrum_from_parameters(pga, sas, tc, td, periods, precision)

    df["Envelope"] = np.max(df.loc[:, df.columns != "Period"], axis=1)
    enveloped_spectra = df.round(precision)

    return enveloped_spectra

create_spectrum_from_parameters(pga: float, sas: float, tc: float, td: float, periods: List[float] = DEFAULT_PERIODS, precision: int = 3) -> List[float]

Creates the TS spectrum based on the incoming pga, sas, tc, and td parameters

Parameters:

Name	Type	Description	Default
pga	float	peak ground acceleration [g]	required
sas	float	short-period spectral acceleration [g]	required
tc	float	spectral-acceleration-plateau corner period [seconds]	required
td	float	spectral-velocity-plateau corner period [seconds]	required
periods	List[float]	list of periods [seconds] at which to calculate the spectrum	DEFAULT_PERIODS
precision	int	number of decimals to include in output	3

Returns:

Name	Type	Description
spectrum	List[float]	acceleration spectrum [g] calculated at the incoming list of periods

Source code in nzssdt_2023/end_user_functions/create_spectra.py

def create_spectrum_from_parameters(
    pga: float,
    sas: float,
    tc: float,
    td: float,
    periods: List[float] = DEFAULT_PERIODS,
    precision: int = 3,
) -> List[float]:
    """Creates the TS spectrum based on the incoming pga, sas, tc, and td parameters

    Args:
        pga: peak ground acceleration [g]
        sas: short-period spectral acceleration [g]
        tc: spectral-acceleration-plateau corner period [seconds]
        td: spectral-velocity-plateau corner period [seconds]
        periods: list of periods [seconds] at which to calculate the spectrum
        precision: number of decimals to include in output

    Returns:
        spectrum: acceleration spectrum [g] calculated at the incoming list of periods
    """

    spectrum = np.array(
        [uhs_value(period, pga, sas, tc, td) for period in periods]
    ).round(precision)

    return list(spectrum)