query_parameters

`query_parameters` ¶

This module contains end user functions for querying the TS table

`parameters_by_location_id(location_id: str) -> pdt.DataFrame` ¶

retrieves all TS parameters associated with a given location id

Parameters:

Name	Type	Description	Default
`location_id`	`str`	label for a TS location (e.g., Wellington or -47.3~167.8)	required

Returns:

Name	Type	Description
`df`	`pdt.DataFrame`	dataframe with the TS parameters by APoE (rows) and (Site Class, parameter) (multi-index columns)

Source code in nzssdt_2023/end_user_functions/query_parameters.py

def parameters_by_location_id(location_id: str) -> "pdt.DataFrame":
    """retrieves all TS parameters associated with a given location id

    Args:
        location_id: label for a TS location (e.g., Wellington or -47.3~167.8)

    Returns:
        df: dataframe with the TS parameters by APoE (rows) and (Site Class, parameter) (multi-index columns)
    """

    # initialize df for sa parameters
    index = pd.Index(APOES, name="APoE")
    columns = pd.MultiIndex.from_product(
        [SITE_CLASSES_LIST, SA_PARAMETER_NAMES], names=["Site Class", "Parameter"]
    )
    sa_df = pd.DataFrame(index=index, columns=columns)

    for apoe_n in APOE_NS:
        apoe = f"1/{apoe_n}"
        for site_class in SITE_CLASSES_LIST:
            sa_df.loc[(apoe), (site_class, slice(None))] = retrieve_sa_parameters(
                location_id, apoe_n, site_class
            )

    # initialize df for dm parameters
    columns = pd.MultiIndex.from_tuples(
        [("", "M"), ("", "D")], names=["Site Class", "Parameter"]
    )
    md_df = pd.DataFrame(index=index, columns=columns)
    for apoe_n in APOE_NS:
        apoe = f"1/{apoe_n}"
        for site_class in [SITE_CLASSES_LIST[0]]:
            m, d = retrieve_md_parameters(location_id, apoe_n, site_class)
            md_df.loc[(apoe), ("", "M")] = m
            md_df.loc[(apoe), ("", "D")] = d

    # combine md and sa parameters
    df = pd.concat([md_df, sa_df], axis=1)

    return df

`retrieve_md_parameters(location_id: str, apoe_n: int, site_class: str) -> Tuple[float, float | str]` ¶

retrieves the M and D parameters for a single line of the TS table

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`	`str`	TS site class label (e.g., 'IV')	required

Returns:

Name	Type	Description
`m`	`float`	earthquake magnitude
`d`	`float \| str`	distance to nearest fault

Source code in nzssdt_2023/end_user_functions/query_parameters.py

def retrieve_md_parameters(
    location_id: str, apoe_n: int, site_class: str
) -> Tuple[float, float | str]:
    """retrieves the M and D parameters for a single line of the TS table

    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: TS site class label (e.g., 'IV')

    Returns:
        m: earthquake magnitude
        d: distance to nearest fault
    """

    loc_idx = PARAMETER_TABLE["Location"] == location_id
    apoe_idx = PARAMETER_TABLE["APoE (1/n)"] == apoe_n
    sc_idx = PARAMETER_TABLE["Site Class"] == site_class

    idx = loc_idx & apoe_idx & sc_idx
    m, d = PARAMETER_TABLE[idx][["M", "D"]].iloc[0]

    # d values are NAN for high APoE (low apoe_n)
    if apoe_n < APOE_N_THRESHOLD_FOR_D:
        d = np.nan

    return m, d

`retrieve_sa_parameters(location_id: str, apoe_n: int, site_class: str) -> Tuple[float, float, float, float]` ¶

retrieves the spectral acceleration parameters for a single line of the TS table

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`	`str`	TS site class label (e.g., 'IV')	required

Returns:

Name	Type	Description
`pga`	`float`	peak ground acceleration
`sas`	`float`	short-period acceleration
`tc`	`float`	spectral-acceleration-plateau corner period
`td`	`float`	spectral-velocity-plateau corner period

Source code in nzssdt_2023/end_user_functions/query_parameters.py

def retrieve_sa_parameters(
    location_id: str, apoe_n: int, site_class: str
) -> Tuple[float, float, float, float]:
    """retrieves the spectral acceleration parameters for a single line of the TS table

    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: TS site class label (e.g., 'IV')

    Returns:
        pga: peak ground acceleration
        sas: short-period acceleration
        tc: spectral-acceleration-plateau corner period
        td: spectral-velocity-plateau corner period
    """

    loc_idx = PARAMETER_TABLE["Location"] == location_id
    apoe_idx = PARAMETER_TABLE["APoE (1/n)"] == apoe_n
    sc_idx = PARAMETER_TABLE["Site Class"] == site_class

    idx = loc_idx & apoe_idx & sc_idx
    pga, sas, tc, td = PARAMETER_TABLE[idx][SA_PARAMETER_NAMES].iloc[0]

    return pga, sas, tc, td

query_parameters