SPI¶

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

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)}"
    )

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
    -------
    :

    """
    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)

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

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

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

    """
    warnings.warn(
        "Converting from Centred Parameters to Direct Parameters "
        "is not guaranteed to produce a unique result. "
        "Prefer constructing from Direct Parameters (xi, omega, alpha) "
        "directly when possible.",
        UserWarning,
        stacklevel=2,
    )
    dp = cp2dp(cp)
    return cls(dp.xi, dp.omega, dp.alpha)

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

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)}"
    )

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

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

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

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

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

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

    Returns
    -------
    :
        indicating the model is not fitted.

    """
    if self.cp is None and self.dp is None:
        return "MultiSkewNorm is not fitted."
    lines = []
    if self.data is not None:
        lines.append(f"Fitted from data. n = {len(self.data)}")
    else:
        lines.append("Fitted from direct parameters.")
    lines.append(str(self.dp))
    lines.append(str(self.cp))
    return "\n".join(lines)

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
        The input data as a pandas DataFrame or numpy array.
    x
        The x-values of the input data as a numpy array or pandas Series.
    y
        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):
            # Rename columns to "x"/"y" on a copy so we don't mutate the
            # caller's DataFrame.
            data = data.copy()
            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, extract parameters immediately, then discard the R object.
    # Storing rpy2 objects (RS4) beyond the function boundary creates a
    # persistent reference into R's heap that can outlive the session.
    m = sspyr.selm("x", "y", data)
    cp = sspyr.extract_cp(m)
    dp = sspyr.extract_dp(m)

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

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

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

    Returns
    -------
    :

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

@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
        The direct parameters to initialize the model.

    Returns
    -------
    :
        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:
            # xi/omega/alpha provided — create DirectParams and derive CP
            instance.dp = DirectParams(xi, omega, alpha)
            instance.cp = CentredParams.from_dp(instance.dp)
        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)

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

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

    Returns
    -------
    :
        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.dp is not None:
        sample = sspyr.sample_msn(
            xi=self.dp.xi, omega=self.dp.omega, alpha=self.dp.alpha, n=n
        )
    else:
        msg = "Model is not fitted. Call fit() or define_dp() first."
        raise ValueError(msg)

    self.sample_data = sample

    if return_sample:
        return sample
    return None

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
        The number of samples to generate, by default 1000.
    a
        Lower truncation bound for both dimensions, by default -1.
    b
        Upper truncation bound for both dimensions, by default 1.
    return_sample
        Whether to return the generated sample as an np.ndarray, by default False.

    Returns
    -------
    :
        The generated sample if `return_sample` is True, otherwise None.

    """
    if self.dp is not None:
        sample = sspyr.sample_mtsn(
            xi=self.dp.xi,
            omega=self.dp.omega,
            alpha=self.dp.alpha,
            n=n,
            a=a,
            b=b,
        )
    else:
        msg = "Model is not fitted. Call fit() or define_dp() first."
        raise ValueError(msg)

    # Store the sample data
    self.sample_data = sample

    if return_sample:
        return sample
    return None

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
        Color for the density plot, by default "blue".
    title
        Title for the plot, by default None.
    n
        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)

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

    Parameters
    ----------
    test
        The test data.

    Returns
    -------
    :
        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)

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
        The test data.

    Returns
    -------
    :
        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)