Soundscape Perception Indices (SPI) Reference

This section provides an overview of the tools for using the Soundscape Perception Indices (SPI) framework. It includes a brief description of each tool, as well as information on how to access and use them.

Soundscapy Psychoacoustic Indicator (SPI) calculation module.

This module provides functions and classes for calculating SPI, based on the R implementation. Requires optional dependencies.

MODULE	DESCRIPTION
`ks2d`
`msn`	Module for handling Multi-dimensional Skewed Normal (MSN) distributions.

CLASS	DESCRIPTION
`CentredParams`	Represents the centered parameters of a distribution.
`DirectParams`	Represents a set of direct parameters for a statistical model.
`MultiSkewNorm`	A class representing a multi-dimensional skewed normal distribution.

FUNCTION	DESCRIPTION
`cp2dp`	Convert centred parameters to direct parameters.
`dp2cp`	Convert direct parameters to centred parameters.
`spi_score`	Compute the Soundscape Perception Index (SPI).

CentredParams

CentredParams(mean, sigma, skew)

Represents the centered parameters of a distribution.

PARAMETER	DESCRIPTION
`mean`	The mean of the distribution. TYPE: `float`
`sigma`	The standard deviation of the distribution. TYPE: `float`
`skew`	The skewness of the distribution. TYPE: `float`

ATTRIBUTE	DESCRIPTION
`mean`	The mean of the distribution. TYPE: `float`
`sigma`	The standard deviation of the distribution. TYPE: `float`
`skew`	The skewness of the distribution. TYPE: `float`

METHOD	DESCRIPTION
`from_dp`	Converts DirectParams object to CentredParams object.

Initialize CentredParams instance.

Source code in soundscapy/spi/msn.py

def __init__(self, mean: np.ndarray, sigma: np.ndarray, skew: np.ndarray) -> None:
    """Initialize CentredParams instance."""
    self.mean = mean
    self.sigma = sigma
    self.skew = skew

repr

__repr__()

Return a string representation of the CentredParams object.

Source code in soundscapy/spi/msn.py

def __repr__(self) -> str:
    """Return a string representation of the CentredParams object."""
    return f"CentredParams(mean={self.mean}, sigma={self.sigma}, skew={self.skew})"

str

__str__()

Return a user-friendly string representation of the CentredParams object.

Source code in soundscapy/spi/msn.py

def __str__(self) -> str:
    """Return a user-friendly string representation of the CentredParams object."""
    return (
        f"Centred Parameters:"
        f"\nmean:  {self.mean.round(3)}"
        f"\nsigma: {self.sigma.round(3)}"
        f"\nskew:  {self.skew.round(3)}"
    )

from_dp `classmethod`

from_dp(dp)

Convert a DirectParams object to a CentredParams object.

PARAMETER	DESCRIPTION
`dp`	The DirectParams object to convert. TYPE: `DirectParams`

RETURNS	DESCRIPTION
`CentredParams`	A new CentredParams object with the converted parameters.

Source code in soundscapy/spi/msn.py

@classmethod
def from_dp(cls, dp: DirectParams) -> "CentredParams":
    """
    Convert a DirectParams object to a CentredParams object.

    Parameters
    ----------
    dp : DirectParams
        The DirectParams object to convert.

    Returns
    -------
    CentredParams
        A new CentredParams object with the converted parameters.

    """
    cp = dp2cp(dp)
    return cls(cp.mean, cp.sigma, cp.skew)

DirectParams

DirectParams(xi, omega, alpha)

Represents a set of direct parameters for a statistical model.

Direct parameters are the parameters that are directly used in the model. They are the parameters that are used to define the distribution of the data. In the case of a skew normal distribution, the direct parameters are the xi, omega, and alpha values.

PARAMETER	DESCRIPTION
`xi`	The location of the distribution in 2D space, represented as a 2x1 array with the x and y coordinates. TYPE: `ndarray`
`omega`	The covariance matrix of the distribution, represented as a 2x2 array. The covariance matrix represents the measure of the relationship between different variables. It provides information about how changes in one variable are associated with changes in other variables. TYPE: `ndarray`
`alpha`	The shape parameters for the x and y dimensions, controlling the shape (skewness) of the distribution. It is represented as a 2x1 array. TYPE: `ndarray`

Initialize DirectParams instance.

METHOD	DESCRIPTION
`__repr__`	Return a string representation of the DirectParams object.
`__str__`	Return a user-friendly string representation of the DirectParams object.
`from_cp`	Convert a CentredParams object to a DirectParams object.
`validate`	Validate the direct parameters.

Source code in soundscapy/spi/msn.py

def __init__(self, xi: np.ndarray, omega: np.ndarray, alpha: np.ndarray) -> None:
    """Initialize DirectParams instance."""
    self.xi = xi
    self.omega = omega
    self.alpha = alpha
    self.validate()

repr

__repr__()

Return a string representation of the DirectParams object.

Source code in soundscapy/spi/msn.py

def __repr__(self) -> str:
    """Return a string representation of the DirectParams object."""
    return f"DirectParams(xi={self.xi}, omega={self.omega}, alpha={self.alpha})"

str

__str__()

Return a user-friendly string representation of the DirectParams object.

Source code in soundscapy/spi/msn.py

def __str__(self) -> str:
    """Return a user-friendly string representation of the DirectParams object."""
    return (
        f"Direct Parameters:"
        f"\nxi:    {self.xi.round(3)}"
        f"\nomega: {self.omega.round(3)}"
        f"\nalpha: {self.alpha.round(3)}"
    )

from_cp `classmethod`

from_cp(cp)

Convert a CentredParams object to a DirectParams object.

PARAMETER	DESCRIPTION
`cp`	The CentredParams object to convert. TYPE: `CentredParams`

RETURNS	DESCRIPTION
`DirectParams`	A new DirectParams object with the converted parameters.

Source code in soundscapy/spi/msn.py

@classmethod
def from_cp(cls, cp: "CentredParams") -> "DirectParams":
    """
    Convert a CentredParams object to a DirectParams object.

    Parameters
    ----------
    cp : CentredParams
        The CentredParams object to convert.

    Returns
    -------
    DirectParams
        A new DirectParams object with the converted parameters.

    """
    warnings.warn(
        "Converting from Centred Parameters to Direct Parameters "
        "is not guaranteed.",
        UserWarning,
        stacklevel=2,
    )  # TODO(MitchellAcoustics): Add a more specific warning message  # noqa: TD003
    dp = cp2dp(cp)
    return cls(dp.xi, dp.omega, dp.alpha)

validate

validate()

Validate the direct parameters.

In a skew normal distribution, the covariance matrix, often denoted as Ω (Omega), represents the measure of the relationship between different variables. It provides information about how changes in one variable are associated with changes in other variables. The covariance matrix must be positive definite and symmetric.

RAISES	DESCRIPTION
`ValueError`	If the direct parameters are not valid.

RETURNS	DESCRIPTION
`None`

Source code in soundscapy/spi/msn.py

def validate(self) -> None:
    """
    Validate the direct parameters.

    In a skew normal distribution, the covariance matrix, often denoted as
    Ω (Omega), represents the measure of the relationship between different
    variables. It provides information about how changes in one variable are
    associated with changes in other variables. The covariance matrix must
    be positive definite and symmetric.

    Raises
    ------
    ValueError
        If the direct parameters are not valid.

    Returns
    -------
    None

    """
    if not self._omega_is_pos_def():
        msg = "Omega must be positive definite"
        raise ValueError(msg)
    if not self._omega_is_symmetric():
        msg = "Omega must be symmetric"
        raise ValueError(msg)

MultiSkewNorm

MultiSkewNorm()

A class representing a multi-dimensional skewed normal distribution.

ATTRIBUTE	DESCRIPTION
`selm_model`	The fitted SELM model.
`cp`	The centred parameters of the fitted model. TYPE: `CentredParams`
`dp`	The direct parameters of the fitted model. TYPE: `DirectParams`
`sample_data`	The generated sample data from the fitted model. TYPE: `ndarray \| None`
`data`	The input data used for fitting the model. TYPE: `DataFrame \| None`

METHOD	DESCRIPTION
`summary`	Prints a summary of the fitted model.
`fit`	Fits the model to the provided data.
`define_dp`	Defines the direct parameters of the model.
`sample`	Generates a sample from the fitted model.
`sspy_plot`	Plots the joint distribution of the generated sample.
`ks2ds`	Computes the two-sample Kolmogorov-Smirnov statistic.
`spi`	Computes the similarity percentage index.

Initialize the MultiSkewNorm object.

Source code in soundscapy/spi/msn.py

def __init__(self) -> None:
    """Initialize the MultiSkewNorm object."""
    self.selm_model = None
    self.cp = None
    self.dp = None
    self.sample_data = None
    self.data: pd.DataFrame | None = None

repr

__repr__()

Return a string representation of the MultiSkewNorm object.

Source code in soundscapy/spi/msn.py

def __repr__(self) -> str:
    """Return a string representation of the MultiSkewNorm object."""
    if self.cp is None and self.dp is None and self.selm_model is None:
        return "MultiSkewNorm() (unfitted)"
    return f"MultiSkewNorm(dp={self.dp})"

define_dp

define_dp(xi, omega, alpha)

Initiate a distribution from the direct parameters.

PARAMETER	DESCRIPTION
`xi`	The xi values of the direct parameters. TYPE: `ndarray`
`omega`	The omega values of the direct parameters. TYPE: `ndarray`
`alpha`	The alpha values of the direct parameters. TYPE: `ndarray`

RETURNS	DESCRIPTION
`self`

Source code in soundscapy/spi/msn.py

def define_dp(
    self, xi: np.ndarray, omega: np.ndarray, alpha: np.ndarray
) -> "MultiSkewNorm":
    """
    Initiate a distribution from the direct parameters.

    Parameters
    ----------
    xi : np.ndarray
        The xi values of the direct parameters.
    omega : np.ndarray
        The omega values of the direct parameters.
    alpha : np.ndarray
        The alpha values of the direct parameters.

    Returns
    -------
    self

    """
    self.dp = DirectParams(xi, omega, alpha)
    self.cp = CentredParams.from_dp(self.dp)
    return self

fit

fit(data=None, x=None, y=None)

Fit the multi-dimensional skewed normal model to the provided data.

PARAMETER	DESCRIPTION
`data`	The input data as a pandas DataFrame or numpy array. TYPE: `DataFrame or ndarray` DEFAULT: `None`
`x`	The x-values of the input data as a numpy array or pandas Series. TYPE: `ndarray or Series` DEFAULT: `None`
`y`	The y-values of the input data as a numpy array or pandas Series. TYPE: `ndarray or Series` DEFAULT: `None`

RAISES	DESCRIPTION
`ValueError`	If neither `data` nor both `x` and `y` are provided.

Source code in soundscapy/spi/msn.py

def fit(
    self,
    data: pd.DataFrame | np.ndarray | None = None,
    x: np.ndarray | pd.Series | None = None,
    y: np.ndarray | pd.Series | None = None,
) -> None:
    """
    Fit the multi-dimensional skewed normal model to the provided data.

    Parameters
    ----------
    data : pd.DataFrame or np.ndarray, optional
        The input data as a pandas DataFrame or numpy array.
    x : np.ndarray or pd.Series, optional
        The x-values of the input data as a numpy array or pandas Series.
    y : np.ndarray or pd.Series, optional
        The y-values of the input data as a numpy array or pandas Series.

    Raises
    ------
    ValueError
        If neither `data` nor both `x` and `y` are provided.

    """
    if data is None and (x is None or y is None):
        # Either data or x and y must be provided
        msg = "Either data or x and y must be provided"
        raise ValueError(msg)

    if data is not None:
        # If data is provided, convert it to a pandas DataFrame
        if isinstance(data, pd.DataFrame):
            # If data is already a DataFrame, no need to convert
            data.columns = ["x", "y"]

        elif isinstance(data, np.ndarray):
            # If data is a numpy array, convert it to a DataFrame
            if data.ndim == 2:  # noqa: PLR2004
                # If data is 2D, assume it's two variables
                data = pd.DataFrame(data, columns=["x", "y"])
            else:
                msg = "Data must be a 2D numpy array or DataFrame"
                raise ValueError(msg)
        else:
            # If data is neither a DataFrame nor a numpy array, raise an error
            msg = "Data must be a pandas DataFrame or 2D numpy array."
            raise ValueError(msg)

    elif x is not None and y is not None:
        # If x and y are provided, convert them to a pandas DataFrame
        data = pd.DataFrame({"x": x, "y": y})

    else:
        # This should never happen
        msg = "Either data or x and y must be provided"
        raise ValueError(msg)

    # Fit the model
    m = rsn.selm("x", "y", data)

    # Extract the parameters
    cp = rsn.extract_cp(m)
    dp = rsn.extract_dp(m)

    self.cp = CentredParams(*cp)
    self.dp = DirectParams(*dp)
    self.data = data
    self.selm_model = m

from_params `classmethod`

from_params(params=None, *, xi=None, omega=None, alpha=None, mean=None, sigma=None, skew=None)

Create a MultiSkewNorm instance from direct parameters.

PARAMETER	DESCRIPTION
`params`	The direct parameters to initialize the model. TYPE: `DirectParams` DEFAULT: `None`

RETURNS	DESCRIPTION
`MultiSkewNorm`	A new instance of MultiSkewNorm initialized with the provided parameters.

Source code in soundscapy/spi/msn.py

@classmethod
def from_params(
    cls,
    params: DirectParams | CentredParams | None = None,
    *,
    xi: np.ndarray | None = None,
    omega: np.ndarray | None = None,
    alpha: np.ndarray | None = None,
    mean: np.ndarray | None = None,
    sigma: np.ndarray | None = None,
    skew: np.ndarray | None = None,
) -> "MultiSkewNorm":
    """
    Create a MultiSkewNorm instance from direct parameters.

    Parameters
    ----------
    params : DirectParams
        The direct parameters to initialize the model.

    Returns
    -------
    MultiSkewNorm
        A new instance of MultiSkewNorm initialized with the provided parameters.

    """
    instance = cls()

    if params is None:
        if (xi is None or omega is None or alpha is None) and (
            mean is None or sigma is None or skew is None
        ):
            msg = "Either params object or xi, omega, and alpha must be provided."
            raise ValueError(msg)
        if xi is not None and omega is not None and alpha is not None:
            # If xi, omega, and alpha are provided, create DirectParams
            instance.dp = DirectParams(xi, omega, alpha)
        elif mean is not None and sigma is not None and skew is not None:
            # If mean, sigma, and skew are provided, create CentredParams
            cp = CentredParams(mean, sigma, skew)
            dp = DirectParams.from_cp(cp)
            instance.dp = dp
            instance.cp = cp
        return instance
    if isinstance(params, DirectParams):
        # If params is a DirectParams object, set it directly
        instance.dp = params
        instance.cp = CentredParams.from_dp(params)
        return instance
    if isinstance(params, CentredParams):
        # If params is a CentredParams object, convert it to DirectParams
        instance.cp = params
        dp = DirectParams.from_cp(params)
        instance.dp = dp
        return instance
    # If params is neither DirectParams nor CentredParams, raise an error
    msg = (
        "Either params or xi, omega, and alpha must be provided."
        "Or mean, sigma, and skew must be provided."
    )
    raise ValueError(msg)

ks2d2s

ks2d2s(test)

Compute the two-sample, two-dimensional Kolmogorov-Smirnov statistic.

PARAMETER	DESCRIPTION
`test`	The test data. TYPE: `DataFrame or ndarray`

RETURNS	DESCRIPTION
`tuple`	The KS2D statistic and p-value.

Source code in soundscapy/spi/msn.py

def ks2d2s(self, test: pd.DataFrame | np.ndarray) -> tuple[float, float]:
    """
    Compute the two-sample, two-dimensional Kolmogorov-Smirnov statistic.

    Parameters
    ----------
    test : pd.DataFrame or np.ndarray
        The test data.

    Returns
    -------
    tuple
        The KS2D statistic and p-value.

    """
    # Ensure sample_data exists, generate if needed and possible
    if self.sample_data is None:
        logger.info("Sample data not found, generating default sample (n=1000).")
        self.sample(n=1000, return_sample=False)  # Generate sample if missing
        if self.sample_data is None:  # Check again in case sample failed
            msg = (
                "Could not generate sample data. "
                "Ensure model is defined (fit or define_dp)."
            )
            raise ValueError(msg)

    # Perform the 2-sample KS test using ks2d2s
    # Note: ks2d2s expects data1, data2
    return ks2d(self.sample_data, test)

sample

sample(n=1000, *, return_sample=False)

Generate a sample from the fitted model.

PARAMETER	DESCRIPTION
`n`	The number of samples to generate, by default 1000. TYPE: `int` DEFAULT: `1000`
`return_sample`	Whether to return the generated sample as an np.ndarray, by default False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`None or ndarray`	The generated sample if `return_sample` is True, otherwise None.

RAISES	DESCRIPTION
`ValueError`	If the model is not fitted (i.e., `selm_model` is None) and direct parameters (`dp`) are also not defined.

Source code in soundscapy/spi/msn.py

def sample(
    self, n: int = 1000, *, return_sample: bool = False
) -> None | np.ndarray:
    """
    Generate a sample from the fitted model.

    Parameters
    ----------
    n : int, optional
        The number of samples to generate, by default 1000.
    return_sample : bool, optional
        Whether to return the generated sample as an np.ndarray, by default False.

    Returns
    -------
    None or np.ndarray
        The generated sample if `return_sample` is True, otherwise None.

    Raises
    ------
    ValueError
        If the model is not fitted (i.e., `selm_model` is None) and direct
        parameters (`dp`) are also not defined.

    """
    if self.selm_model is not None:
        sample = rsn.sample_msn(selm_model=self.selm_model, n=n)
    elif self.dp is not None:
        sample = rsn.sample_msn(
            xi=self.dp.xi, omega=self.dp.omega, alpha=self.dp.alpha, n=n
        )
    else:
        msg = "Either selm_model or xi, omega, and alpha must be provided."
        raise ValueError(msg)

    self.sample_data = sample

    if return_sample:
        return sample
    return None

sample_mtsn

sample_mtsn(n=1000, a=-1, b=1, *, return_sample=False)

Generate a sample from the multi-dimensional truncated skew-normal distribution.

Uses rejection sampling to ensure that the samples are within the bounds [a, b] for both dimensions.

PARAMETER	DESCRIPTION
`n`	The number of samples to generate, by default 1000. TYPE: `int` DEFAULT: `1000`
`a`	Lower truncation bound for both dimensions, by default -1. TYPE: `float` DEFAULT: `-1`
`b`	Upper truncation bound for both dimensions, by default 1. TYPE: `float` DEFAULT: `1`
`return_sample`	Whether to return the generated sample as an np.ndarray, by default False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`None or ndarray`	The generated sample if `return_sample` is True, otherwise None.

Source code in soundscapy/spi/msn.py

def sample_mtsn(
    self, n: int = 1000, a: float = -1, b: float = 1, *, return_sample: bool = False
) -> None | np.ndarray:
    """
    Generate a sample from the multi-dimensional truncated skew-normal distribution.

    Uses rejection sampling to ensure that the samples are within the bounds [a, b]
    for both dimensions.

    Parameters
    ----------
    n : int, optional
        The number of samples to generate, by default 1000.
    a : float, optional
        Lower truncation bound for both dimensions, by default -1.
    b : float, optional
        Upper truncation bound for both dimensions, by default 1.
    return_sample : bool, optional
        Whether to return the generated sample as an np.ndarray, by default False.

    Returns
    -------
    None or np.ndarray
        The generated sample if `return_sample` is True, otherwise None.

    """
    if self.selm_model is not None:
        sample = rsn.sample_mtsn(
            selm_model=self.selm_model,
            n=n,
            a=a,
            b=b,
        )
    elif self.dp is not None:
        sample = rsn.sample_mtsn(
            xi=self.dp.xi,
            omega=self.dp.omega,
            alpha=self.dp.alpha,
            n=n,
            a=a,
            b=b,
        )
    else:
        msg = "Either selm_model or xi, omega, and alpha must be provided."
        raise ValueError(msg)

    # Store the sample data
    self.sample_data = sample

    if return_sample:
        return sample
    return None

spi_score

spi_score(test)

Compute the Soundscape Perception Index (SPI).

Calculates the SPI for the test data against the target distribution represented by this MultiSkewNorm instance.

PARAMETER	DESCRIPTION
`test`	The test data. TYPE: `DataFrame or ndarray`

RETURNS	DESCRIPTION
`int`	The Soundscape Perception Index (SPI), ranging from 0 to 100.

Source code in soundscapy/spi/msn.py

def spi_score(self, test: pd.DataFrame | np.ndarray) -> int:
    """
    Compute the Soundscape Perception Index (SPI).

    Calculates the SPI for the test data against the target distribution
    represented by this MultiSkewNorm instance.

    Parameters
    ----------
    test : pd.DataFrame or np.ndarray
        The test data.

    Returns
    -------
    int
        The Soundscape Perception Index (SPI), ranging from 0 to 100.

    """
    # Ensure sample_data exists, generate if needed and possible
    if self.sample_data is None:
        logger.info("Sample data not found, generating default sample (n=1000).")
        self.sample(n=1000, return_sample=False)  # Generate sample if missing
        if self.sample_data is None:  # Check again in case sample failed
            msg = (
                "Could not generate sample data. "
                "Ensure model is defined (fit or define_dp)."
            )
            raise ValueError(msg)
    return spi_score(self.sample_data, test)

sspy_plot

sspy_plot(color='blue', title=None, n=1000)

Plot the joint distribution of the generated sample using soundscapy.

PARAMETER	DESCRIPTION
`color`	Color for the density plot, by default "blue". TYPE: `str` DEFAULT: `'blue'`
`title`	Title for the plot, by default None. TYPE: `str` DEFAULT: `None`
`n`	Number of samples to generate if `sample_data` is None, by default 1000. TYPE: `int` DEFAULT: `1000`

Source code in soundscapy/spi/msn.py

def sspy_plot(
    self, color: str = "blue", title: str | None = None, n: int = 1000
) -> None:
    """
    Plot the joint distribution of the generated sample using soundscapy.

    Parameters
    ----------
    color : str, optional
        Color for the density plot, by default "blue".
    title : str, optional
        Title for the plot, by default None.
    n : int, optional
        Number of samples to generate if `sample_data` is None, by default 1000.

    """
    if self.sample_data is None:
        self.sample(n=n)

    data = pd.DataFrame(self.sample_data, columns=["ISOPleasant", "ISOEventful"])
    plot_title = title if title is not None else "Soundscapy Density Plot"
    scatter(data, color=color, title=plot_title)

summary

summary()

Provide a summary of the fitted MultiSkewNorm model.

RETURNS	DESCRIPTION
`str or None`	A string summarizing the model parameters and data, or a message indicating the model is not fitted. Returns None if fitted but summary logic is not fully implemented yet.

Source code in soundscapy/spi/msn.py

def summary(self) -> str | None:
    """
    Provide a summary of the fitted MultiSkewNorm model.

    Returns
    -------
    str or None
        A string summarizing the model parameters and data, or a message
        indicating the model is not fitted. Returns None if fitted but
        summary logic is not fully implemented yet.

    """
    if self.cp is None and self.dp is None and self.selm_model is None:
        return "MultiSkewNorm is not fitted."
    if self.data is not None:
        print(f"Fitted from data. n = {len(self.data)}")  # noqa: T201
    else:
        print("Fitted from direct parameters.")  # noqa: T201
    print(self.dp)  # noqa: T201
    print("\n")  # noqa: T201
    print(self.cp)  # noqa: RET503, T201

cp2dp

cp2dp(cp, family='SN')

Convert centred parameters to direct parameters.

PARAMETER	DESCRIPTION
`cp`	The centred parameters object. TYPE: `CentredParams`
`family`	The distribution family, by default "SN" (Skew Normal). TYPE: `str` DEFAULT: `'SN'`

RETURNS	DESCRIPTION
`DirectParams`	The corresponding direct parameters object.

Source code in soundscapy/spi/msn.py

def cp2dp(
    cp: CentredParams, family: Literal["SN", "ESN", "ST", "SC"] = "SN"
) -> DirectParams:
    """
    Convert centred parameters to direct parameters.

    Parameters
    ----------
    cp : CentredParams
        The centred parameters object.
    family : str, optional
        The distribution family, by default "SN" (Skew Normal).

    Returns
    -------
    DirectParams
        The corresponding direct parameters object.

    """
    dp_r = rsn.cp2dp(cp.mean, cp.sigma, cp.skew, family=family)

    return DirectParams(*dp_r)

dp2cp

dp2cp(dp, family='SN')

Convert direct parameters to centred parameters.

PARAMETER	DESCRIPTION
`dp`	The direct parameters object. TYPE: `DirectParams`
`family`	The distribution family, by default "SN" (Skew Normal). TYPE: `str` DEFAULT: `'SN'`

RETURNS	DESCRIPTION
`CentredParams`	The corresponding centred parameters object.

Source code in soundscapy/spi/msn.py

def dp2cp(
    dp: DirectParams, family: Literal["SN", "ESN", "ST", "SC"] = "SN"
) -> CentredParams:
    """
    Convert direct parameters to centred parameters.

    Parameters
    ----------
    dp : DirectParams
        The direct parameters object.
    family : str, optional
        The distribution family, by default "SN" (Skew Normal).

    Returns
    -------
    CentredParams
        The corresponding centred parameters object.

    """
    cp_r = rsn.dp2cp(dp.xi, dp.omega, dp.alpha, family=family)

    return CentredParams(*cp_r)

spi_score

spi_score(target, test)

Compute the Soundscape Perception Index (SPI).

Calculates the SPI for the test data against the target distribution represented by the sample data.

PARAMETER	DESCRIPTION
`target`	The sample data representing the target distribution. TYPE: `ndarray`
`test`	The test data. TYPE: `DataFrame or ndarray`

RETURNS	DESCRIPTION
`int`	The Soundscape Perception Index (SPI), ranging from 0 to 100.

Source code in soundscapy/spi/msn.py

def spi_score(
    target: pd.DataFrame | np.ndarray, test: pd.DataFrame | np.ndarray
) -> int:
    """
    Compute the Soundscape Perception Index (SPI).

    Calculates the SPI for the test data against the target distribution
    represented by the sample data.

    Parameters
    ----------
    target : np.ndarray
        The sample data representing the target distribution.
    test : pd.DataFrame or np.ndarray
        The test data.

    Returns
    -------
    int
        The Soundscape Perception Index (SPI), ranging from 0 to 100.

    """
    return int((1 - ks2d(target, test)[0]) * 100)

options: show_root_heading: false show_root_toc_entry: false show_submodules: true members: - msn

Soundscape Perception Indices (SPI) Reference

CentredParams

__repr__

__str__

from_dp classmethod

DirectParams

__repr__

__str__

from_cp classmethod

validate

MultiSkewNorm

__repr__

define_dp

fit

from_params classmethod

ks2d2s

sample

sample_mtsn

spi_score

sspy_plot

summary

cp2dp

dp2cp

spi_score

repr

str

from_dp `classmethod`

repr

str

from_cp `classmethod`

repr

from_params `classmethod`