def analyze_significance(results: RegressionResults, 
                         alpha: float = 0.05) -> Dict[str, bool]:
    """Flag which scaling exponents are statistically significant.

    Parameters
    ----------
    results : RegressionResults
        A fitted regression [-].
    alpha : float, optional
        Significance level; a coefficient with ``p < alpha`` is significant
        [-].

    Returns
    -------
    dict of str to bool
        Parameter name to whether its exponent is significant; a parameter
        absent from the fit is ``False`` [-].

    Defaults
    --------
    ``alpha = 0.05`` is the conventional literature value, no more.

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    A p-value from a small sample with correlated regressors overstates
    significance; see :func:`get_correlation_matrix` before trusting it.
    """
    significance = {}
    for param in results.eng_params:
        param_name = f'ln_{param}'
        if param_name in results.pvalues:
            pval = results.pvalues[param_name]
            significance[param] = pval < alpha
        else:
            significance[param] = False

    return significance

def confinement_time_histogram(df: pd.DataFrame,
                               eng_params: Optional[List[str]] = None,
                               m: Optional[int] = None,
                               n: Optional[int] = None,
                               figsize: Optional[Tuple[float, float]] = None,
                               bins: Union[int, str] = 30,
                               alpha: float = 0.7,
                               edgecolor: str = 'black',
                               **kwargs):
    """Plot histograms of the scaling parameters in an ``m x n`` grid.

    Parameters
    ----------
    df : pd.DataFrame
        The scaling table [-].
    eng_params : list of str or None, optional
        Columns to plot; ``None`` for the renderer's default set [-].
    m : int or None, optional
        Grid rows [-].
    n : int or None, optional
        Grid columns [-].
    figsize : tuple of (float, float) or None, optional
        Figure size in inches [-].
    bins : int or str, optional
        Histogram bins, as Matplotlib takes them [-].
    alpha : float, optional
        Bar opacity [-].
    edgecolor : str, optional
        Bar edge colour [-].

    Returns
    -------
    matplotlib.figure.Figure
        The figure, as :func:`vaft.plot.history.confinement_time_histogram`
        returns it [-].

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    Rendering lives in :func:`vaft.plot.history.confinement_time_histogram`
    (issue #63); this is a compatibility shim that keeps the old call site
    and pulls Matplotlib in on call.  Its removal is tracked in #263.
    """
    from vaft.plot.history import confinement_time_histogram as _render

    return _render(df, eng_params=eng_params, m=m, n=n, figsize=figsize,
                   bins=bins, alpha=alpha, edgecolor=edgecolor, **kwargs)

def filter_dataframe(df: pd.DataFrame) -> pd.DataFrame:
    """Drop shots with unrealistic loss power and rectify the toroidal field sign.

    Parameters
    ----------
    df : pd.DataFrame
        The scaling table; ``Ploss_MW`` and ``Bt_T`` are acted on when present
        [-].

    Returns
    -------
    pd.DataFrame
        The filtered table [-].

    Processing steps
    ----------------
    1. Keep rows with ``Ploss_MW <= 3``.
    2. Replace ``Bt_T`` by its absolute value.

    Defaults
    --------
    The 3 MW ceiling is a hard-coded empirical cut from the study; its
    derivation is not recorded.  It is not a parameter.

    Convention
    ----------
    ``Bt_T`` is made positive regardless of the field direction actually run,
    so the fit sees magnitude only.  Any sign convention on the field is
    discarded here.

    Applicability
    -------------
    VEST-specific.  The ceiling and the column names are the VEST study's.

    Limitations
    -----------
    Assigns into the frame it was given (``df["Bt_T"] = ...``), so the
    caller's table may be modified and pandas may warn about a copy.
    """
    if 'Ploss_MW' in df.columns:
        df = df[df['Ploss_MW'] <= 3]

    # Ensure Bt_T is always positive
    if 'Bt_T' in df.columns:
        df['Bt_T'] = df['Bt_T'].abs()
    return df

def get_correlation_matrix(log_df: pd.DataFrame, 
                          eng_params: List[str],
                          target_param: str = 'tauE_s') -> pd.DataFrame:
    """Pearson correlation matrix of the log-transformed regressors and target.

    Parameters
    ----------
    log_df : pd.DataFrame
        Output of :func:`log_transform` [-].
    eng_params : list of str
        Column names of the engineering parameters [-].
    target_param : str, optional
        Column name of the confinement time [-].

    Returns
    -------
    pd.DataFrame
        The correlation matrix over the available ``ln_`` columns; empty when
        fewer than two exist [-].

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    Pairwise-complete, as ``DataFrame.corr`` is; rows are not dropped
    consistently across pairs.
    """
    cols = [f'ln_{p}' for p in eng_params] + [f'ln_{target_param}']
    available_cols = [c for c in cols if c in log_df.columns]

    if len(available_cols) < 2:
        logger.warning("Not enough columns for correlation matrix")
        return pd.DataFrame()

    corr_df = log_df[available_cols].corr()
    return corr_df

def get_individual_correlations(log_df: pd.DataFrame,
                               eng_params: List[str],
                               target_param: str = 'tauE_s') -> Dict[str, float]:
    """Pearson correlation of each log regressor with the log target.

    Parameters
    ----------
    log_df : pd.DataFrame
        Output of :func:`log_transform` [-].
    eng_params : list of str
        Column names of the engineering parameters [-].
    target_param : str, optional
        Column name of the confinement time [-].

    Returns
    -------
    dict of str to float
        Parameter name to its correlation with the target; NaN when the
        column is missing or fewer than two complete rows exist [-].

    Applicability
    -------------
    Machine-independent.
    """
    correlations = {}
    target_col = f'ln_{target_param}'

    if target_col not in log_df.columns:
        logger.warning(f"Target column {target_col} not found")
        return correlations

    for param in eng_params:
        param_col = f'ln_{param}'
        if param_col in log_df.columns:
            # Remove NaN values for correlation calculation
            valid_mask = ~(log_df[param_col].isna() | log_df[target_col].isna())
            if valid_mask.sum() > 1:
                corr, _ = pearsonr(log_df[param_col][valid_mask], 
                                  log_df[target_col][valid_mask])
                correlations[param] = corr
            else:
                correlations[param] = np.nan
        else:
            correlations[param] = np.nan

    return correlations

def get_residuals(results: RegressionResults) -> pd.Series:
    """Residuals of the log-space fit.

    Parameters
    ----------
    results : RegressionResults
        A fitted regression [-].

    Returns
    -------
    pd.Series
        ``ln(actual) - ln(fitted)`` per row used in the fit [-].

    Applicability
    -------------
    Machine-independent.
    """
    return results.residuals

def load_data_from_excel(filepath: str) -> pd.DataFrame:
    """Load a confinement-scaling table from an Excel file.

    Parameters
    ----------
    filepath : str
        Path to the ``.xlsx`` file; one row per shot, columns as the study
        named them [-].

    Returns
    -------
    pd.DataFrame
        The table as read, untouched [-].

    Raises
    ------
    Exception
        Whatever ``pandas.read_excel`` raises, after logging it.

    Applicability
    -------------
    Machine-independent.  The tables under
    ``workflow/automatic_pipeline_3_data_summary/`` are VEST, but nothing here
    depends on that.

    Provenance
    ----------
    .. [1] The study notebook [NB]_.
    """
    try:
        df = pd.read_excel(filepath)
        logger.info(f"Loaded {len(df)} rows from {filepath}")
        return df
    except Exception as e:
        logger.error(f"Error loading Excel file: {e}")
        raise

def log_transform(df: pd.DataFrame, 
                  eng_params: List[str], 
                  target_param: str = 'tauE_s') -> pd.DataFrame:
    """Take natural logarithms of the engineering parameters and the target.

    Parameters
    ----------
    df : pd.DataFrame
        The scaling table [-].
    eng_params : list of str
        Column names of the engineering parameters [-].
    target_param : str, optional
        Column name of the confinement time [-].

    Returns
    -------
    pd.DataFrame
        Columns ``ln_<name>`` for each parameter and the target, same index as
        ``df``; a missing column becomes all-NaN with a warning [-].

    Convention
    ----------
    Natural logarithm, so the fitted coefficients are the exponents of a
    power law directly.  A value that is not strictly positive has no
    logarithm and becomes NaN, to be dropped by :func:`perform_ols_regression`.

    Applicability
    -------------
    Machine-independent.
    """
    log_df = pd.DataFrame(index=df.index)

    # Log transform engineering parameters
    for param in eng_params:
        if param in df.columns:
            # Handle NaN and non-positive values
            valid_mask = (df[param] > 0) & ~np.isnan(df[param])
            log_df[f'ln_{param}'] = np.where(valid_mask, np.log(df[param]), np.nan)
        else:
            logger.warning(f"Parameter {param} not found in DataFrame")
            log_df[f'ln_{param}'] = np.nan

    # Log transform target parameter
    if target_param in df.columns:
        valid_mask = (df[target_param] > 0) & ~np.isnan(df[target_param])
        log_df[f'ln_{target_param}'] = np.where(valid_mask, np.log(df[target_param]), np.nan)
    else:
        logger.warning(f"Target parameter {target_param} not found in DataFrame")
        log_df[f'ln_{target_param}'] = np.nan

    return log_df