coviewing_tools
Databricks coviewing factors generation utilities.
This module provides utility functions for the coviewing factors generation process, associated with the synpop generation.
Requires: - databricks-sdk - time
Author: Gino F. Fazzi gino.franco.fazzi@audienceproject.com
coviewing_tools.CoViewCalculator
Class to calculate coviewing factors for a given set of contries and subsets of media. The class is initialized with the subsets and countries to be used in the calculation.
Date created: 04/08/2026 Author: Gino F. Fazzi gino.franco.fazzi@audienceproject.com
coviewing_tools.CoViewCalculator.__init__()
Create a calculator with no configured countries or subsets.
Notes
Countries and media subsets are supplied per call to
:meth:calculate_coviewing_factors rather than stored here.
:attr:coviewing_factors_df only exists after that method has run.
coviewing_tools.CoViewCalculator.calculate_coviewing_factors(countries=None, subsets=None, run_date=None, save_to_table=False, verbose=False)
Calculate coviewing factors per country and media subset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
countries
|
list
|
Country codes to process. When omitted, the countries with an active synthetic population are used. |
None
|
subsets
|
dict
|
Mapping of media subset name to its filter definition. When omitted,
|
None
|
run_date
|
Optional upper bound on the demographic-weights population date. Defaults to the most recent active population. |
None
|
|
save_to_table
|
Currently unused. Persisting results requires calling
:meth: |
False
|
|
verbose
|
Print progress information while processing. |
False
|
Returns:
| Type | Description |
|---|---|
None
|
Results are stored on :attr: |
Notes
The minimum age is 17 for GB and 18 elsewhere, matching the
establishment-survey age brackets.
coviewing_tools.CoViewCalculator.save_coviewing_factors_to_table(table_path=None)
Save the coviewing factors to a Delta table in S3.
Existing rows matching on Date, Country, Subset, and
Filter are updated; new rows are inserted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
table_path
|
Target Delta table location. Defaults to
|
None
|
Returns:
| Type | Description |
|---|---|
None
|
The factors are merged into the Delta table rather than returned. |
Raises:
| Type | Description |
|---|---|
AttributeError
|
If :meth: |
Notes
Despite the create-if-missing branch, this currently requires
table_path to already be a Delta table: DeltaTable.forPath is
called before the existence check and fails for a missing table.
coviewing_tools.calculate_coviewing_factors_3parts(weighted_survey, media_name_vals, verbose=False)
Calculate three-part coviewing factors from a weighted survey.
Author: Kathrine Kuszon
Adapted: 04/08/2026 (Gino F. Fazzi, gino.franco.fazzi@audienceproject.com)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
weighted_survey
|
Weighted survey Spark DataFrame. Must contain a weight column |
required | |
media_name_vals
|
Media names to calculate coviewing factors for. |
required | |
verbose
|
Print intermediate totals while processing. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Per-media coviewing factors unioned across media, with an added
|
coviewing_tools.weight_establishment_survey(survey, population_weights, weight_column_name='N', id_column_name='id', lower_age_limit=16)
This function weights the establishment survey according to the population proportions. Age is set to be grouped into the selected age brackets because of the responses for primary shopper in the survey.
Author: Christian Brandstrup Starup, christian@audienceproject.com Date created: 08/06/2023 Last modified: 10/02/2025 Adapted: 04/08/2026 (Gino F. Fazzi, gino.franco.fazzi@audienceproject.com)
Arguments:
survey : spark dataframe The formatted establishment survey population_weights : spark dataframe The population, in weight format. Must have age & gender. weight_column_name : str Name of the column holding weight in the population, and the name of the coming weight column in the survey id_column_name : str Name of the survey's respondent identifier column. lower_age_limit : int Minimum age retained from the population before weighting. Respondents below this age are excluded. Returns:
survey : spark dataframe Same survey as before, but with added "weight" column.