meridian.analysis.analyzer.Analyzer

Executa cálculos para analisar os dados brutos depois de ajustar o modelo.

meridian.analysis.analyzer.Analyzer(
    meridian: meridian.model.model.Meridian
)

Classes filhas

class PerformanceData

Métodos

adstock_decay

Ver código-fonte

adstock_decay(
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL
) -> pd.DataFrame

Calcula o decaimento de Adstock para canais de mídia e de alcance e frequência.

Args
confidence_level Nível de confiança para intervalos de confiança a priori e a posteriori, representado como um valor entre zero e um.

Retorna
DataFrame do Pandas contendo o canal, time_units, distribuição, ci_hi, ci_lo e mean para a função de Adstock.

baseline_summary_metrics

Ver código-fonte

baseline_summary_metrics(
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> xr.Dataset

Retorna as métricas de resumo do valor de referência.

Args
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o resultado esperado será somado em todas as regiões.
aggregate_times Booleano. Se for True, o resultado esperado será somado em todos os períodos.
confidence_level Nível de confiança para intervalos de confiança das métricas de resumo de mídia, representado como um valor entre zero e um.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Um xr.Dataset com coordenadas: metric (mean, median, ci_low, ci_high), distribution (a priori, a posteriori) e contém as seguintes variáveis de dados: baseline_outcome, pct_of_contribution.

cpik

Ver código-fonte

cpik(
    use_posterior: bool = True,
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> tf.Tensor

Calcula o custo por distribuição incremental de KPIs para cada canal.

O numerador do CPIK é o gasto total no canal. O denominador do CPIK é a mudança no KPI esperado quando o gasto de um canal é definido como zero, mantendo o gasto de todos os outros canais sem alterações.

Se new_data=None, esse método calcula o CPIK condicionalmente com base nos valores das variáveis de mídia paga com que o objeto do Meridian foi inicializado. O usuário também pode substituir esses dados históricos pelo argumento new_data, desde que as dimensões dos novos tensores sejam correspondentes. Por exemplo,

new_data = DataTensors(media=new_media, frequency=new_frequency)

Se selected_geos ou selected_times forem especificados, o numerador do CPIK será o gasto total durante as regiões e períodos selecionados. Uma exceção será gerada se o gasto dos InputData usados para treinar o modelo não tiver dimensões geográficas e de tempo. Se os argumentos new_data.media_spend e new_data.rf_spend forem usados com dimensões diferentes do gasto de InputData, uma exceção será gerada, já que é provável que isso seja um erro do usuário.

O CPIK é simplesmente 1/ROI, em que o ROI é obtido de uma chamada para o método roi com use_kpi=True.

Args
use_posterior Booleano. Se True, a distribuição a posteriori será calculada. Caso contrário, será a distribuição a priori.
new_data Opcional. DataTensors que contêm os dados de media, media_spend, reach, frequency, rf_spend e revenue_per_kpi. Se forem fornecidos, o CPIK será calculado com base nos valores dos tensores transmitidos em new_data e os valores originais de todos os tensores restantes. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de meridian.input_data. Se None, o CPIK será calculado usando os valores originais de todos os tensores.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o KPI esperado será somado em todas as regiões.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Tensor de valores de CPIK com dimensões (n_chains, n_draws, n_geos, (n_media_channels + n_rf_channels)). A dimensão n_geos será descartada se for aggregate_geos=True.

expected_outcome

Ver código-fonte

expected_outcome(
    use_posterior: bool = True,
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    inverse_transform_outcome: bool = True,
    use_kpi: bool = False,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> tf.Tensor

Calcula o resultado esperado a priori ou a posteriori.

Isso calcula E(Outcome|Media, RF, Organic media, Organic RF, Non-media treatments, Controls) para cada extração de parâmetro a posteriori (ou a priori), em que Outcome se refere a revenue se use_kpi=False, ou kpi se use_kpi=True. Quando revenue_per_kpi não está definido, use_kpi não pode ser False.

Se new_data=None, esse método calcula o resultado esperado condicionalmente aos valores das variáveis independentes com que o objeto do Meridian foi inicializado. O usuário também pode substituir esses dados históricos pelo argumento new_data, desde que as dimensões dos novos tensores sejam correspondentes. Por exemplo,

new_data=DataTensors(reach=new_reach, frequency=new_frequency)

Em princípio, o resultado esperado pode ser calculado com outras dimensões de tempo (para previsões futuras, por exemplo). No entanto, isso não é permitido com esse método devido às complexidades adicionais que ele introduz:

  1. Os dados de preço correspondentes (receita por KPI) também serão necessários.
  2. Se o modelo tiver parâmetros de efeito semanal, será necessário usar algum método para estimar ou prever esses efeitos em períodos fora da janela de dados de treinamento.

Args
use_posterior Booleano. Se True, a distribuição esperada de resultados a posteriori será calculada. Caso contrário, será a distribuição a priori.
new_data Um contêiner DataTensors opcional com novos tensores opcionais: media, reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments, controls. Se for None, o resultado esperado será calculado condicionalmente aos valores originais dos tensores de dados com que o objeto do Meridian foi inicializado. Se o argumento new_data for usado, o resultado esperado será calculado condicionalmente aos valores dos tensores transmitidos em new_data e aos valores originais dos tensores restantes não definidos. Por exemplo, expected_outcome(new_data=DataTensors(reach=new_reach, frequency=new_frequency)) calcula o resultado esperado condicionalmente aos tensores originais media, organic_media, organic_reach, organic_frequency, non_media_treatments e controls e aos novos valores fornecidos para os tensores reach e frequency. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de input_data.
selected_geos Lista opcional que contém um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de datas a serem incluídas. Os valores aceitos aqui precisam corresponder às coordenadas de dimensão de tempo de InputData.time. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o resultado esperado será somado em todas as regiões.
aggregate_times Booleano. Se True, o resultado esperado será somado em todos os períodos.
inverse_transform_outcome Booleano. Se True, vai retornar o resultado esperado no KPI ou na receita original (dependendo do que é transmitido para use_kpi), conforme foi transmitido para InputData. Se for "False", vai retornar o resultado após a transformação feita por KpiTransformer, refletindo como ele é representado no modelo.
use_kpi Booleano. Se use_kpi = True, o KPI esperado será calculado. Caso contrário, a receita esperada (kpi * revenue_per_kpi) será calculada. É obrigatório que use_kpi = True se revenue_per_kpi não estiver definido ou se inverse_transform_outcome = False.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Tensor do resultado esperado (KPI ou receita, dependendo do argumento use_kpi) com dimensões (n_chains, n_draws, n_geos, n_times). As dimensões n_geos e n_times serão descartadas se aggregate_geos=True ou aggregate_time=True, respectivamente.

Gera
NotFittedModelError se sample_posterior() (para use_posterior=True) ou sample_prior() (para use_posterior=False) não tiver sido chamado antes de chamar esse método.

expected_vs_actual_data

Ver código-fonte

expected_vs_actual_data(
    aggregate_geos: bool = False,
    aggregate_times: bool = False,
    split_by_holdout_id: bool = False,
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL
) -> xr.Dataset

Calcula os dados do resultado esperado x real ao longo do tempo.

Args
aggregate_geos Booleano. Se True, os valores esperado, real e de referência serão somados em todas as regiões.
aggregate_times Booleano. Se True, os valores esperado, real e de referência serão somados em todos os períodos.
split_by_holdout_id Booleano. Se True e holdout_id existirem, os dados serão divididos em subseções 'Train', 'Test' e 'All Data'.
confidence_level Nível de confiança para intervalos confiáveis de resultado esperado, representado como um valor entre zero e um. Padrão: 0.9.

Retorna
Um conjunto de dados com as métricas dos resultados esperado, real e do valor de referência.

filter_and_aggregate_geos_and_times

Ver código-fonte

filter_and_aggregate_geos_and_times(
    tensor: tf.Tensor,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | Sequence[bool] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    flexible_time_dim: bool = False,
    has_media_dim: bool = True
) -> tf.Tensor

Filtra e/ou agrega as dimensões de região geográfica e tempo de um tensor.

Args
tensor Tensor com dimensões [..., n_geos, n_times] ou [..., n_geos, n_times, n_channels], em que n_channels é o número de canais de mídia, canais de RF (alcance e frequência), todos os canais pagos (mídia e RF) ou todos os canais (mídia, RF, não mídia, mídia orgânica, RF orgânicos).
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas. As regiões selecionadas precisam corresponder às que estão em InputData.geo.
selected_times Lista opcional de horários a serem incluídos. Pode ser uma lista de strings que contém um subconjunto de coordenadas da dimensão de tempo de InputData.time ou uma lista booleana com comprimento igual à dimensão de tempo do tensor. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o tensor será somado em todas as regiões geográficas.
aggregate_times Booleano. Se True, o tensor será somado em todos os períodos.
flexible_time_dim Booleano. Se True, a dimensão de tempo do tensor não será necessária para corresponder ao número de períodos em InputData.time. Nesse caso, se você usar selected_times, ela precisará ser uma lista booleana com comprimento igual à dimensão de tempo do tensor.
has_media_dim Booleano. Só será usado se flexible_time_dim=True. Caso contrário, essa suposição será feita com base nas dimensões do tensor. Se True, será considerado que o tensor tem uma dimensão de mídia após a dimensão de tempo. Se False, a última dimensão do tensor será considerada a dimensão de tempo.

Retorna
Um tensor com dimensões de região geográfica e tempo filtradas e/ou agregadas.

get_aggregated_impressions

Ver código-fonte

get_aggregated_impressions(
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    optimal_frequency: (Sequence[float] | None) = None,
    include_non_paid_channels: bool = True
) -> tf.Tensor

Calcula os valores de impressões agregadas nos dados de todos os canais.

Args
new_data Um objeto DataTensors opcional que contém os novos tensores media, reach, frequency, organic_media, organic_reach, organic_frequency e non_media_treatments. Se o argumento new_data for usado, as impressões agregadas serão calculadas com base nos valores dos tensores transmitidos no argumento new_data e os valores originais de todos os tensores restantes. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de meridian.input_data. Se None, os tensores atuais do objeto Meridian serão usados.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o resultado esperado será somado em todas as regiões.
aggregate_times Booleano. Se True, o resultado esperado será somado em todos os períodos.
optimal_frequency Uma lista opcional com a dimensão n_rf_channels, que contém a frequência ideal por canal, que maximiza o ROI médio a posteriori. O valor padrão é None, e a frequência histórica é usada para o cálculo das métricas.
include_non_paid_channels Booleano. Se for True, mídia orgânica, RF orgânicos e canais que não são de mídia serão incluídos na agregação.

Retorna
Um tensor com o formato (n_selected_geos, n_selected_times, n_channels) (ou (n_channels,), se as regiões geográficas e os horários forem agregados) com valores de impressão agregados por canal.

get_historical_spend

Ver código-fonte

get_historical_spend(
    selected_times: (Sequence[str] | None),
    include_media: bool = True,
    include_rf: bool = True
) -> xr.DataArray

Recebe o gasto histórico agregado com base no período.

Args
selected_times O período para obter os gastos históricos. Se for "None", os gastos históricos serão agregados em todos os pontos de tempo.
include_media Se os gastos com canais de mídia paga que não têm dados de alcance e frequência serão incluídos.
include_rf Se os gastos com canais de mídia paga vão incluir dados de alcance e frequência.

Retorna
Um xr.DataArray com a coordenada channel e que contém a variável de dados spend.

Gera
ValueError Um ValueError quando include_media e include_rf são "False".

get_rhat

Ver código-fonte

get_rhat() -> Mapping[str, tf.Tensor]

Calcula os valores de R-hat para cada parâmetro no modelo.

Retorna
Um dicionário de valores de R-hat em que cada parâmetro é uma chave e os valores são R-hats correspondentes ao parâmetro.

Gera
NotFittedModelError Se "self.sample_posterior()" não for chamado antes de chamar esse método.

hill_curves

Ver código-fonte

hill_curves(
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL,
    n_bins: int = 25
) -> pd.DataFrame

Estima as tabelas de curva de Hill usadas para representar as curvas de cada canal.

Args
confidence_level Nível de confiança para intervalos de confiança a priori e a posteriori, representado como um valor entre zero e um. O padrão é 0.9.
n_bins Número de agrupamentos de largura igual a serem incluídos no histograma para a plotagem. O padrão é 25.

Retorna
Curvas de Hill pd.DataFrame com colunas:

  • channel: nome do canal media ou rf.
  • media_units: unidades de mídia (para canais media) ou frequência média (para canais rf).
  • distribution: indicação de extração posterior ou prior.
  • ci_hi: limite superior do intervalo de confiança do valor da função de Hill.
  • ci_lo: limite inferior do intervalo de confiança do valor da função de Hill.
  • mean: média por ponto do valor da função de Hill por extração.
  • channel_type: indicação de um canal media ou rf.
  • scaled_count_histogram: contagem ajustada de unidades de mídia ou de frequências médias no agrupamento.
  • count_histogram: valor da contagem de unidades de mídia ou de frequências médias no agrupamento.
  • start_interval_histogram: unidade de mídia ou ponto de partida da frequência média de um agrupamento de histogramas.
  • end_interval_histogram: unidade de mídia ou ponto final da frequência média de um agrupamento de histogramas.

incremental_outcome

Ver código-fonte

incremental_outcome(
    use_posterior: bool = True,
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    non_media_baseline_values: (Sequence[float | str] | None) = None,
    scaling_factor0: float = 0.0,
    scaling_factor1: float = 1.0,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | Sequence[bool] | None) = None,
    media_selected_times: (Sequence[str] | Sequence[bool] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    inverse_transform_outcome: bool = True,
    use_kpi: bool = False,
    include_non_paid_channels: bool = True,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> tf.Tensor

Calcula o resultado incremental a posteriori ou a priori.

Isso calcula o resultado da mídia de cada canal para cada extração de parâmetro a posteriori ou a priori. O resultado incremental é definido como:

E(Outcome|Media_1, Controls) menos E(Outcome|Media_0, Controls)

Aqui, Media_1 significa que a execução de mídia de um determinado canal é multiplicada por scaling_factor1 (1,0 por padrão) para o conjunto de períodos especificados por media_selected_times. De maneira semelhante, Media_0 significa que a execução de mídia é multiplicada por scaling_factor0 (0 por padrão) para esses períodos.

Para canais com dados de alcance e frequência, a frequência é mantida fixa, enquanto o alcance é dimensionado. "Outcome" se refere a revenue, se use_kpi=False, ou kpi, se use_kpi=True. Quando revenue_per_kpi não está definido, use_kpi não pode ser "False".

Se new_data=None, esse método calcula o resultado incremental usando os tensores media, reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments e revenue_per_kpi com que o objeto do Meridian foi inicializado. Esse comportamento pode ser substituído pelo argumento new_data. Por exemplo, new_data=DataTensors(media=new_media) calcula o resultado incremental usando o tensor new_media e os valores originais dos tensores reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments e revenue_per_kpi.

O cálculo neste método depende de duas premissas importantes feitas na implementação do Meridian:

  1. Adicionalidade dos efeitos de mídia (sem interações).
  2. As mudanças de adicionalidade na escala de KPI do modelo correspondem às mudanças na escala de KPI original. Em outras palavras, os efeitos de interceptação e controle não influenciam os efeitos de mídia. Essa premissa é válida no momento porque a transformação do resultado envolve apenas centralização e dimensionamento, por exemplo, sem transformações de registros.

Args
use_posterior Booleano. Se for True, a distribuição a posteriori de impacto incremental será calculada. Caso contrário, será a distribuição a priori.
new_data Contêiner DataTensors opcional com tensores opcionais: media, reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments e revenue_per_kpi. Se for None, o resultado incremental será calculado usando o InputData fornecido ao objeto do Meridian. Se new_data for fornecido, o resultado incremental será calculado usando os novos tensores em new_data e os valores originais dos tensores restantes. Por exemplo, incremental_outcome(new_data=DataTensors(media=new_media) calcula o resultado incremental usando new_media e os valores originais de reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments e revenue_per_kpi. Se algum dos tensores em new_data for fornecido com um número diferente de períodos em relação a InputData, todos os tensores precisarão ser fornecidos com o mesmo número de períodos.
non_media_baseline_values Lista opcional de forma (n_non_media_channels). Cada elemento é um ponto flutuante, o que significa que o valor fixo será usado como base para o canal específico, ou uma das strings "min" ou "max". Isso significa que o valor mínimo ou máximo global será usado como base para os valores ajustados do canal dos tratamentos não relacionados a mídia. Se não for fornecido, o valor mínimo será usado como base para cada canal de tratamentos não relacionados a mídia.
scaling_factor0 Ponto flutuante. O fator pelo qual dimensionar o cenário contrafactual "Media_0" durante os períodos especificados em media_selected_times. Precisa ser não negativo e menor que scaling_factor1.
scaling_factor1 Ponto flutuante. O fator pelo qual dimensionar "Media_1" durante os períodos selecionados especificados em media_selected_times. Precisa ser não negativo e maior que scaling_factor0.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de datas a serem incluídas ou booleanos com comprimento igual ao número de períodos nos argumentos new_XXX, se fornecidos. O resultado incremental corresponde ao KPI incremental gerado durante o argumento selected_times por mídia executada durante o argumento media_selected_times. Se use_kpi=False, selected_times só poderá incluir os períodos que têm dados de entrada revenue_per_kpi. Por padrão, todos os períodos são incluídos quando os dados de revenue_per_kpi estão disponíveis.
media_selected_times Lista opcional que contém um subconjunto de datas a serem incluídas ou booleanos com comprimento igual ao número de períodos em new_media, se fornecido. Se new_media for fornecido, media_selected_times poderá selecionar qualquer subconjunto de períodos em new_media. Se new_media não for fornecido, media_selected_times vai selecionar uma opção de InputData.time. O resultado incremental corresponde ao KPI incremental gerado durante o argumento selected_times por mídia executada durante o argumento media_selected_times. Para cada canal, o resultado incremental é definido como a diferença entre o KPI esperado quando a execução de mídia é dimensionada por scaling_factor1 e scaling_factor0 durante esses períodos especificados. Por padrão, a diferença é entre a média nos níveis de execução históricos ou conforme informado em new_media, em comparação com a execução zero. O padrão é incluir todos os períodos.
aggregate_geos Booleano. Se True, o resultado incremental será somado em todas as regiões.
aggregate_times Booleano. Se True, o resultado incremental será somado em todos os períodos.
inverse_transform_outcome Booleano. Se True, vai retornar o resultado esperado no KPI ou na receita original (dependendo do que é transmitido para use_kpi), conforme foi transmitido para InputData. Se for "False", vai retornar o resultado após a transformação feita por KpiTransformer, refletindo como ele é representado no modelo.
use_kpi Booleano. Se use_kpi = True, o KPI esperado será calculado. Caso contrário, a receita esperada (kpi * revenue_per_kpi) será calculada. É necessário que use_kpi = True se os dados de revenue_per_kpi não estiverem disponíveis ou se inverse_transform_outcome = False.
include_non_paid_channels Booleano. Se for True, os tratamentos não relacionados a mídia e os efeitos orgânicos serão incluídos no cálculo. Se for False, somente a mídia paga e os efeitos de RF serão incluídos.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Tensor de resultado incremental (KPI ou receita, dependendo do argumento use_kpi) com dimensões (n_chains, n_draws, n_geos, n_times, n_channels). Se include_non_paid_channels=True, n_channel é o número total de mídia, RF, mídia orgânica, RF orgânicos e canais que não são de mídia. Se include_non_paid_channels=False, n_channels é o número total de canais de mídia e RF. As dimensões n_geos e n_times serão descartadas se aggregate_geos=True ou aggregate_times=True, respectivamente.

Gera
NotFittedModelError Se sample_posterior() (para use_posterior=True) ou sample_prior() (para use_posterior=False) não tiver sido chamado antes de chamar esse método.
ValueError Se os argumentos new_media não tiverem as mesmas dimensões do tensor que a mídia.

marginal_roi

Ver código-fonte

marginal_roi(
    incremental_increase: float = 0.01,
    use_posterior: bool = True,
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    by_reach: bool = True,
    use_kpi: bool = False,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> (tf.Tensor | None)

Calcula a distribuição a priori ou a posteriori do ROI marginal.

O numerador do ROI marginal (mROI) é a alteração no resultado esperado (kpi ou kpi * revenue_per_kpi) quando o gasto de um canal aumenta um pouco. O denominador do mROI é a pequena fração correspondente do gasto total do canal.

Se new_data=None, esse método calcula o ROI marginal condicionalmente com base nos valores das variáveis de mídia paga com que o objeto do Meridian foi inicializado. O usuário também pode substituir esses dados históricos pelo argumento new_data, desde que as dimensões dos novos tensores sejam correspondentes. Por exemplo,

new_data = DataTensors(media=new_media, frequency=new_frequency)

Se selected_geos ou selected_times forem especificados, o denominador do mROI será baseado no gasto total durante as regiões e períodos selecionados. Uma exceção será gerada se o gasto dos InputData usados para treinar o modelo não tiver dimensões geográficas e de tempo. Se os argumentos new_data.media_spend e new_data.rf_spend forem usados com dimensões diferentes do gasto de InputData, uma exceção será gerada, já que é provável que isso seja um erro do usuário.

Args
incremental_increase Pequena fração pela qual o gasto de cada canal aumenta ao calcular o numerador do mROI. O denominador do mROI é essa fração do gasto total do canal. Usado somente se a margem for True.
use_posterior Se True, a distribuição a posteriori será calculada. Caso contrário, será a distribuição a priori.
new_data Opcional. DataTensors que contêm os dados de media, media_spend, reach, frequency, rf_spend e revenue_per_kpi. Se forem fornecidos, o ROI marginal será calculado com base nos valores dos tensores transmitidos em new_data e os valores originais de todos os tensores restantes. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de meridian.input_data. Se None, o ROI marginal será calculado usando os valores originais de todos os tensores.
selected_geos Opcional. Contém um subconjunto de regiões geográficas a serem incluídas. Por padrão, todas as regiões são incluídas.
selected_times Opcional. Contém um subconjunto de períodos a serem incluídos. Por padrão, todos os períodos são incluídos.
aggregate_geos Se for True, a receita esperada será somada em todas as regiões.
by_reach Usado para um canal com alcance e frequência. Se True, vai retornar o mROI por alcance de uma determinada frequência fixa. Se False, vai retornar o mROI por frequência de um determinado alcance fixo.
use_kpi Se False, a receita será usada para calcular o numerador do mROI. Caso contrário, usa o KPI.
batch_size Número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Tensor de valores de mROI com dimensões (n_chains, n_draws, n_geos, (n_media_channels + n_rf_channels)). A dimensão n_geos será descartada se for aggregate_geos=True.

optimal_freq

Ver código-fonte

optimal_freq(
    freq_grid: (Sequence[float] | None) = None,
    use_posterior: bool = True,
    selected_geos: (Sequence[str | int] | None) = None,
    selected_times: (Sequence[str | int] | None) = None,
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL
) -> xr.Dataset

Calcula a frequência ideal que maximiza o ROI médio a posteriori.

Para essa otimização, o gasto histórico é usado e fixado, e a frequência é restrita para se manter constante em todas as regiões geográficas e períodos. O alcance é calculado para cada região geográfica, e período é calculado de modo que o número de impressões permaneça inalterado à medida que a frequência varia. O Meridian resolve a frequência com que o ROI médio a posteriori é otimizado.

Args
freq_grid Lista de valores de frequência. O ROI de cada canal é calculado para cada valor de frequência na lista. Por padrão, a lista inclui números de 1.0 até a frequência máxima em incrementos de 0.1.
use_posterior Booleano. Se True, as frequências ideais a posteriori serão geradas. Se False, serão as frequências ideais a priori.
selected_geos Lista opcional que contém um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
confidence_level Nível de confiança para intervalos de confiança a priori e a posteriori, representado como um valor entre zero e um.

Retorna
Um conjunto de dados xarray que contém:

  • Coordenadas: frequency, rf_channel, metric (mean, median, ci_lo, ci_hi).
  • Variáveis de dados:
    • optimal_frequency: a frequência que otimiza a média a posteriori do ROI.
    • roi: o ROI de cada valor de frequência em freq_grid.
    • optimized_incremental_outcome: o resultado incremental com base na frequência ideal.
    • optimized_pct_of_contribution: a porcentagem da contribuição com base na frequência ideal.
    • optimized_effectiveness: a eficácia com base na frequência ideal.
    • optimized_roi: o ROI com base na frequência ideal.
    • optimized_mroi_by_reach: o ROI marginal com uma pequena mudança no alcance e na frequência fixa na frequência ideal.
    • optimized_mroi_by_frequency: o ROI marginal com uma pequena mudança na frequência ideal e no alcance fixo.
    • optimized_cpik: o CPIK com base na frequência ideal.

Gera
NotFittedModelError Se sample_posterior() (para use_posterior=True) ou sample_prior() (para use_posterior=False) não tiver sido chamado antes de chamar esse método.
ValueError Se não houver canais com dados de alcance e frequência.

predictive_accuracy

Ver código-fonte

predictive_accuracy(
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> xr.Dataset

Calcula as métricas de ajuste de R-Squared, MAPE e wMAPE.

R-Squared, MAPE (erro percentual absoluto médio) e wMAPE (erro percentual absoluto ponderado) são calculados na escala de receita (KPI * revenue_per_kpi) quando revenue_per_kpi é especificado ou na escala de KPI quando revenue_per_kpi = None. Essa é a mesma escala usada no numerador do ROI (resultado incremental).

Os erros de previsão em wMAPE são ponderados pela receita real (KPI * revenue_per_kpi) quando revenue_per_kpi é especificado ou ponderado pela escala de KPI quando revenue_per_kpi = None. Isso significa que os erros percentuais quando a receita é alta têm mais peso do que os erros ocorridos quando a receita é baixa.

R-Squared, MAPE e wMAPE são calculados no nível do modelo (uma observação por região geográfica e período) e no nível nacional (agregando o KPI ou o resultado da receita em todas as regiões geográficas para que haja uma observação por período).

R-Squared, MAPE e wMAPE são calculados para a amostra completa. Se o objeto do modelo tiver observações de validação, R-squared, MAPE e wMAPE também serão calculados para os subconjuntos Train e Test.

Args
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de datas a serem incluídas. Por padrão, todos os períodos são incluídos.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. Por padrão, batch_size é 100. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Um conjunto de dados xarray que contém os valores calculados R_Squared, MAPE e wMAPE, com coordenadas metric, geo_granularity, evaluation_set e a variável de dados value. Se holdout_id existir, os dados serão divididos em subseções 'Train', 'Test' e 'All Data', e as três métricas serão calculadas para cada uma delas.

response_curves

Ver código-fonte

response_curves(
    spend_multipliers: (list[float] | None) = None,
    use_posterior: bool = True,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    by_reach: bool = True,
    use_optimal_frequency: bool = False,
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> xr.Dataset

Método para gerar curvas de resposta xarray.Dataset.

As curvas de resposta são calculadas no nível nacional, considerando o padrão de veiculação histórico em várias regiões geográficas e períodos para cada canal de mídia. Uma lista de multiplicadores é aplicada ao gasto histórico total de cada canal de mídia para obter o x-values em que a curva de resposta do canal é calculada.

Args
spend_multipliers Lista de multiplicadores. O gasto total de cada canal é multiplicado por esses fatores para conseguir os valores em que a curva é calculada para esse canal.
use_posterior Booleano. Se True, as curvas de resposta a posteriori serão geradas. Se False, serão as curvas de resposta a priori.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de dimensões de tempo a serem incluídas. Por padrão, todos os períodos são incluídos. As strings e os números inteiros da dimensão de tempo precisam estar alinhados com Meridian.n_times.
by_reach Booleano. Para canais com alcance e frequência. Se True, vai mostrar a curva de resposta por alcance. Se False, será a curva de resposta por frequência.
use_optimal_frequency Se True, vai usar a frequência ideal para representar as curvas de resposta. O padrão é False.
confidence_level Nível de confiança para intervalos de confiança a priori e a posteriori, representado como um valor entre zero e um.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Um xarray.Dataset que contém os dados necessários para visualizar as curvas de resposta.

rhat_summary

Ver código-fonte

rhat_summary(
    bad_rhat_threshold: float = 1.2
) -> pd.DataFrame

Calcula um resumo dos valores de R-hat para cada parâmetro no modelo.

Resume a redução de escala potencial de Gelman & Rubin (1992) para a convergência de cadeia, comumente chamada de R-hat. É uma medida de diagnóstico de convergência que mede o grau em que a variância (das médias) entre as cadeias excede o que seria esperado se elas fossem distribuídas de forma idêntica. Valores próximos de 1,0 indicam convergência. R-hat < 1,2 indica a convergência aproximada e é um limite razoável para muitos problemas (Brooks & Gelman, 1998).

Referências
Andrew Gelman e Donald B. Rubin. Inference from Iterative Simulation Using Multiple Sequences. Statistical Science, 7(4):457-472, 1992. Stephen P. Brooks e Andrew Gelman. General Methods for Monitoring Convergence of Iterative Simulations. Journal of Computational and Graphical Statistics, 7(4), 1998.

Args
bad_rhat_threshold O limite para determinar quais valores de R-hat são considerados ruins.

Retorna
Um DataFrame com as seguintes colunas:

  • n_params: o número de parâmetros respectivos no modelo.
  • avg_rhat: o valor médio de R-hat para o respectivo parâmetro.
  • n_params: o número de parâmetros respectivos no modelo.
  • avg_rhat: o valor médio de R-hat para o respectivo parâmetro.
  • max_rhat: o valor máximo de R-hat para o respectivo parâmetro.
  • percent_bad_rhat: a porcentagem de valores de R-hat para o respectivo parâmetro maiores que bad_rhat_threshold.
  • row_idx_bad_rhat: os índices de linha dos valores de R-hat maiores que bad_rhat_threshold.
  • col_idx_bad_rhat: os índices de coluna dos valores de R-hat maiores que bad_rhat_threshold.

Gera
NotFittedModelError Se self.sample_posterior() não for chamado antes de chamar esse método.
ValueError Se o número de dimensões da matriz R-hat para um parâmetro não for 1 ou 2.

roi

Ver código-fonte

roi(
    use_posterior: bool = True,
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    use_kpi: bool = False,
    batch_size: int = constants.DEFAULT_BATCH_SIZE
) -> tf.Tensor

Calcula a distribuição a priori ou a posteriori do ROI para cada canal de mídia.

O numerador do ROI é a mudança no resultado esperado (kpi ou kpi * revenue_per_kpi) quando o gasto de um canal é definido como zero, deixando o gasto de todos os outros canais inalterado. O denominador do ROI é o gasto total do canal.

Se for new_data=None, esse método calcula o ROI condicionalmente aos valores das variáveis de mídia paga com que o objeto do Meridian foi inicializado. O usuário também pode substituir esses dados históricos pelo argumento new_data, desde que as dimensões dos novos tensores sejam correspondentes. Por exemplo,

new_data = DataTensors(media=new_media, frequency=new_frequency)

Se selected_geos ou selected_times forem especificados, o denominador do ROI será o gasto total durante as regiões e períodos selecionados. Uma exceção será gerada se o gasto dos InputData usados para treinar o modelo não tiver dimensões geográficas e de tempo. Se os argumentos new_data.media_spend e new_data.rf_spend forem usados com dimensões diferentes do gasto de InputData, uma exceção será gerada, já que é provável que isso seja um erro do usuário.

Args
use_posterior Booleano. Se True, a distribuição a posteriori será calculada. Caso contrário, será a distribuição a priori.
new_data Opcional. DataTensors que contêm dados media, media_spend, reach, frequency, rf_spend e revenue_per_kpi. Se forem fornecidos, o CPIK será calculado com base nos valores dos tensores transmitidos em new_data e os valores originais de todos os tensores restantes. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de meridian.input_data. Se for None, o ROI será calculado usando os valores originais de todos os tensores.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se for True, a receita esperada será somada em todas as regiões.
use_kpi Se for False, a receita será usada para calcular o numerador do ROI. Caso contrário, usará o KPI.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.

Retorna
Tensor de valores de ROI com dimensões (n_chains, n_draws, n_geos, (n_media_channels + n_rf_channels)). A dimensão n_geos será descartada se for aggregate_geos=True.

summary_metrics

Ver código-fonte

summary_metrics(
    new_data: (meridian.analysis.analyzer.DataTensors | None) = None,
    marginal_roi_by_reach: bool = True,
    marginal_roi_incremental_increase: float = 0.01,
    selected_geos: (Sequence[str] | None) = None,
    selected_times: (Sequence[str] | None) = None,
    aggregate_geos: bool = True,
    aggregate_times: bool = True,
    optimal_frequency: (Sequence[float] | None) = None,
    use_kpi: bool = False,
    confidence_level: float = constants.DEFAULT_CONFIDENCE_LEVEL,
    batch_size: int = constants.DEFAULT_BATCH_SIZE,
    include_non_paid_channels: bool = False
) -> xr.Dataset

Retorna métricas de resumo.

Se for new_data=None, esse método calcula todas as métricas condicionalmente com base nos valores das variáveis de dados com que o objeto do Meridian foi inicializado. O usuário também pode substituir esses dados históricos pelo argumento new_data, desde que as dimensões dos novos tensores sejam correspondentes. Por exemplo,

new_data = DataTensors(
    media=new_media,
    frequency=new_frequency,
    non_media_treatments=new_non_media_treatments)

As métricas mroi e effectiveness não são definidas (math.nan) para a dimensão de canal agregado "All Paid Channels".

Args
new_data Objeto DataTensors opcional com novos tensores opcionais: media, reach, frequency, organic_media, organic_reach, organic_frequency, non_media_treatments, controls e revenue_per_kpi. Se fornecido, as métricas de resumo são calculadas usando os valores dos tensores transmitidos em new_data e os valores originais de todos os tensores restantes. As dimensões dos novos tensores precisam corresponder às dimensões dos tensores originais de meridian.input_data. Se None, as métricas de resumo serão calculadas usando os valores originais de todos os tensores.
marginal_roi_by_reach Booleano. O ROI marginal (mROI) é definido como o retorno do próximo dólar gasto. Se esse argumento for True, será considerado que o próximo dólar gasto afetará somente o alcance, mantendo a frequência constante. Se esse argumento for False, será considerado que o próximo dólar gasto afetará somente a frequência, mantendo o alcance constante. Usado somente quando include_non_paid_channels é False.
marginal_roi_incremental_increase Pequena fração pela qual o gasto de cada canal aumenta ao calcular o numerador do mROI. O denominador do mROI é essa fração do gasto total do canal. Usado somente quando include_non_paid_channels é False.
selected_geos Lista opcional contendo um subconjunto de regiões geográficas a serem adicionadas. Por padrão, todas as regiões são incluídas.
selected_times Lista opcional que contém um subconjunto de horários a serem adicionados. Por padrão, todos os períodos são incluídos.
aggregate_geos Booleano. Se True, o resultado esperado será somado em todas as regiões.
aggregate_times Booleano. Se True, o resultado esperado será somado em todos os períodos. Se False, ROI, mROI, "Eficácia" e CPIK não forem informados, porque não há uma interpretação clara por período,
optimal_frequency Uma lista opcional com a dimensão n_rf_channels, que contém a frequência ideal por canal, que maximiza o ROI médio a posteriori. O valor padrão é None, e a frequência histórica é usada para o cálculo das métricas.
use_kpi Booleano. Se for True, as métricas de resumo serão calculadas usando o KPI. Se False, as métricas serão calculadas usando a receita.
confidence_level Nível de confiança para intervalos de confiança de métricas de resumo, representado como um valor entre zero e um.
batch_size Número inteiro que representa o número máximo de extrações por cadeia em cada lote. O cálculo é executado em lotes para evitar o esgotamento da memória. Se ocorrer um erro de memória, tente reduzir o batch_size. O cálculo costuma ser mais rápido com valores de batch_size maiores.
include_non_paid_channels Booleano. Se for True, canais não pagos (mídia orgânica, alcance e frequência orgânicos e tratamentos não relacionados a mídia) serão incluídos no resumo, mas apenas as métricas independentes do gasto serão informadas. Se for False, apenas os canais pagos (mídia, alcance e frequência) serão incluídos, mas o resumo também terá as métricas dependentes do gasto. Padrão: False.

Retorna
Um xr.Dataset com coordenadas: channel, metric (mean, median, ci_low e ci_high), distribution (a priori, a posteriori) e contém as seguintes variáveis de dados não pagos: incremental_outcome, pct_of_contribution, effectiveness e as variáveis de dados pagos impressions, pct_of_impressions, spend, pct_of_spend, CPM, roi, mroi e cpik. As variáveis de dados pagos só são incluídas quando include_non_paid_channels é False. As métricas roi, mroi, cpik e effectiveness não são informadas quando aggregate_times=False, porque não têm uma interpretação clara por período.