mosqlient 2.5.2__tar.gz → 2.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mosqlient-2.7.0/PKG-INFO +293 -0
- mosqlient-2.7.0/README.md +247 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/__init__.py +1 -1
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_utils/brasil.py +2 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_climate_get_impl.py +17 -3
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_episcanner_get_impl.py +14 -6
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_infodengue_get_impl.py +13 -5
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_mosquito_get_impl.py +14 -3
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_vegetation_get_impl.py +8 -1
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/models.py +23 -6
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/schema.py +27 -8
- mosqlient-2.7.0/mosqlient/forecast/__init__.py +4 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/forecast/baseline.py +33 -109
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/forecast/ensemble.py +3 -3
- mosqlient-2.7.0/mosqlient/forecast/lstm.py +1434 -0
- mosqlient-2.7.0/mosqlient/forecast/viz.py +389 -0
- mosqlient-2.7.0/mosqlient/forecast/xgb.py +412 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_model_get_impl.py +8 -5
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_get_impl.py +46 -8
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_post_impl.py +14 -5
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_validate_impl.py +14 -5
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/models.py +10 -3
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/schema.py +13 -5
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/scoring/score.py +8 -8
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/types.py +3 -1
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/validations.py +48 -16
- {mosqlient-2.5.2 → mosqlient-2.7.0}/pyproject.toml +11 -5
- mosqlient-2.5.2/PKG-INFO +0 -69
- mosqlient-2.5.2/README.md +0 -28
- mosqlient-2.5.2/mosqlient/forecast/__init__.py +0 -2
- mosqlient-2.5.2/mosqlient/forecast/viz.py +0 -155
- {mosqlient-2.5.2 → mosqlient-2.7.0}/LICENSE +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/__main__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_config/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_config/globals.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_utils/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/cli.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/client.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/errors.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/prediction_optimize/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/prediction_optimize/pred_opt.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_delete_impl.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_patch_impl.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/scoring/__init__.py +0 -0
- {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/tests/__init__.py +0 -0
mosqlient-2.7.0/PKG-INFO
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mosqlient
|
|
3
|
+
Version: 2.7.0
|
|
4
|
+
Summary: client library for the mosqlimate client library
|
|
5
|
+
License: GPLv3
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Keywords: data science,epidemiology,forecasting
|
|
8
|
+
Author: Flávio Codeço Coelho
|
|
9
|
+
Author-email: fccoelho@gmail.com
|
|
10
|
+
Requires-Python: >=3.10,<3.15
|
|
11
|
+
Classifier: License :: Other/Proprietary License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Provides-Extra: analyze
|
|
19
|
+
Requires-Dist: aiohttp (>=3.9.5,<4.0.0)
|
|
20
|
+
Requires-Dist: altair (>=5.3.0,<6.0.0) ; extra == "analyze"
|
|
21
|
+
Requires-Dist: cffi (>=1.17.0,<2.0.0)
|
|
22
|
+
Requires-Dist: epiweeks (>=2.3.0,<3.0.0)
|
|
23
|
+
Requires-Dist: loguru (>=0.7.3,<0.8.0)
|
|
24
|
+
Requires-Dist: matplotlib (>=3.9.0,<4.0.0) ; extra == "analyze"
|
|
25
|
+
Requires-Dist: nest-asyncio (>=1.6.0,<2.0.0)
|
|
26
|
+
Requires-Dist: numpy (>=2.2.5)
|
|
27
|
+
Requires-Dist: pandas (>=2.2.2,<3.0.0)
|
|
28
|
+
Requires-Dist: pandas-stubs (>=2.3.3,<2.4.0)
|
|
29
|
+
Requires-Dist: pmdarima (>=2.0.4,<3.0.0) ; extra == "analyze"
|
|
30
|
+
Requires-Dist: pydantic (>=2.7.3,<3.0.0)
|
|
31
|
+
Requires-Dist: requests (>=2.32.2,<3.0.0)
|
|
32
|
+
Requires-Dist: scikit-learn ; extra == "analyze"
|
|
33
|
+
Requires-Dist: scipy ; extra == "analyze"
|
|
34
|
+
Requires-Dist: scoringrules ; extra == "analyze"
|
|
35
|
+
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
|
|
36
|
+
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
|
|
37
|
+
Requires-Dist: torch (>=2.13.0,<3.0.0) ; extra == "analyze"
|
|
38
|
+
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
|
|
39
|
+
Requires-Dist: types-requests (>=2.32.0.20240523,<3.0.0.0)
|
|
40
|
+
Requires-Dist: vl-convert-python (>=1.7.0,<2.0.0)
|
|
41
|
+
Requires-Dist: xgboost (>=2.0.0,<3.0.0) ; extra == "analyze"
|
|
42
|
+
Project-URL: Homepage, https://github.com/Mosqlimate-project/mosqlimate-client
|
|
43
|
+
Project-URL: Repository, https://github.com/Mosqlimate-project/mosqlimate-client
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
# Mosqlimate client
|
|
47
|
+
|
|
48
|
+
[](https://github.com/Mosqlimate-project/mosqlimate-client/actions?query=workflow%3Aci)
|
|
49
|
+
[](https://api.mosqlimate.org/docs/)
|
|
50
|
+
[](https://pypi.org/project/mosqlient)
|
|
51
|
+
[](https://gitter.im/mosqlimate-client/community)
|
|
52
|
+
[](https://github.com/psf/black)
|
|
53
|
+
[](https://api.epidbot.kwar-ai.com.br)
|
|
54
|
+
|
|
55
|
+
Client library for the [Mosqlimate](https://api.mosqlimate.org/) data platform — an open platform for epidemiological forecasting of arboviruses (dengue, zika, chikungunya) in Brazil. It provides access to epidemiological and climate data, a model registry, forecasting tools, and scoring utilities.
|
|
56
|
+
|
|
57
|
+
## Requirements
|
|
58
|
+
|
|
59
|
+
Python 3.10 or above.
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install mosqlient
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
For forecasting and scoring features (ARIMA baseline model, ensemble model, scoring metrics, visualization):
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install "mosqlient[analyze]"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Authentication
|
|
74
|
+
|
|
75
|
+
All API calls require an API key in the format `username:uuid`. Create an account on the [Mosqlimate platform](https://api.mosqlimate.org/) to obtain your key.
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import os
|
|
79
|
+
from dotenv import load_dotenv
|
|
80
|
+
|
|
81
|
+
load_dotenv()
|
|
82
|
+
api_key = os.getenv("API_KEY") # e.g. "myuser:550e8400-e29b-41d4-a716-446655440000"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Tutorial
|
|
86
|
+
|
|
87
|
+
### 1. Fetching epidemiological data
|
|
88
|
+
|
|
89
|
+
Query InfoDengue data for a specific city (geocode) or an entire state (UF):
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
import mosqlient
|
|
93
|
+
|
|
94
|
+
# Dengue cases for Rio de Janeiro city (geocode=3304557)
|
|
95
|
+
df = mosqlient.get_infodengue(
|
|
96
|
+
api_key=api_key,
|
|
97
|
+
disease="A90", # ICD-10 code for dengue
|
|
98
|
+
start_date="2010-01-01",
|
|
99
|
+
end_date="2023-12-31",
|
|
100
|
+
geocode=3304557,
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
# All cities in Paraná state
|
|
104
|
+
df_pr = mosqlient.get_infodengue(
|
|
105
|
+
api_key=api_key,
|
|
106
|
+
disease="A90",
|
|
107
|
+
start_date="2022-01-01",
|
|
108
|
+
end_date="2023-01-01",
|
|
109
|
+
uf="PR",
|
|
110
|
+
)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The returned DataFrame includes columns such as `data_iniSE` (epidemiological week start date), `SE` (week number), `casos` (reported cases), `casos_est` (estimated cases), `p_inc100k` (incidence per 100k), temperature, humidity, and more.
|
|
114
|
+
|
|
115
|
+
### 2. Fetching climate data
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
df_climate = mosqlient.get_climate(
|
|
119
|
+
api_key=api_key,
|
|
120
|
+
start_date="2022-01-01",
|
|
121
|
+
end_date="2023-01-01",
|
|
122
|
+
geocode=4108304, # Curitiba
|
|
123
|
+
)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### 3. Model registry
|
|
127
|
+
|
|
128
|
+
Browse and search forecast models registered on the platform. Model registration is done through the [Mosqlimate platform](https://api.mosqlimate.org/) (not via API).
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
from mosqlient import get_all_models, get_models
|
|
132
|
+
|
|
133
|
+
# List all registered models
|
|
134
|
+
all_models = get_all_models(api_key)
|
|
135
|
+
|
|
136
|
+
# Search with filters
|
|
137
|
+
imdc_2024_models = get_models(api_key, imdc_year=2024)
|
|
138
|
+
dengue_models = get_models(api_key, disease="A90", adm_level=1)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Disease codes use ICD-10 format: `"A90"` (Dengue), `"A92.0"` (Chikungunya), `"A92.5"` (Zika).
|
|
142
|
+
|
|
143
|
+
**Upload predictions:**
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
from mosqlient import upload_prediction
|
|
147
|
+
|
|
148
|
+
prediction_data = [
|
|
149
|
+
{
|
|
150
|
+
"date": "2024-10-06",
|
|
151
|
+
"lower_95": 500, "lower_50": 1200, "pred": 1491,
|
|
152
|
+
"upper_50": 1800, "upper_95": 4000,
|
|
153
|
+
},
|
|
154
|
+
# ... must contain all weeks in the date range without gaps
|
|
155
|
+
]
|
|
156
|
+
|
|
157
|
+
upload_prediction(
|
|
158
|
+
api_key=api_key,
|
|
159
|
+
repository="username/repository", # format: owner/repo_name
|
|
160
|
+
disease="A90",
|
|
161
|
+
description="Out-of-sample forecast for Rio de Janeiro",
|
|
162
|
+
commit="abc123",
|
|
163
|
+
adm_level=2,
|
|
164
|
+
case_definition="probable",
|
|
165
|
+
adm_0="BRA",
|
|
166
|
+
adm_2=3304557, # geocode for Rio de Janeiro
|
|
167
|
+
prediction=prediction_data,
|
|
168
|
+
)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
For IMDC submissions, prediction data must contain all weeks in the date range without gaps:
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
import pandas as pd
|
|
175
|
+
from epiweeks import Week
|
|
176
|
+
|
|
177
|
+
# Generate all required weeks for an IMDC submission
|
|
178
|
+
prediction_data = pd.date_range(
|
|
179
|
+
start=Week(2023, 41).startdate(), # Year-1 week 41
|
|
180
|
+
end=Week(2024, 40).startdate(), # Current year week 40
|
|
181
|
+
freq="W-SUN",
|
|
182
|
+
).to_frame(name="date")
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### 4. Building a baseline ARIMA forecast
|
|
186
|
+
|
|
187
|
+
*Requires `mosqlient[analyze]`.*
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
import pandas as pd
|
|
191
|
+
from datetime import date
|
|
192
|
+
from mosqlient.datastore import Infodengue
|
|
193
|
+
from mosqlient.forecast import Arima
|
|
194
|
+
|
|
195
|
+
# Load and prepare data
|
|
196
|
+
df = Infodengue.get(
|
|
197
|
+
api_key=api_key,
|
|
198
|
+
disease="A90",
|
|
199
|
+
start="2010-01-01",
|
|
200
|
+
end=date.today().strftime("%Y-%m-%d"),
|
|
201
|
+
geocode=3304557,
|
|
202
|
+
)
|
|
203
|
+
df = pd.DataFrame(df)
|
|
204
|
+
df["data_iniSE"] = pd.to_datetime(df["data_iniSE"])
|
|
205
|
+
df.set_index("data_iniSE", inplace=True)
|
|
206
|
+
df = df[["casos"]].rename(columns={"casos": "y"})
|
|
207
|
+
df = df.resample("W-SUN").sum()
|
|
208
|
+
|
|
209
|
+
# Train ARIMA model
|
|
210
|
+
model = Arima(df=df)
|
|
211
|
+
model.train(train_ini_date="2010-01-01", train_end_date="2021-12-31")
|
|
212
|
+
|
|
213
|
+
# In-sample predictions
|
|
214
|
+
df_in = model.predict_in_sample(plot=True)
|
|
215
|
+
|
|
216
|
+
# Out-of-sample forecast
|
|
217
|
+
df_out = model.forecast(horizon=8, plot=True, last_obs=10)
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### 5. Scoring predictions
|
|
221
|
+
|
|
222
|
+
*Requires `mosqlient[analyze]`.*
|
|
223
|
+
|
|
224
|
+
Compare forecasts against observed data with multiple metrics (MAE, MSE, CRPS, Log Score, Interval Score, WIS):
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
import pandas as pd
|
|
228
|
+
from mosqlient.scoring import Scorer
|
|
229
|
+
|
|
230
|
+
# df_true must have 'date' and 'casos' columns
|
|
231
|
+
scorer = Scorer(
|
|
232
|
+
api_key=api_key,
|
|
233
|
+
df_true=observed_data,
|
|
234
|
+
ids=[77, 78], # prediction IDs from the platform
|
|
235
|
+
dist="log_normal",
|
|
236
|
+
fn_loss="median",
|
|
237
|
+
conf_level=0.90,
|
|
238
|
+
)
|
|
239
|
+
|
|
240
|
+
# Score summary table
|
|
241
|
+
print(scorer.summary)
|
|
242
|
+
|
|
243
|
+
# Filter by date range
|
|
244
|
+
scorer.set_date_range("2022-01-01", "2023-06-25")
|
|
245
|
+
|
|
246
|
+
# Visualize
|
|
247
|
+
scorer.plot_predictions() # observed vs predicted
|
|
248
|
+
scorer.plot_mae() # mean absolute error
|
|
249
|
+
scorer.plot_crps() # CRPS over time
|
|
250
|
+
scorer.plot_wis() # weighted interval score
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### 6. Ensemble model
|
|
254
|
+
|
|
255
|
+
Combine multiple predictions via logarithmic pooling or linear mixture:
|
|
256
|
+
|
|
257
|
+
```python
|
|
258
|
+
from mosqlient.forecast import Ensemble
|
|
259
|
+
from mosqlient.prediction_optimize import get_df_pars
|
|
260
|
+
from mosqlient import get_prediction_by_id
|
|
261
|
+
|
|
262
|
+
# Fetch and parameterize a prediction
|
|
263
|
+
pred = get_prediction_by_id(api_key, id=300).to_dataframe()
|
|
264
|
+
pred_pars = get_df_pars(pred, dist="log_normal", fn_loss="lower")
|
|
265
|
+
|
|
266
|
+
# Create ensemble
|
|
267
|
+
ensemble = Ensemble(
|
|
268
|
+
df=pred_pars,
|
|
269
|
+
order_models=[15, 42, 78],
|
|
270
|
+
mixture="log",
|
|
271
|
+
dist="log_normal",
|
|
272
|
+
)
|
|
273
|
+
|
|
274
|
+
# Optimize weights against observations
|
|
275
|
+
weights = ensemble.compute_weights(df_obs=observed_data, metric="crps")
|
|
276
|
+
|
|
277
|
+
# Generate combined forecast
|
|
278
|
+
ensemble_df = ensemble.apply_ensemble()
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Using from R
|
|
282
|
+
|
|
283
|
+
Despite `mosqlient` being a Python library, it can be used from R via the `reticulate` package. See the example [R Jupyter notebook](docs/tutorials/Using%20Mosqlient%20from%20R.ipynb).
|
|
284
|
+
|
|
285
|
+
## Documentation
|
|
286
|
+
|
|
287
|
+
Full documentation, including detailed API reference and additional tutorials, is available at [api.mosqlimate.org/docs](https://api.mosqlimate.org/docs/).
|
|
288
|
+
|
|
289
|
+
## License
|
|
290
|
+
|
|
291
|
+
This project is licensed under the GPLv3 License — see the [LICENSE](LICENSE) file for details.
|
|
292
|
+
In the examples folder, you can find an [R jupyter notebook](docs/tutorials/Using%20Mosqlient%20from%20R.ipynb) of how to use `mosqlient` from R.
|
|
293
|
+
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Mosqlimate client
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Mosqlimate-project/mosqlimate-client/actions?query=workflow%3Aci)
|
|
4
|
+
[](https://api.mosqlimate.org/docs/)
|
|
5
|
+
[](https://pypi.org/project/mosqlient)
|
|
6
|
+
[](https://gitter.im/mosqlimate-client/community)
|
|
7
|
+
[](https://github.com/psf/black)
|
|
8
|
+
[](https://api.epidbot.kwar-ai.com.br)
|
|
9
|
+
|
|
10
|
+
Client library for the [Mosqlimate](https://api.mosqlimate.org/) data platform — an open platform for epidemiological forecasting of arboviruses (dengue, zika, chikungunya) in Brazil. It provides access to epidemiological and climate data, a model registry, forecasting tools, and scoring utilities.
|
|
11
|
+
|
|
12
|
+
## Requirements
|
|
13
|
+
|
|
14
|
+
Python 3.10 or above.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install mosqlient
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
For forecasting and scoring features (ARIMA baseline model, ensemble model, scoring metrics, visualization):
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install "mosqlient[analyze]"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Authentication
|
|
29
|
+
|
|
30
|
+
All API calls require an API key in the format `username:uuid`. Create an account on the [Mosqlimate platform](https://api.mosqlimate.org/) to obtain your key.
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
import os
|
|
34
|
+
from dotenv import load_dotenv
|
|
35
|
+
|
|
36
|
+
load_dotenv()
|
|
37
|
+
api_key = os.getenv("API_KEY") # e.g. "myuser:550e8400-e29b-41d4-a716-446655440000"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Tutorial
|
|
41
|
+
|
|
42
|
+
### 1. Fetching epidemiological data
|
|
43
|
+
|
|
44
|
+
Query InfoDengue data for a specific city (geocode) or an entire state (UF):
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import mosqlient
|
|
48
|
+
|
|
49
|
+
# Dengue cases for Rio de Janeiro city (geocode=3304557)
|
|
50
|
+
df = mosqlient.get_infodengue(
|
|
51
|
+
api_key=api_key,
|
|
52
|
+
disease="A90", # ICD-10 code for dengue
|
|
53
|
+
start_date="2010-01-01",
|
|
54
|
+
end_date="2023-12-31",
|
|
55
|
+
geocode=3304557,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
# All cities in Paraná state
|
|
59
|
+
df_pr = mosqlient.get_infodengue(
|
|
60
|
+
api_key=api_key,
|
|
61
|
+
disease="A90",
|
|
62
|
+
start_date="2022-01-01",
|
|
63
|
+
end_date="2023-01-01",
|
|
64
|
+
uf="PR",
|
|
65
|
+
)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The returned DataFrame includes columns such as `data_iniSE` (epidemiological week start date), `SE` (week number), `casos` (reported cases), `casos_est` (estimated cases), `p_inc100k` (incidence per 100k), temperature, humidity, and more.
|
|
69
|
+
|
|
70
|
+
### 2. Fetching climate data
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
df_climate = mosqlient.get_climate(
|
|
74
|
+
api_key=api_key,
|
|
75
|
+
start_date="2022-01-01",
|
|
76
|
+
end_date="2023-01-01",
|
|
77
|
+
geocode=4108304, # Curitiba
|
|
78
|
+
)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 3. Model registry
|
|
82
|
+
|
|
83
|
+
Browse and search forecast models registered on the platform. Model registration is done through the [Mosqlimate platform](https://api.mosqlimate.org/) (not via API).
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
from mosqlient import get_all_models, get_models
|
|
87
|
+
|
|
88
|
+
# List all registered models
|
|
89
|
+
all_models = get_all_models(api_key)
|
|
90
|
+
|
|
91
|
+
# Search with filters
|
|
92
|
+
imdc_2024_models = get_models(api_key, imdc_year=2024)
|
|
93
|
+
dengue_models = get_models(api_key, disease="A90", adm_level=1)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Disease codes use ICD-10 format: `"A90"` (Dengue), `"A92.0"` (Chikungunya), `"A92.5"` (Zika).
|
|
97
|
+
|
|
98
|
+
**Upload predictions:**
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from mosqlient import upload_prediction
|
|
102
|
+
|
|
103
|
+
prediction_data = [
|
|
104
|
+
{
|
|
105
|
+
"date": "2024-10-06",
|
|
106
|
+
"lower_95": 500, "lower_50": 1200, "pred": 1491,
|
|
107
|
+
"upper_50": 1800, "upper_95": 4000,
|
|
108
|
+
},
|
|
109
|
+
# ... must contain all weeks in the date range without gaps
|
|
110
|
+
]
|
|
111
|
+
|
|
112
|
+
upload_prediction(
|
|
113
|
+
api_key=api_key,
|
|
114
|
+
repository="username/repository", # format: owner/repo_name
|
|
115
|
+
disease="A90",
|
|
116
|
+
description="Out-of-sample forecast for Rio de Janeiro",
|
|
117
|
+
commit="abc123",
|
|
118
|
+
adm_level=2,
|
|
119
|
+
case_definition="probable",
|
|
120
|
+
adm_0="BRA",
|
|
121
|
+
adm_2=3304557, # geocode for Rio de Janeiro
|
|
122
|
+
prediction=prediction_data,
|
|
123
|
+
)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For IMDC submissions, prediction data must contain all weeks in the date range without gaps:
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
import pandas as pd
|
|
130
|
+
from epiweeks import Week
|
|
131
|
+
|
|
132
|
+
# Generate all required weeks for an IMDC submission
|
|
133
|
+
prediction_data = pd.date_range(
|
|
134
|
+
start=Week(2023, 41).startdate(), # Year-1 week 41
|
|
135
|
+
end=Week(2024, 40).startdate(), # Current year week 40
|
|
136
|
+
freq="W-SUN",
|
|
137
|
+
).to_frame(name="date")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### 4. Building a baseline ARIMA forecast
|
|
141
|
+
|
|
142
|
+
*Requires `mosqlient[analyze]`.*
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
import pandas as pd
|
|
146
|
+
from datetime import date
|
|
147
|
+
from mosqlient.datastore import Infodengue
|
|
148
|
+
from mosqlient.forecast import Arima
|
|
149
|
+
|
|
150
|
+
# Load and prepare data
|
|
151
|
+
df = Infodengue.get(
|
|
152
|
+
api_key=api_key,
|
|
153
|
+
disease="A90",
|
|
154
|
+
start="2010-01-01",
|
|
155
|
+
end=date.today().strftime("%Y-%m-%d"),
|
|
156
|
+
geocode=3304557,
|
|
157
|
+
)
|
|
158
|
+
df = pd.DataFrame(df)
|
|
159
|
+
df["data_iniSE"] = pd.to_datetime(df["data_iniSE"])
|
|
160
|
+
df.set_index("data_iniSE", inplace=True)
|
|
161
|
+
df = df[["casos"]].rename(columns={"casos": "y"})
|
|
162
|
+
df = df.resample("W-SUN").sum()
|
|
163
|
+
|
|
164
|
+
# Train ARIMA model
|
|
165
|
+
model = Arima(df=df)
|
|
166
|
+
model.train(train_ini_date="2010-01-01", train_end_date="2021-12-31")
|
|
167
|
+
|
|
168
|
+
# In-sample predictions
|
|
169
|
+
df_in = model.predict_in_sample(plot=True)
|
|
170
|
+
|
|
171
|
+
# Out-of-sample forecast
|
|
172
|
+
df_out = model.forecast(horizon=8, plot=True, last_obs=10)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### 5. Scoring predictions
|
|
176
|
+
|
|
177
|
+
*Requires `mosqlient[analyze]`.*
|
|
178
|
+
|
|
179
|
+
Compare forecasts against observed data with multiple metrics (MAE, MSE, CRPS, Log Score, Interval Score, WIS):
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
import pandas as pd
|
|
183
|
+
from mosqlient.scoring import Scorer
|
|
184
|
+
|
|
185
|
+
# df_true must have 'date' and 'casos' columns
|
|
186
|
+
scorer = Scorer(
|
|
187
|
+
api_key=api_key,
|
|
188
|
+
df_true=observed_data,
|
|
189
|
+
ids=[77, 78], # prediction IDs from the platform
|
|
190
|
+
dist="log_normal",
|
|
191
|
+
fn_loss="median",
|
|
192
|
+
conf_level=0.90,
|
|
193
|
+
)
|
|
194
|
+
|
|
195
|
+
# Score summary table
|
|
196
|
+
print(scorer.summary)
|
|
197
|
+
|
|
198
|
+
# Filter by date range
|
|
199
|
+
scorer.set_date_range("2022-01-01", "2023-06-25")
|
|
200
|
+
|
|
201
|
+
# Visualize
|
|
202
|
+
scorer.plot_predictions() # observed vs predicted
|
|
203
|
+
scorer.plot_mae() # mean absolute error
|
|
204
|
+
scorer.plot_crps() # CRPS over time
|
|
205
|
+
scorer.plot_wis() # weighted interval score
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### 6. Ensemble model
|
|
209
|
+
|
|
210
|
+
Combine multiple predictions via logarithmic pooling or linear mixture:
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
from mosqlient.forecast import Ensemble
|
|
214
|
+
from mosqlient.prediction_optimize import get_df_pars
|
|
215
|
+
from mosqlient import get_prediction_by_id
|
|
216
|
+
|
|
217
|
+
# Fetch and parameterize a prediction
|
|
218
|
+
pred = get_prediction_by_id(api_key, id=300).to_dataframe()
|
|
219
|
+
pred_pars = get_df_pars(pred, dist="log_normal", fn_loss="lower")
|
|
220
|
+
|
|
221
|
+
# Create ensemble
|
|
222
|
+
ensemble = Ensemble(
|
|
223
|
+
df=pred_pars,
|
|
224
|
+
order_models=[15, 42, 78],
|
|
225
|
+
mixture="log",
|
|
226
|
+
dist="log_normal",
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
# Optimize weights against observations
|
|
230
|
+
weights = ensemble.compute_weights(df_obs=observed_data, metric="crps")
|
|
231
|
+
|
|
232
|
+
# Generate combined forecast
|
|
233
|
+
ensemble_df = ensemble.apply_ensemble()
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Using from R
|
|
237
|
+
|
|
238
|
+
Despite `mosqlient` being a Python library, it can be used from R via the `reticulate` package. See the example [R Jupyter notebook](docs/tutorials/Using%20Mosqlient%20from%20R.ipynb).
|
|
239
|
+
|
|
240
|
+
## Documentation
|
|
241
|
+
|
|
242
|
+
Full documentation, including detailed API reference and additional tutorials, is available at [api.mosqlimate.org/docs](https://api.mosqlimate.org/docs/).
|
|
243
|
+
|
|
244
|
+
## License
|
|
245
|
+
|
|
246
|
+
This project is licensed under the GPLv3 License — see the [LICENSE](LICENSE) file for details.
|
|
247
|
+
In the examples folder, you can find an [R jupyter notebook](docs/tutorials/Using%20Mosqlient%20from%20R.ipynb) of how to use `mosqlient` from R.
|
|
@@ -25,7 +25,7 @@ def get_version() -> str:
|
|
|
25
25
|
try:
|
|
26
26
|
return importlib_metadata.version(__name__)
|
|
27
27
|
except importlib_metadata.PackageNotFoundError: # pragma: no cover
|
|
28
|
-
return "2.
|
|
28
|
+
return "2.7.0" # changed by semantic-release
|
|
29
29
|
|
|
30
30
|
|
|
31
31
|
version: str = get_version()
|
|
@@ -16,6 +16,7 @@ def get_climate(
|
|
|
16
16
|
end_date: date | str = "2024-01-01",
|
|
17
17
|
uf: Optional[types.UF] = None,
|
|
18
18
|
geocode: Optional[int] = None,
|
|
19
|
+
adm_1: Optional[types.ADM1] = None,
|
|
19
20
|
) -> pd.DataFrame:
|
|
20
21
|
"""
|
|
21
22
|
Retrieve historical climate data from the Mosqlimate API for a specific region and date range.
|
|
@@ -29,9 +30,12 @@ def get_climate(
|
|
|
29
30
|
end_date : date or str
|
|
30
31
|
End date of the data range (as a `datetime.date` or ISO format string).
|
|
31
32
|
uf : types.UF, optional
|
|
32
|
-
The Brazilian state abbreviation (e.g., 'SP', 'MG')
|
|
33
|
+
The Brazilian state abbreviation (e.g., 'SP', 'MG') or state IBGE
|
|
34
|
+
code (e.g., 33). If provided and `geocode` is not, filters by state.
|
|
33
35
|
geocode : int, optional
|
|
34
36
|
IBGE geocode of a municipality. If provided, overrides `uf`.
|
|
37
|
+
adm_1 : types.ADM1, optional
|
|
38
|
+
Alias for `uf`. Accepts a state abbreviation or IBGE state code.
|
|
35
39
|
|
|
36
40
|
Returns
|
|
37
41
|
-------
|
|
@@ -53,6 +57,9 @@ def get_climate(
|
|
|
53
57
|
... )
|
|
54
58
|
"""
|
|
55
59
|
|
|
60
|
+
if uf is None:
|
|
61
|
+
uf = adm_1
|
|
62
|
+
|
|
56
63
|
return pd.DataFrame(
|
|
57
64
|
Climate.get(
|
|
58
65
|
api_key=api_key,
|
|
@@ -71,6 +78,7 @@ def get_climate_weekly(
|
|
|
71
78
|
uf: Optional[types.UF] = None,
|
|
72
79
|
geocode: Optional[int] = None,
|
|
73
80
|
macro_health_code: Optional[int] = None,
|
|
81
|
+
adm_1: Optional[types.ADM1] = None,
|
|
74
82
|
) -> pd.DataFrame:
|
|
75
83
|
"""
|
|
76
84
|
Retrieve historical climate data weekly aggregated
|
|
@@ -83,12 +91,15 @@ def get_climate_weekly(
|
|
|
83
91
|
Start epiweek in YYYYWW format (example: 202501).
|
|
84
92
|
end : str
|
|
85
93
|
End epiweek in YYYYWW format (example: 202501).
|
|
86
|
-
uf : str, optional
|
|
87
|
-
The Brazilian state abbreviation (e.g., 'SP', 'MG')
|
|
94
|
+
uf : str or int, optional
|
|
95
|
+
The Brazilian state abbreviation (e.g., 'SP', 'MG') or state IBGE
|
|
96
|
+
code (e.g., 33).
|
|
88
97
|
geocode : int, optional
|
|
89
98
|
IBGE geocode of a municipality.
|
|
90
99
|
macro_health_code : int, optional
|
|
91
100
|
Macro Health IBGE geocode. Example: 1101
|
|
101
|
+
adm_1 : types.ADM1, optional
|
|
102
|
+
Alias for `uf`. Accepts a state abbreviation or IBGE state code.
|
|
92
103
|
|
|
93
104
|
Returns
|
|
94
105
|
-------
|
|
@@ -112,6 +123,9 @@ def get_climate_weekly(
|
|
|
112
123
|
... )
|
|
113
124
|
"""
|
|
114
125
|
|
|
126
|
+
if uf is None:
|
|
127
|
+
uf = adm_1
|
|
128
|
+
|
|
115
129
|
return pd.DataFrame(
|
|
116
130
|
ClimateWeekly.get(
|
|
117
131
|
api_key=api_key,
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
__all__ = ["get_episcanner"]
|
|
2
2
|
|
|
3
3
|
|
|
4
|
-
from typing import Optional
|
|
4
|
+
from typing import Optional
|
|
5
5
|
from datetime import date
|
|
6
6
|
|
|
7
7
|
import pandas as pd
|
|
@@ -12,21 +12,25 @@ from .models import Episcanner
|
|
|
12
12
|
|
|
13
13
|
def get_episcanner(
|
|
14
14
|
api_key: str | None = None,
|
|
15
|
-
uf: types.UF =
|
|
16
|
-
disease:
|
|
15
|
+
uf: Optional[types.UF] = None,
|
|
16
|
+
disease: types.DiseaseName = "dengue",
|
|
17
17
|
year: Optional[int] = date.today().year,
|
|
18
|
+
adm_1: Optional[types.ADM1] = None,
|
|
18
19
|
) -> pd.DataFrame:
|
|
19
20
|
"""
|
|
20
21
|
Parameters
|
|
21
22
|
----------
|
|
22
23
|
api_key : str
|
|
23
24
|
API key used to authenticate with the Mosqlimate service.
|
|
24
|
-
disease : types.
|
|
25
|
-
Default: "dengue".
|
|
25
|
+
disease : types.DiseaseName
|
|
26
|
+
Default: "dengue". Accepts disease names or ICD-10 codes.
|
|
26
27
|
uf : types.UF
|
|
27
|
-
The Brazilian state abbreviation (e.g., 'SP', 'MG')
|
|
28
|
+
The Brazilian state abbreviation (e.g., 'SP', 'MG') or state IBGE
|
|
29
|
+
code (e.g., 33). Defaults to 'RJ'.
|
|
28
30
|
year : int, optional
|
|
29
31
|
Default value is the current year.
|
|
32
|
+
adm_1 : types.ADM1, optional
|
|
33
|
+
Alias for `uf`. Accepts a state abbreviation or IBGE state code.
|
|
30
34
|
|
|
31
35
|
Returns
|
|
32
36
|
-------
|
|
@@ -44,6 +48,10 @@ def get_episcanner(
|
|
|
44
48
|
... )
|
|
45
49
|
"""
|
|
46
50
|
|
|
51
|
+
uf = uf if uf is not None else adm_1
|
|
52
|
+
if uf is None:
|
|
53
|
+
uf = "RJ"
|
|
54
|
+
|
|
47
55
|
return pd.DataFrame(
|
|
48
56
|
Episcanner.get(
|
|
49
57
|
api_key=api_key,
|