Skip to content

Get, post and delete predictions

get_prediction_by_id(api_key, id)

Retrieve one prediction record by its ID.

Source code in mosqlient/registry/_prediction_get_impl.py 
100
101
102
103
def get_prediction_by_id(api_key: str, id: int) -> Prediction | None:
    """Retrieve one prediction record by its ID."""
    res = Prediction.get(api_key=api_key, id=id)
    return res[0] if len(res) == 1 else None

get_predictions(api_key, id=None, model_id=None, model_name=None, model_owner=None, model_organization=None, adm_level=None, model_time_resolution=None, disease=None, model_category=None, imdc_year=None, start=None, end=None)

Retrieve one or more prediction records from the Mosqlimate API.

Parameters

api_key : str API key used to authenticate with the Mosqlimate service. id : int, optional Unique identifier of the prediction. model_id : int, optional Unique identifier of the model. model_name : str, optional Name of the model (repository name). model_owner : str, optional Username of the model owner (e.g. GitHub username). model_organization : str, optional Name of the organization that owns the model. adm_level : int, optional Administrative level (0: national, 1: state, 2: municipality, 3: sub-municipality). model_time_resolution : str, optional Temporal resolution ('day', 'week', 'month', 'year'). disease : str, optional Disease code (e.g., 'A90' for Dengue, 'A92.0' for Chikungunya, 'A92.5' for Zika). model_category : str, optional Category of the model (e.g., 'quantitative', 'spatio_temporal_quantitative'). imdc_year : int, optional The year of the IMDC if the model was part of a competition (e.g., 2024). start : date, optional Filter predictions with data starting on or after this date. end : date, optional Filter predictions with data ending on or before this date.

Returns

List[Prediction] A list of prediction objects matching the filters.

Source code in mosqlient/registry/_prediction_get_impl.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def get_predictions(
    api_key: str,
    id: Optional[int] = None,
    model_id: Optional[int] = None,
    model_name: Optional[str] = None,
    model_owner: Optional[str] = None,
    model_organization: Optional[str] = None,
    adm_level: Optional[int] = None,
    model_time_resolution: Optional[
        Literal["day", "week", "month", "year"]
    ] = None,
    disease: Optional[str] = None,
    model_category: Optional[
        Literal[
            "quantitative",
            "categorical",
            "spatial_quantitative",
            "spatial_categorical",
            "spatio_temporal_quantitative",
            "spatio_temporal_categorical",
        ]
    ] = None,
    imdc_year: Optional[int] = None,
    start: Optional[date] = None,
    end: Optional[date] = None,
) -> List[Prediction]:
    """
    Retrieve one or more prediction records from the Mosqlimate API.

    Parameters
    ----------
    api_key : str
        API key used to authenticate with the Mosqlimate service.
    id : int, optional
        Unique identifier of the prediction.
    model_id : int, optional
        Unique identifier of the model.
    model_name : str, optional
        Name of the model (repository name).
    model_owner : str, optional
        Username of the model owner (e.g. GitHub username).
    model_organization : str, optional
        Name of the organization that owns the model.
    adm_level : int, optional
        Administrative level (0: national, 1: state, 2: municipality, 3: sub-municipality).
    model_time_resolution : str, optional
        Temporal resolution ('day', 'week', 'month', 'year').
    disease : str, optional
        Disease code (e.g., 'A90' for Dengue, 'A92.0' for Chikungunya, 'A92.5' for Zika).
    model_category : str, optional
        Category of the model (e.g., 'quantitative', 'spatio_temporal_quantitative').
    imdc_year : int, optional
        The year of the IMDC if the model was part of a competition (e.g., 2024).
    start : date, optional
        Filter predictions with data starting on or after this date.
    end : date, optional
        Filter predictions with data ending on or before this date.

    Returns
    -------
    List[Prediction]
        A list of prediction objects matching the filters.
    """
    params = {
        "id": id,
        "model_id": model_id,
        "model_name": model_name,
        "model_owner": model_owner,
        "model_organization": model_organization,
        "adm_level": adm_level,
        "model_time_resolution": model_time_resolution,
        "disease": disease,
        "model_category": model_category,
        "imdc_year": imdc_year,
        "start": str(start) if start else None,
        "end": str(end) if end else None,
    }
    return Prediction.get(api_key=api_key, **params)

get_predictions_between(api_key, start, end)

Retrieve predictions where data falls within the date range.

Source code in mosqlient/registry/_prediction_get_impl.py 
157
158
159
160
161
def get_predictions_between(
    api_key: str, start: date, end: date
) -> List[Prediction]:
    """Retrieve predictions where data falls within the date range."""
    return Prediction.get(api_key=api_key, start=str(start), end=str(end))

upload_prediction(api_key, repository, disease, description, commit, prediction, adm_level, case_definition='probable', published=True, adm_0='BRA', adm_1=None, adm_2=None, adm_3=None)

Upload a prediction to the Mosqlimate API.

Parameters

api_key : str API key used to authenticate with the Mosqlimate service. repository : str The repository identifier in the format "owner/repo_name". disease : str The disease code in the IDC-10 format. Example: "A90". description : str Textual description of the prediction run. commit : str Git commit hash associated with the model version. prediction : list of dict or pandas.DataFrame Forecast data. If a DataFrame is provided, it must contain columns matching the prediction schema (date, pred, lower_95, etc.). adm_level : int Administrative level, options: 0, 1, 2, 3 (National, State, Municipality, Sub Municipality) case_definition : str, default="probable" The case definition used (e.g., "probable" or "reported"). published : bool, default=False Whether the prediction should be visible to the public. adm_0 : str, default="BRA" ISO 3166-1 alpha-3 country code. adm_1 : int, optional State-level administrative division geocode. adm_2 : int, optional Municipality-level geocode. adm_3 : int, optional Sub-municipality-level geocode.

Returns

Prediction The created Prediction object.

Source code in mosqlient/registry/_prediction_post_impl.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def upload_prediction(
    api_key: str,
    repository: str,
    disease: str,
    description: str,
    commit: str,
    prediction: Union[List[Dict], pd.DataFrame],
    adm_level: int,
    case_definition: str = "probable",
    published: bool = True,
    adm_0: str = "BRA",
    adm_1: Optional[int] = None,
    adm_2: Optional[int] = None,
    adm_3: Optional[int] = None,
) -> Prediction:
    """
    Upload a prediction to the Mosqlimate API.

    Parameters
    ----------
    api_key : str
        API key used to authenticate with the Mosqlimate service.
    repository : str
        The repository identifier in the format "owner/repo_name".
    disease : str
        The disease code in the IDC-10 format. Example: "A90".
    description : str
        Textual description of the prediction run.
    commit : str
        Git commit hash associated with the model version.
    prediction : list of dict or pandas.DataFrame
        Forecast data. If a DataFrame is provided, it must contain columns matching
        the prediction schema (date, pred, lower_95, etc.).
    adm_level : int
        Administrative level, options: 0, 1, 2, 3 (National, State, Municipality,
        Sub Municipality)
    case_definition : str, default="probable"
        The case definition used (e.g., "probable" or "reported").
    published : bool, default=False
        Whether the prediction should be visible to the public.
    adm_0 : str, default="BRA"
        ISO 3166-1 alpha-3 country code.
    adm_1 : int, optional
        State-level administrative division geocode.
    adm_2 : int, optional
        Municipality-level geocode.
    adm_3 : int, optional
        Sub-municipality-level geocode.

    Returns
    -------
    Prediction
        The created Prediction object.
    """

    prediction_data = []

    if isinstance(prediction, pd.DataFrame):
        df = prediction.copy()
        if "date" in df.columns:
            df["date"] = df["date"].astype(str)

        prediction_data = df.to_dict(orient="records")
    else:
        prediction_data = prediction

    float_fields = [
        "lower_95",
        "lower_90",
        "lower_80",
        "lower_50",
        "pred",
        "upper_50",
        "upper_80",
        "upper_90",
        "upper_95",
    ]

    clean_prediction = []
    for item in prediction_data:
        i: Dict[str, Any] = {"date": str(item["date"])}
        for field in float_fields:
            if field in item and item[field] is not None:
                i[field] = float(item[field])
            else:
                i[field] = None
        clean_prediction.append(i)

    return Prediction.post(
        api_key=api_key,
        repository=repository,
        disease=disease,
        description=description,
        commit=commit,
        case_definition=case_definition,
        published=published,
        adm_level=adm_level,
        adm_0=adm_0,
        adm_1=adm_1,
        adm_2=adm_2,
        adm_3=adm_3,
        prediction=clean_prediction,
    )

delete_prediction(api_key, prediction_id)

Function to delete a prediction registered in the platform. Only the author can remove the prediction.

Parameters

api_key : str
    API key used to authenticate with the Mosqlimate service.
prediction_id : int
    Prediction id.

Returns

request response

Source code in mosqlient/registry/_prediction_delete_impl.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
def delete_prediction(
    api_key: str,
    prediction_id: int,
) -> requests.Response:
    """
    Function to delete a prediction registered in the platform.
    Only the author can remove the prediction.

    Parameters
    ----------
        api_key : str
            API key used to authenticate with the Mosqlimate service.
        prediction_id : int
            Prediction id.

    Returns
    --------
    request response
    """
    return Prediction.delete_by_id(api_key=api_key, id=prediction_id)