Skip to content

Commit 728b130

Browse files
vpratzvpratz
committed
[no ci] add draft for data processing section
1 parent 4140afe commit 728b130

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎docsrc/source/user_guide/data_processing.ipynb‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "d030332b-2bb3-4b6c-b332-164206123b8f",
6+
"metadata": {},
7+
"source": [
8+
"# Data Processing: Adapters\n",
9+
"\n",
10+
"To ensure that the training data generated by a simulator can be used for deep learning, we have to bring our data into the structure required by BayesFlow. The {py:class}`~bayesflow.adapters.Adapter` class provides multiple flexible functionalities, from standardization to renaming, and many more.\n",
11+
"\n",
12+
"## BayesFlow's Data Structure\n",
13+
"\n",
14+
"BayesFlow offers a standardized interface for training neural networks. Data and parameters are organized in dictionaries. The inputs to the networks are organized in specific dictionary entries.\n",
15+
"\n",
16+
"- `inference_variables` (required): The variables of the distribution we try to approximate. For a posterior distribution, this would be the parameters. For a likelihood function, this would be the data.\n",
17+
"- `summary_variables` (optional): Variables that are passed through the summary network, and subsequently used as a condition for the inference network. In a posterior estimation setting, this would be the data (if a summary network is used).\n",
18+
"- `inference_conditions` (optional): Conditions for the inference network that are passed directly, without going through a summary network. This is useful for context variables, as well as for the data when not summary network is used.\n",
19+
"\n",
20+
"In addition, we have to ensure that the correct data type is passed, usually `float32`. The {py:class}`~bayesflow.adapters.Adapter` class makes it easy to transform the data into the required structure."
21+
]
22+
},
23+
{
24+
"cell_type": "markdown",
25+
"id": "9380af80-0638-4059-ab5e-ed8c181e9a93",
26+
"metadata": {},
27+
"source": [
28+
"### Example: Posterior Estimation\n",
29+
"\n",
30+
"Let's start with a simple posterior estimation example, where we want to approximate the posterior distribution for parameters `theta_1` and `theta_2`, conditional on data `x`. First, we construct a simple dataset."
31+
]
32+
},
33+
{
34+
"cell_type": "code",
35+
"execution_count": 12,
36+
"id": "30505f99-db0f-4651-9de6-efcb282f578c",
37+
"metadata": {},
38+
"outputs": [
39+
{
40+
"name": "stdout",
41+
"output_type": "stream",
42+
"text": [
43+
"Shapes: {'theta_1': (2, 1), 'theta_2': (2, 1), 'x': (2, 3)}\n"
44+
]
45+
}
46+
],
47+
"source": [
48+
"import bayesflow as bf\n",
49+
"import numpy as np\n",
50+
"\n",
51+
"batch_size = 2\n",
52+
"rng = np.random.default_rng(seed=2025)\n",
53+
"data = {\n",
54+
" \"theta_1\": np.zeros((batch_size, 1)),\n",
55+
" \"theta_2\": np.ones((batch_size, 1)),\n",
56+
" \"x\": rng.uniform(size=(batch_size, 3)),\n",
57+
"}\n",
58+
"print(\"Shapes:\", {k: v.shape for k, v in data.items()})"
59+
]
60+
},
61+
{
62+
"cell_type": "markdown",
63+
"id": "823b183c-a993-451f-b3a9-1908694a6448",
64+
"metadata": {},
65+
"source": [
66+
"Next, we create an {py:class}`~bayesflow.adapters.Adapter` to convert it into the desired format (assuming we want to use a summary network later on)."
67+
]
68+
},
69+
{
70+
"cell_type": "code",
71+
"execution_count": 5,
72+
"id": "bd217c66-a748-455d-8cbd-03e74405bc86",
73+
"metadata": {},
74+
"outputs": [
75+
{
76+
"name": "stdout",
77+
"output_type": "stream",
78+
"text": [
79+
"Adapter([0: ConvertDType -> 1: Concatenate(['theta_1', 'theta_2'] -> 'inference_variables') -> 2: Rename('x' -> 'summary_variables')])\n"
80+
]
81+
}
82+
],
83+
"source": [
84+
"adapter = (\n",
85+
" bf.Adapter()\n",
86+
" .convert_dtype(\"float64\", \"float32\")\n",
87+
" .concatenate([\"theta_1\", \"theta_2\"], into=\"inference_variables\")\n",
88+
" .rename(\"x\", \"summary_variables\")\n",
89+
")\n",
90+
"\n",
91+
"print(adapter)"
92+
]
93+
},
94+
{
95+
"cell_type": "markdown",
96+
"id": "2616f412-db48-49e6-a876-89e95b435472",
97+
"metadata": {},
98+
"source": [
99+
"When we now apply the adapter to our data, it executes the specified transformations:"
100+
]
101+
},
102+
{
103+
"cell_type": "code",
104+
"execution_count": 7,
105+
"id": "9da822ba-bc14-4945-8eb5-db5b26eb8a3b",
106+
"metadata": {},
107+
"outputs": [
108+
{
109+
"name": "stdout",
110+
"output_type": "stream",
111+
"text": [
112+
"{'inference_variables': array([[0., 1.],\n",
113+
" [0., 1.]], dtype=float32), 'summary_variables': array([[0.9944578 , 0.38200974, 0.827148 ],\n",
114+
" [0.8372553 , 0.97580904, 0.07722503]], dtype=float32)}\n",
115+
"Shapes: {'inference_variables': (2, 2), 'summary_variables': (2, 3)}\n"
116+
]
117+
}
118+
],
119+
"source": [
120+
"transformed_data = adapter(data)\n",
121+
"print(transformed_data)\n",
122+
"print(\"Shapes:\", {k: v.shape for k, v in transformed_data.items()})"
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"id": "58def124-c41c-4059-b1ee-21319043ad06",
128+
"metadata": {},
129+
"source": [
130+
"Many of the transforms in the adapter are invertible, so that we can also call the adapter in the inverse direction:"
131+
]
132+
},
133+
{
134+
"cell_type": "code",
135+
"execution_count": 15,
136+
"id": "963df7dd-e641-44e7-86fa-3d0444556b95",
137+
"metadata": {},
138+
"outputs": [
139+
{
140+
"name": "stdout",
141+
"output_type": "stream",
142+
"text": [
143+
"Shapes: {'x': (2, 3), 'theta_1': (2, 1), 'theta_2': (2, 1)}\n"
144+
]
145+
}
146+
],
147+
"source": [
148+
"cycled_data = adapter(transformed_data, inverse=True)\n",
149+
"print(\"Shapes:\", {k: v.shape for k, v in cycled_data.items()})"
150+
]
151+
},
152+
{
153+
"cell_type": "markdown",
154+
"id": "352acf17-7880-4b24-8358-c7f66b405159",
155+
"metadata": {},
156+
"source": [
157+
"### Example: Likelihood Estimation\n",
158+
"\n",
159+
"For likelihood estimation, the roles are switched. We want to estimate the distribution of the data `x` conditional on the parameters `theta_1` and `theta_2`. We supply the parameters to the inference network directly without a summary network."
160+
]
161+
},
162+
{
163+
"cell_type": "code",
164+
"execution_count": 16,
165+
"id": "af55755f-200e-436d-9e06-ba26761ae859",
166+
"metadata": {},
167+
"outputs": [
168+
{
169+
"name": "stdout",
170+
"output_type": "stream",
171+
"text": [
172+
"Adapter([0: ConvertDType -> 1: Concatenate(['theta_1', 'theta_2'] -> 'inference_conditions') -> 2: Rename('x' -> 'inference_variables')])\n",
173+
"Shapes: {'inference_conditions': (2, 2), 'inference_variables': (2, 3)}\n"
174+
]
175+
}
176+
],
177+
"source": [
178+
"adapter = (\n",
179+
" bf.Adapter()\n",
180+
" .convert_dtype(\"float64\", \"float32\")\n",
181+
" .concatenate([\"theta_1\", \"theta_2\"], into=\"inference_conditions\")\n",
182+
" .rename(\"x\", \"inference_variables\")\n",
183+
")\n",
184+
"\n",
185+
"print(adapter)\n",
186+
"transformed_data = adapter(data)\n",
187+
"print(\"Shapes:\", {k: v.shape for k, v in transformed_data.items()})"
188+
]
189+
},
190+
{
191+
"cell_type": "markdown",
192+
"id": "f88a14b1-7b18-4d44-a5f6-8ca7a54dda7f",
193+
"metadata": {},
194+
"source": [
195+
"You can find many more configurations in the {doc}`../../examples` section."
196+
]
197+
},
198+
{
199+
"cell_type": "markdown",
200+
"id": "16ba9fa3-6ad6-476d-afbd-13e260ea56b0",
201+
"metadata": {},
202+
"source": [
203+
"## Pre-processing"
204+
]
205+
},
206+
{
207+
"cell_type": "markdown",
208+
"id": "06f0f749-32fb-42a7-b56e-12ca0e396abb",
209+
"metadata": {},
210+
"source": [
211+
"Besides the structure and the data types, there are pre-processing steps that can make network training more efficient. Those include standardization, transforming constrained variables to an unconstrained space, or various non-linear transformations that simply the space the network has to operate in. In addition, operations on arrays like broadcasting and concatenating simplify the transformation into the required structure.\n",
212+
"\n",
213+
"The {py:class}`~bayesflow.adapters.Adapter` features a large set of methods, please refer to the API documentation for a complete list. For applied examples, refer to the {doc}`../../examples` section."
214+
]
215+
}
216+
],
217+
"metadata": {
218+
"kernelspec": {
219+
"display_name": "Python 3 (ipykernel)",
220+
"language": "python",
221+
"name": "python3"
222+
},
223+
"language_info": {
224+
"codemirror_mode": {
225+
"name": "ipython",
226+
"version": 3
227+
},
228+
"file_extension": ".py",
229+
"mimetype": "text/x-python",
230+
"name": "python",
231+
"nbconvert_exporter": "python",
232+
"pygments_lexer": "ipython3",
233+
"version": "3.11.11"
234+
}
235+
},
236+
"nbformat": 4,
237+
"nbformat_minor": 5
238+
}

‎docsrc/source/user_guide/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,5 @@ If you want to contribute, feel free to open an issue or a pull request, we welc
1111
1212
introduction
1313
generative_models.ipynb
14+
data_processing.ipynb
1415
```

0 commit comments

Comments
 (0)