def unpack_single_value_from_df(name, df, allow_empty=True):
    """
    Utility method to unpack a single value from a DataFrame.
    If allow_empty is True (default), an empty DataFrame will be accepted and None will be returned.

    :param name: the name of the DataFrame, for validation purposes
    :param df:
    :param allow_empty:
    :return:
    """
    values = df.values.ravel()
    if len(values) == 1:
        return values[0]
    elif len(values) == 0 and allow_empty:
        return None
    else:
        raise ValueError(
            "DataFrame '%s' is supposed to contain a single value but does not: \n%s"
             % (name, df))
