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.
Files changed (47) hide show
  1. mosqlient-2.7.0/PKG-INFO +293 -0
  2. mosqlient-2.7.0/README.md +247 -0
  3. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/__init__.py +1 -1
  4. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_utils/brasil.py +2 -0
  5. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_climate_get_impl.py +17 -3
  6. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_episcanner_get_impl.py +14 -6
  7. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_infodengue_get_impl.py +13 -5
  8. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_mosquito_get_impl.py +14 -3
  9. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/_vegetation_get_impl.py +8 -1
  10. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/models.py +23 -6
  11. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/schema.py +27 -8
  12. mosqlient-2.7.0/mosqlient/forecast/__init__.py +4 -0
  13. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/forecast/baseline.py +33 -109
  14. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/forecast/ensemble.py +3 -3
  15. mosqlient-2.7.0/mosqlient/forecast/lstm.py +1434 -0
  16. mosqlient-2.7.0/mosqlient/forecast/viz.py +389 -0
  17. mosqlient-2.7.0/mosqlient/forecast/xgb.py +412 -0
  18. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_model_get_impl.py +8 -5
  19. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_get_impl.py +46 -8
  20. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_post_impl.py +14 -5
  21. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_validate_impl.py +14 -5
  22. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/models.py +10 -3
  23. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/schema.py +13 -5
  24. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/scoring/score.py +8 -8
  25. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/types.py +3 -1
  26. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/validations.py +48 -16
  27. {mosqlient-2.5.2 → mosqlient-2.7.0}/pyproject.toml +11 -5
  28. mosqlient-2.5.2/PKG-INFO +0 -69
  29. mosqlient-2.5.2/README.md +0 -28
  30. mosqlient-2.5.2/mosqlient/forecast/__init__.py +0 -2
  31. mosqlient-2.5.2/mosqlient/forecast/viz.py +0 -155
  32. {mosqlient-2.5.2 → mosqlient-2.7.0}/LICENSE +0 -0
  33. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/__main__.py +0 -0
  34. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_config/__init__.py +0 -0
  35. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_config/globals.py +0 -0
  36. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/_utils/__init__.py +0 -0
  37. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/cli.py +0 -0
  38. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/client.py +0 -0
  39. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/datastore/__init__.py +0 -0
  40. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/errors.py +0 -0
  41. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/prediction_optimize/__init__.py +0 -0
  42. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/prediction_optimize/pred_opt.py +0 -0
  43. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/__init__.py +0 -0
  44. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_delete_impl.py +0 -0
  45. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/registry/_prediction_patch_impl.py +0 -0
  46. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/scoring/__init__.py +0 -0
  47. {mosqlient-2.5.2 → mosqlient-2.7.0}/mosqlient/tests/__init__.py +0 -0
@@ -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
+ [![ci](https://github.com/Mosqlimate-project/mosqlimate-client/workflows/ci/badge.svg)](https://github.com/Mosqlimate-project/mosqlimate-client/actions?query=workflow%3Aci)
49
+ [![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://api.mosqlimate.org/docs/)
50
+ [![pypi version](https://img.shields.io/pypi/v/mosqlient.svg)](https://pypi.org/project/mosqlient)
51
+ [![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mosqlimate-client/community)
52
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
53
+ [![EpidBot Ready](https://img.shields.io/badge/EpidBot-Ready-brightgreen?style=flat-square&logo=robot&logoColor=white)](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
+ [![ci](https://github.com/Mosqlimate-project/mosqlimate-client/workflows/ci/badge.svg)](https://github.com/Mosqlimate-project/mosqlimate-client/actions?query=workflow%3Aci)
4
+ [![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)](https://api.mosqlimate.org/docs/)
5
+ [![pypi version](https://img.shields.io/pypi/v/mosqlient.svg)](https://pypi.org/project/mosqlient)
6
+ [![gitter](https://badges.gitter.im/join%20chat.svg)](https://gitter.im/mosqlimate-client/community)
7
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
8
+ [![EpidBot Ready](https://img.shields.io/badge/EpidBot-Ready-brightgreen?style=flat-square&logo=robot&logoColor=white)](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.5.2" # changed by semantic-release
28
+ return "2.7.0" # changed by semantic-release
29
29
 
30
30
 
31
31
  version: str = get_version()
@@ -57,3 +57,5 @@ UF_CODES = {
57
57
  "SP": 35,
58
58
  "TO": 17,
59
59
  }
60
+
61
+ CODE_UFS = {code: uf for uf, code in UF_CODES.items()}
@@ -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'). If provided and `geocode` is not, filters by state.
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, Literal
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 = "RJ",
16
- disease: Literal["dengue", "zika", "chikungunya"] = "dengue",
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.Disease
25
- Default: "dengue". Options: dengue, chikungunya or zika
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,