Join the newly launched Discord
community for real-time discussions, peer support, and direct interaction with the Meridian team!
Load geo-level data without reach and frequency
Stay organized with collections
Save and categorize content based on your preferences.
Simulated data is provided as an example for each data type and format in the
following sections.
CSV
To load the simulated CSV
data using CsvDataLoader
:
-
Map the column names to the variable types. The required variable types are time
, geo
, controls
, population
, kpi
, revenue_per_kpi
, media
,
and media_spend
. For the definition of each variable, see Collect and organize your data
.
coord_to_columns
=
load
.
CoordToColumns
(
time
=
'time'
,
geo
=
'geo'
,
controls
=
[
'GQV'
,
'Discount'
,
'Competitor_Sales'
],
population
=
'population'
,
kpi
=
'conversions'
,
revenue_per_kpi
=
'revenue_per_conversion'
,
media
=
[
'Channel0_impression'
,
'Channel1_impression'
,
'Channel2_impression'
,
'Channel3_impression'
,
'Channel4_impression'
,
'Channel5_impression'
,
],
media_spend
=
[
'Channel0_spend'
,
'Channel1_spend'
,
'Channel2_spend'
,
'Channel3_spend'
,
'Channel4_spend'
,
'Channel5_spend'
,
],
)
-
Map the media variables and the media spends to the designated channel names
that you want to display in the two-page output. In the following example, Channel0_impression
and Channel0_spend
are connected to the same
channel, Channel0
.
correct_media_to_channel
=
{
'Channel0_impression'
:
'Channel0'
,
'Channel1_impression'
:
'Channel1'
,
'Channel2_impression'
:
'Channel2'
,
'Channel3_impression'
:
'Channel3'
,
'Channel4_impression'
:
'Channel4'
,
'Channel5_impression'
:
'Channel5'
,
}
correct_media_spend_to_channel
=
{
'Channel0_spend'
:
'Channel0'
,
'Channel1_spend'
:
'Channel1'
,
'Channel2_spend'
:
'Channel2'
,
'Channel3_spend'
:
'Channel3'
,
'Channel4_spend'
:
'Channel4'
,
'Channel5_spend'
:
'Channel5'
,
}
-
Load the data using CsvDataLoader
:
loader
=
load
.
CsvDataLoader
(
csv_path
=
f
'/
{
PATH
}
/
{
FILENAME
}
.csv'
,
kpi_type
=
'non_revenue'
,
coord_to_columns
=
coord_to_columns
,
media_to_channel
=
correct_media_to_channel
,
media_spend_to_channel
=
correct_media_spend_to_channel
,
)
data
=
loader
.
load
()
Where:
-
kpi_type
is either 'revenue'
or 'non_revenue'
.
-
PATH
is the path to the data file location.
-
FILENAME
is the name of your data file.
Xarray Dataset
To load the pickled simulated Xarray Dataset
using XrDatasetDataLoader
:
-
Load the data using pickle
:
import
pickle
with
open
(
f
'/
{
PATH
}
/
{
FILENAME
}
.pkl'
,
'r'
)
as
fh
:
dataset
=
pickle
.
load
(
fh
)
Where:
-
PATH
is the path to the data file location.
-
FILENAME
is the name of your data file.
-
Pass the dataset to XrDatasetDataLoader
. Use the name_mapping
argument
to map the coordinates and arrays. Provide mapping if the names in the input
dataset are different from the required names. The required coordinate
names are geo
, time
, control_variable
and media_channel
. The
required data variables names are kpi
, revenue_per_kpi
, controls
, population
, media
, and media_spend
.
loader
=
load
.
XrDatasetDataLoader
(
dataset
,
kpi_type
=
'non_revenue'
,
name_mapping
=
{
'channel'
:
'media_channel'
,
'control'
:
'control_variable'
,
'conversions'
:
'kpi'
,
'revenue_per_conversion'
:
'revenue_per_kpi'
,
'control_value'
:
'controls'
,
'spend'
:
'media_spend'
,
},
)
data
=
loader
.
load
()
Where:
-
kpi_type
is either 'revenue'
or 'non_revenue'
.
Numpy ndarray
To load numpy ndarrays directly, use NDArrayInputDataBuilder
:
-
Create the data into separate numpy ndarrays.
import
numpy
as
np
kpi_nd
=
np
.
array
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
controls_nd
=
np
.
array
([
[[
1
,
5
],
[
2
,
6
],
[
3
,
4
]],
[[
7
,
8
],
[
9
,
10
],
[
11
,
12
]],
[[
13
,
14
],
[
15
,
16
],
[
17
,
18
]],
])
population_nd
=
np
.
array
([
1
,
2
,
3
])
revenue_per_kpi_nd
=
np
.
array
([[
1
,
2
,
3
],
[
4
,
5
,
6
],
[
7
,
8
,
9
]])
media_nd
=
np
.
array
([
[[
1
,
5
],
[
2
,
6
],
[
3
,
4
]],
[[
7
,
8
],
[
9
,
10
],
[
11
,
12
]],
[[
13
,
14
],
[
15
,
16
],
[
17
,
18
]],
])
media_spend_nd
=
np
.
array
([
[[
1
,
5
],
[
2
,
6
],
[
3
,
4
]],
[[
7
,
8
],
[
9
,
10
],
[
11
,
12
]],
[[
13
,
14
],
[
15
,
16
],
[
17
,
18
]],
])
-
Use a NDArrayInputDataBuilder
to set time and geos, as well as give channel or dimension
names as required in a Meridian input data.
For the definition of each variable, see Collect and organize your data
.
from
meridian.data
import
nd_array_input_data_builder
as
data_builder
builder
=
(
data_builder
.
NDArrayInputDataBuilder
(
kpi_type
=
'non_revenue'
)
)
builder
.
time_coords
=
[
'2024-01-02'
,
'2024-01-03'
,
'2024-01-01'
]
builder
.
media_time_coords
=
[
'2024-01-02'
,
'2024-01-03'
,
'2024-01-01'
]
builder
.
geos
=
[
'B'
,
'A'
,
'C'
]
builder
=
(
builder
.
with_kpi
(
kpi_nd
)
.
with_revenue_per_kpi
(
revenue_per_kpi_nd
)
.
with_population
(
population_nd
)
.
with_controls
(
controls_nd
,
control_names
=
[
"control0"
,
"control1"
])
.
with_media
(
m_nd
=
media_nd
,
ms_nd
=
media_spend_nd
,
media_channels
=
[
"channel0"
,
"channel1"
]
)
)
data
=
builder
.
build
()
Where:
-
kpi_type
is either 'revenue'
or 'non_revenue'
.
To load the simulated other data format
(such as excel
) using DataFrameInputDataBuilder
:
-
Read the data (such as an excel
spreadsheet) into one or more Pandas DataFrame
(s).
import
pandas
as
pd
df
=
pd
.
read_excel
(
'https://github.com/google/meridian/raw/main/meridian/data/simulated_data/xlsx/geo_media.xlsx'
,
engine
=
'openpyxl'
,
)
-
Use a DataFrameInputDataBuilder
to map column names to the variable types required in a Meridian input data.
For the definition of each variable, see Collect and organize your data
.
from
meridian.data
import
data_frame_input_data_builder
as
data_builder
builder
=
data_builder
.
DataFrameInputDataBuilder
(
kpi_type
=
'non_revenue'
,
default_kpi_column
=
"conversions"
,
default_revenue_per_kpi_column
=
"revenue_per_conversion"
,
)
builder
=
(
builder
.
with_kpi
(
df
)
.
with_revenue_per_kpi
(
df
)
.
with_population
(
df
)
.
with_controls
(
df
,
control_cols
=
[
"GQV"
,
"Discount"
,
"Competitor_Sales"
])
)
channels
=
[
"Channel0"
,
"Channel1"
,
"Channel2"
,
"Channel3"
,
"Channel4"
,
"Channel5"
]
builder
=
builder
.
with_media
(
df
,
media_cols
=
[
f
"
{
channel
}
_impression"
for
channel
in
channels
],
media_spend_cols
=
[
f
"
{
channel
}
_spend"
for
channel
in
channels
],
media_channels
=
channels
,
)
data
=
builder
.
build
()
Where:
-
kpi_type
is either 'revenue'
or 'non_revenue'
.
Next, you can create your model
.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-07-10 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-07-10 UTC."],[[["\u003cp\u003eSimulated data examples are provided for CSV, Xarray Dataset, and other formats like Excel to demonstrate data loading.\u003c/p\u003e\n"],["\u003cp\u003eLoading CSV data requires mapping column names to predefined variable types and mapping media variables and spends to specific channel names using \u003ccode\u003eCsvDataLoader\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eLoading Xarray Dataset data involves using \u003ccode\u003epickle\u003c/code\u003e to read in data, and \u003ccode\u003eXrDatasetDataLoader\u003c/code\u003e for processing, which also requires mapping if dataset names differ from the required coordinate and variable names.\u003c/p\u003e\n"],["\u003cp\u003eLoading other data formats, like Excel, requires mapping column names and media channels, similar to CSV, but uses \u003ccode\u003eDataFrameDataLoader\u003c/code\u003e after reading the data into a dataframe.\u003c/p\u003e\n"],["\u003cp\u003eAfter loading the data in any of these formats, you may then proceed to creating a model.\u003c/p\u003e\n"]]],[],null,["# Load geo-level data without reach and frequency\n\nSimulated data is provided as an example for each data type and format in the\nfollowing sections.\n\nCSV\n---\n\nTo load the\n[simulated CSV](https://github.com/google/meridian/tree/main/meridian/data/simulated_data/csv/geo_media.csv)\ndata using `CsvDataLoader`:\n\n1. Map the column names to the variable types. The required variable types are\n `time`, `geo`, `controls`, `population`, `kpi`, `revenue_per_kpi`, `media`,\n and `media_spend`. For the definition of each variable, see\n [Collect and organize your data](/meridian/docs/user-guide/collect-data).\n\n coord_to_columns = load.CoordToColumns(\n time='time',\n geo='geo',\n controls=['GQV', 'Discount', 'Competitor_Sales'],\n population='population',\n kpi='conversions',\n revenue_per_kpi='revenue_per_conversion',\n media=[\n 'Channel0_impression',\n 'Channel1_impression',\n 'Channel2_impression',\n 'Channel3_impression',\n 'Channel4_impression',\n 'Channel5_impression',\n ],\n media_spend=[\n 'Channel0_spend',\n 'Channel1_spend',\n 'Channel2_spend',\n 'Channel3_spend',\n 'Channel4_spend',\n 'Channel5_spend',\n ],\n )\n\n2. Map the media variables and the media spends to the designated channel names\n that you want to display in the two-page output. In the following example,\n `Channel0_impression` and `Channel0_spend` are connected to the same\n channel, `Channel0`.\n\n correct_media_to_channel = {\n 'Channel0_impression': 'Channel0',\n 'Channel1_impression': 'Channel1',\n 'Channel2_impression': 'Channel2',\n 'Channel3_impression': 'Channel3',\n 'Channel4_impression': 'Channel4',\n 'Channel5_impression': 'Channel5',\n }\n correct_media_spend_to_channel = {\n 'Channel0_spend': 'Channel0',\n 'Channel1_spend': 'Channel1',\n 'Channel2_spend': 'Channel2',\n 'Channel3_spend': 'Channel3',\n 'Channel4_spend': 'Channel4',\n 'Channel5_spend': 'Channel5',\n }\n\n3. Load the data using `CsvDataLoader`:\n\n loader = load.CsvDataLoader(\n csv_path=f'/{PATH}/{FILENAME}.csv',\n kpi_type='non_revenue',\n coord_to_columns=coord_to_columns,\n media_to_channel=correct_media_to_channel,\n media_spend_to_channel=correct_media_spend_to_channel,\n )\n data = loader.load()\n\n Where:\n - `kpi_type` is either `'revenue'` or `'non_revenue'`.\n - `PATH` is the path to the data file location.\n - `FILENAME` is the name of your data file.\n\nXarray Dataset\n--------------\n\nTo load the pickled\n[simulated Xarray Dataset](https://github.com/google/meridian/tree/main/meridian/data/simulated_data/pkl/geo_media.pkl)\nusing `XrDatasetDataLoader`:\n\n1. Load the data using `pickle`:\n\n import pickle\n with open(f'/{PATH}/{FILENAME}.pkl', 'r') as fh:\n dataset = pickle.load(fh)\n\n Where:\n - `PATH` is the path to the data file location.\n - `FILENAME` is the name of your data file.\n2. Pass the dataset to `XrDatasetDataLoader`. Use the `name_mapping` argument\n to map the coordinates and arrays. Provide mapping if the names in the input\n dataset are different from the required names. The required coordinate\n names are `geo`, `time`, `control_variable` and `media_channel`. The\n required data variables names are `kpi`, `revenue_per_kpi`, `controls`,\n `population`, `media`, and `media_spend`.\n\n loader = load.XrDatasetDataLoader(\n dataset,\n kpi_type='non_revenue',\n name_mapping={\n 'channel': 'media_channel',\n 'control': 'control_variable',\n 'conversions': 'kpi',\n 'revenue_per_conversion': 'revenue_per_kpi',\n 'control_value': 'controls',\n 'spend': 'media_spend',\n },\n )\n\n data = loader.load()\n\n Where:\n - `kpi_type` is either `'revenue'` or `'non_revenue'`.\n\nNumpy ndarray\n-------------\n\nTo load numpy ndarrays directly, use `NDArrayInputDataBuilder`:\n\n1. Create the data into separate numpy ndarrays.\n\n import numpy as np\n\n kpi_nd = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])\n controls_nd = np.array([\n [[1, 5], [2, 6], [3, 4]],\n [[7, 8], [9, 10], [11, 12]],\n [[13, 14], [15, 16], [17, 18]],\n ])\n population_nd = np.array([1, 2, 3])\n revenue_per_kpi_nd = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])\n media_nd = np.array([\n [[1, 5], [2, 6], [3, 4]],\n [[7, 8], [9, 10], [11, 12]],\n [[13, 14], [15, 16], [17, 18]],\n ])\n media_spend_nd = np.array([\n [[1, 5], [2, 6], [3, 4]],\n [[7, 8], [9, 10], [11, 12]],\n [[13, 14], [15, 16], [17, 18]],\n ])\n\n2. Use a\n [`NDArrayInputDataBuilder`](https://github.com/google/meridian/blob/4624447e0aace5c24d42b58dd1cfd8fe0dc00971/meridian/data/nd_array_input_data_builder.py#L25)\n to set time and geos, as well as give channel or dimension\n names as required in a Meridian input data.\n For the definition of each variable, see\n [Collect and organize your data](/meridian/docs/user-guide/collect-data).\n\n from meridian.data import nd_array_input_data_builder as data_builder\n\n builder = (\n data_builder.NDArrayInputDataBuilder(kpi_type='non_revenue')\n )\n builder.time_coords = ['2024-01-02', '2024-01-03', '2024-01-01']\n builder.media_time_coords = ['2024-01-02', '2024-01-03', '2024-01-01']\n builder.geos = ['B', 'A', 'C']\n builder = (\n builder\n .with_kpi(kpi_nd)\n .with_revenue_per_kpi(revenue_per_kpi_nd)\n .with_population(population_nd)\n .with_controls(\n controls_nd,\n control_names=[\"control0\", \"control1\"])\n .with_media(\n m_nd=media_nd,\n ms_nd=media_spend_nd,\n media_channels=[\"channel0\", \"channel1\"]\n )\n )\n\n data = builder.build()\n\n Where:\n - `kpi_type` is either `'revenue'` or `'non_revenue'`.\n\nPandas DataFrames or other data formats\n---------------------------------------\n\nTo load the\n[simulated other data format](https://github.com/google/meridian/tree/main/meridian/data/simulated_data/xlsx/geo_media.xlsx)\n(such as `excel`) using `DataFrameInputDataBuilder`:\n\n1. Read the data (such as an `excel` spreadsheet) into one or more Pandas\n `DataFrame`(s).\n\n import pandas as pd\n\n df = pd.read_excel(\n 'https://github.com/google/meridian/raw/main/meridian/data/simulated_data/xlsx/geo_media.xlsx',\n engine='openpyxl',\n )\n\n2. Use a\n [`DataFrameInputDataBuilder`](https://github.com/google/meridian/blob/4624447e0aace5c24d42b58dd1cfd8fe0dc00971/meridian/data/data_frame_input_data_builder.py#L25)\n to map column names to the variable types required in a Meridian input data.\n For the definition of each variable, see\n [Collect and organize your data](/meridian/docs/user-guide/collect-data).\n\n from meridian.data import data_frame_input_data_builder as data_builder\n\n builder = data_builder.DataFrameInputDataBuilder(\n kpi_type='non_revenue',\n default_kpi_column=\"conversions\",\n default_revenue_per_kpi_column=\"revenue_per_conversion\",\n )\n builder = (\n builder\n .with_kpi(df)\n .with_revenue_per_kpi(df)\n .with_population(df)\n .with_controls(df, control_cols=[\"GQV\", \"Discount\", \"Competitor_Sales\"])\n )\n channels = [\"Channel0\", \"Channel1\", \"Channel2\", \"Channel3\", \"Channel4\", \"Channel5\"]\n builder = builder.with_media(\n df,\n media_cols=[f\"{channel}_impression\" for channel in channels],\n media_spend_cols=[f\"{channel}_spend\" for channel in channels],\n media_channels=channels,\n )\n\n data = builder.build()\n\n Where:\n - `kpi_type` is either `'revenue'` or `'non_revenue'`.\n\nNext, you can [create your model](/meridian/docs/user-guide/modeling-overview)."]]
