Skip to content

chronulus.prediction

Prediction

A class representing the output of a prediction request

Parameters:

Name Type Description Default
_id str

Unique identifier for the prediction.

 required

Attributes:

Name Type Description
_id str

Unique identifier for the prediction.
Source code in src/chronulus/prediction.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class Prediction:
    """
    A class representing the output of a prediction request

    Parameters
    ----------
    _id : str
        Unique identifier for the prediction.

    Attributes
    ----------
    _id : str
        Unique identifier for the prediction.

    """

    def __init__(self, _id: str):
        self._id = _id

    @property
    def id(self) -> str:
        """Get the unique identifier for the prediction"""
        return self._id

id property

Get the unique identifier for the prediction

Forecast

Bases: Prediction

A class representing the output of a prediction request, containing both numerical results and explanatory text.

This class encapsulates the prediction results returned from the chronulus API, including a unique identifier, descriptive text, and the numerical predictions in a pandas DataFrame format.

Parameters:

Name Type Description Default
_id str

Unique identifier for the prediction.

 required
text str

Descriptive text or notes explaining the prediction results.

 required
data dict

JSON-Split formatted dictionary containing the prediction results.

 required

Attributes:

Name Type Description
_id str

Unique identifier for the prediction.
_text str

Explanatory text describing the prediction results.
_data dict

JSON-Split formatted dictionary containing the prediction results.
Source code in src/chronulus/prediction.py 
 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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class Forecast(Prediction):
    """
    A class representing the output of a prediction request, containing both numerical results and explanatory text.

    This class encapsulates the prediction results returned from the chronulus API,
    including a unique identifier, descriptive text, and the numerical predictions in
    a pandas DataFrame format.

    Parameters
    ----------
    _id : str
        Unique identifier for the prediction.
    text : str
        Descriptive text or notes explaining the prediction results.
    data : dict
        JSON-Split formatted dictionary containing the prediction results.

    Attributes
    ----------
    _id : str
        Unique identifier for the prediction.
    _text : str
        Explanatory text describing the prediction results.
    _data : dict
        JSON-Split formatted dictionary containing the prediction results.

    """

    def __init__(self, _id: str, text: str, data: dict):
        super().__init__(_id)
        self._text = text
        self._data = data

    @property
    def data(self) -> dict:
        """Get the forecast data after the transformation defined by this forecast"""
        return self._transform_data(self._data)

    @property
    def text(self) -> str:
        """Get the forecast explanation after the transformation defined by this forecast"""
        return self._transform_text(self._text)

    def _transform_data(self, data: dict) -> dict:
        """Hook for transforming the forecast data"""
        return data

    def _transform_text(self, text: str) -> str:
        """Hook for transforming the forecast text"""
        return text

    def to_json(self, orient='columns'):
        """
        Convert the forecast data to JSON format with specified orientation.

        Parameters
        ----------
        orient : str, optional
            Data orientation for the JSON output. Options are:

            - 'split': Original JSON-split format
            - 'rows': List of dictionaries, each representing a row
            - 'columns': Dictionary of lists, each representing a column
            Default is 'columns'.

        Returns
        -------
        dict or list
            Forecast data in the specified JSON format:

            - For 'split': Original JSON-split dictionary
            - For 'rows': List of row dictionaries
            - For 'columns': Dictionary of column arrays

        Examples
        --------
        >>> # Get data in columns format
        >>> json_cols = forecast.to_json(orient='columns')
        >>> # Get data in rows format
        >>> json_rows = forecast.to_json(orient='rows')
        """

        if orient == 'split':
            return self.data

        elif orient == 'rows':
            columns = self.data.get('columns')
            rows = list()
            for row in self.data.get('data'):
                _row = {columns[j]: val for j, val in enumerate(row)}
                rows.append(_row)
            return rows

        else:
            col_names = self.data.get('columns')
            columns = {k: list() for k in col_names}

            for row in self.data.get('data'):
                for j, val in enumerate(row):
                    columns[col_names[j]].append(val)

            return columns

    def to_pandas(self):
        """
        Convert the forecast data to a pandas DataFrame.

        The first column is automatically set as the index of the resulting DataFrame.
        Typically, this is a timestamp or date column.

        Returns
        -------
        pandas.DataFrame
            DataFrame containing the forecast data with the first column as index.

        Raises
        ------
        ImportError
            If pandas is not installed in the environment.

        Examples
        --------
        >>> df = forecast.to_pandas()
        >>> print(df.head())
                   y_hat
        date
        2025-01-01   .12345
        2025-01-02   .67890
        """
        if not PANDAS_AVAILABLE:

            message = """pandas is not installed but his method requires pandas. Please install pandas using `pip install pandas` and then try again."""
            raise ImportError(message)

        else:
            json_str = json.dumps(self.data)
            df = pd.read_json(StringIO(json_str), orient='split')
            return df.set_index(self.data.get('columns')[0], drop=True)

data property

Get the forecast data after the transformation defined by this forecast

text property

Get the forecast explanation after the transformation defined by this forecast

to_json(orient='columns')

Convert the forecast data to JSON format with specified orientation.

Parameters:

Name Type Description Default
orient str

Data orientation for the JSON output. Options are:

  • 'split': Original JSON-split format
  • 'rows': List of dictionaries, each representing a row
  • 'columns': Dictionary of lists, each representing a column Default is 'columns'.
 'columns'

Returns:

Type Description
dict or list

Forecast data in the specified JSON format:

  • For 'split': Original JSON-split dictionary
  • For 'rows': List of row dictionaries
  • For 'columns': Dictionary of column arrays

Examples:

>>> # Get data in columns format
>>> json_cols = forecast.to_json(orient='columns')
>>> # Get data in rows format
>>> json_rows = forecast.to_json(orient='rows')
Source code in src/chronulus/prediction.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def to_json(self, orient='columns'):
    """
    Convert the forecast data to JSON format with specified orientation.

    Parameters
    ----------
    orient : str, optional
        Data orientation for the JSON output. Options are:

        - 'split': Original JSON-split format
        - 'rows': List of dictionaries, each representing a row
        - 'columns': Dictionary of lists, each representing a column
        Default is 'columns'.

    Returns
    -------
    dict or list
        Forecast data in the specified JSON format:

        - For 'split': Original JSON-split dictionary
        - For 'rows': List of row dictionaries
        - For 'columns': Dictionary of column arrays

    Examples
    --------
    >>> # Get data in columns format
    >>> json_cols = forecast.to_json(orient='columns')
    >>> # Get data in rows format
    >>> json_rows = forecast.to_json(orient='rows')
    """

    if orient == 'split':
        return self.data

    elif orient == 'rows':
        columns = self.data.get('columns')
        rows = list()
        for row in self.data.get('data'):
            _row = {columns[j]: val for j, val in enumerate(row)}
            rows.append(_row)
        return rows

    else:
        col_names = self.data.get('columns')
        columns = {k: list() for k in col_names}

        for row in self.data.get('data'):
            for j, val in enumerate(row):
                columns[col_names[j]].append(val)

        return columns

to_pandas()

Convert the forecast data to a pandas DataFrame.

The first column is automatically set as the index of the resulting DataFrame. Typically, this is a timestamp or date column.

Returns:

Type Description
DataFrame

DataFrame containing the forecast data with the first column as index.

Raises:

Type Description
ImportError

If pandas is not installed in the environment.

Examples:

>>> df = forecast.to_pandas()
>>> print(df.head())
           y_hat
date
2025-01-01   .12345
2025-01-02   .67890
Source code in src/chronulus/prediction.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
def to_pandas(self):
    """
    Convert the forecast data to a pandas DataFrame.

    The first column is automatically set as the index of the resulting DataFrame.
    Typically, this is a timestamp or date column.

    Returns
    -------
    pandas.DataFrame
        DataFrame containing the forecast data with the first column as index.

    Raises
    ------
    ImportError
        If pandas is not installed in the environment.

    Examples
    --------
    >>> df = forecast.to_pandas()
    >>> print(df.head())
               y_hat
    date
    2025-01-01   .12345
    2025-01-02   .67890
    """
    if not PANDAS_AVAILABLE:

        message = """pandas is not installed but his method requires pandas. Please install pandas using `pip install pandas` and then try again."""
        raise ImportError(message)

    else:
        json_str = json.dumps(self.data)
        df = pd.read_json(StringIO(json_str), orient='split')
        return df.set_index(self.data.get('columns')[0], drop=True)

NormalizedForecast

Bases: Forecast

A class representing the output of a NormalizedForecast prediction request, containing both numerical results and explanatory text.

This class provides methods for operating on normalized forecast data.

Parameters:

Name Type Description Default
_id str

Unique identifier for the prediction.

 required
text str

Descriptive text or notes explaining the prediction results.

 required
data dict

JSON-Split formatted dictionary containing the prediction results.

 required
y_min float

The minimum value of the source scale.

 0.0
y_max float

The maximum value of the source scale

 1.0
Source code in src/chronulus/prediction.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
class NormalizedForecast(Forecast):
    """
    A class representing the output of a NormalizedForecast prediction request, containing both numerical results and explanatory text.

    This class provides methods for operating on normalized forecast data.

    Parameters
    ----------
    _id : str
        Unique identifier for the prediction.
    text : str
        Descriptive text or notes explaining the prediction results.
    data : dict
        JSON-Split formatted dictionary containing the prediction results.
    y_min : float
        The minimum value of the source scale.
    y_max : float
        The maximum value of the source scale
    """

    def __init__(self, _id: str, text: str, data: dict, y_min: float = 0.0, y_max: float = 1.0):
        super().__init__(_id, text, data)
        self.y_min = y_min
        self.y_max = y_max

    def to_rescaled_forecast(self, y_min: float = 0.0, y_max: float = 1.0, invert_scale: bool = False):
        """
        Create a RescaledForecast instance from  NormalizedForecast object.

        This static method allows conversion from a generic Forecast to a RescaledForecast,
        applying the specified scaling parameters.

        Parameters
        ----------
        y_min : float, default 0.0
            The minimum value of the target scale.
        y_max : float, default 1.0
            The maximum value of the target scale.
        invert_scale : bool, default False
            Whether to invert the scale before rescaling.

        Returns
        -------
        RescaledForecast
            A new RescaledForecast instance containing the rescaled data.
        """
        return RescaledForecast(
            _id=self.id,
            data=self.data,
            text=self.text,
            y_min=y_min,
            y_max=y_max,
            invert_scale=invert_scale
        )

to_rescaled_forecast(y_min=0.0, y_max=1.0, invert_scale=False)

Create a RescaledForecast instance from NormalizedForecast object.

This static method allows conversion from a generic Forecast to a RescaledForecast, applying the specified scaling parameters.

Parameters:

Name Type Description Default
y_min float

The minimum value of the target scale.

 0.0
y_max float

The maximum value of the target scale.

 1.0
invert_scale bool

Whether to invert the scale before rescaling.

 False

Returns:

Type Description
RescaledForecast

A new RescaledForecast instance containing the rescaled data.
Source code in src/chronulus/prediction.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
def to_rescaled_forecast(self, y_min: float = 0.0, y_max: float = 1.0, invert_scale: bool = False):
    """
    Create a RescaledForecast instance from  NormalizedForecast object.

    This static method allows conversion from a generic Forecast to a RescaledForecast,
    applying the specified scaling parameters.

    Parameters
    ----------
    y_min : float, default 0.0
        The minimum value of the target scale.
    y_max : float, default 1.0
        The maximum value of the target scale.
    invert_scale : bool, default False
        Whether to invert the scale before rescaling.

    Returns
    -------
    RescaledForecast
        A new RescaledForecast instance containing the rescaled data.
    """
    return RescaledForecast(
        _id=self.id,
        data=self.data,
        text=self.text,
        y_min=y_min,
        y_max=y_max,
        invert_scale=invert_scale
    )

RescaledForecast

Bases: Forecast

A class representing a RescaledForecast prediction

This class provides methods for rescaling (denormalizing) a Forecast.

Parameters:

Name Type Description Default
_id str

Unique identifier for the prediction.

 required
text str

Descriptive text or notes explaining the prediction results.

 required
data dict

JSON-Split formatted dictionary containing the prediction results.

 required
y_min float

The minimum value of the source scale.

 0.0
y_max float

The maximum value of the source scale

 1.0
invert_scale bool

Should we invert the scale before rescaling?

 False
Source code in src/chronulus/prediction.py 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
class RescaledForecast(Forecast):
    """
    A class representing a RescaledForecast prediction

    This class provides methods for rescaling (denormalizing) a Forecast.

    Parameters
    ----------
    _id : str
        Unique identifier for the prediction.
    text : str
        Descriptive text or notes explaining the prediction results.
    data : dict
        JSON-Split formatted dictionary containing the prediction results.
    y_min : float
        The minimum value of the source scale.
    y_max : float
        The maximum value of the source scale
    invert_scale : bool
        Should we invert the scale before rescaling?
    """

    def __init__(self, _id: str, text: str, data: dict, y_min: float = 0.0, y_max: float = 1.0,
                 invert_scale: bool = False):
        super().__init__(_id, text, data)
        self.y_min = y_min
        self.y_max = y_max
        self.invert_scale = invert_scale

    def _transform_data(self, data: dict) -> dict:
        # data should be in split format
        # we should create types for this instead of assuming
        new_data = deepcopy(data)
        json_data = new_data.get("data")
        for i, (ds, y_hat) in enumerate(json_data):
            yhat = 1 - y_hat if self.invert_scale else y_hat
            yhat = yhat * (self.y_max - self.y_min) + self.y_min
            json_data[i][1] = yhat

        new_data['data'] = json_data

        return new_data

    @staticmethod
    def from_forecast(forecast: Forecast, y_min: float = 0.0, y_max: float = 1.0, invert_scale: bool = False):
        """
        Convert the normalized forecast to a rescaled forecast with specified scale parameters.

        This method creates a new RescaledForecast instance using the current forecast's data,
        allowing you to specify the target range and whether to invert the scale.

        Parameters
        ----------
        y_min : float, default 0.0
            The minimum value of the target scale.
        y_max : float, default 1.0
            The maximum value of the target scale.
        invert_scale : bool, default False
            Whether to invert the scale before rescaling.

        Returns
        -------
        RescaledForecast
            A new forecast instance with values rescaled to the specified range.
        """

        return RescaledForecast(
            _id=forecast.id,
            data=forecast.data,
            text=forecast.text,
            y_min=y_min,
            y_max=y_max,
            invert_scale=invert_scale
        )

from_forecast(forecast, y_min=0.0, y_max=1.0, invert_scale=False) staticmethod

Convert the normalized forecast to a rescaled forecast with specified scale parameters.

This method creates a new RescaledForecast instance using the current forecast's data, allowing you to specify the target range and whether to invert the scale.

Parameters:

Name Type Description Default
y_min float

The minimum value of the target scale.

 0.0
y_max float

The maximum value of the target scale.

 1.0
invert_scale bool

Whether to invert the scale before rescaling.

 False

Returns:

Type Description
RescaledForecast

A new forecast instance with values rescaled to the specified range.
Source code in src/chronulus/prediction.py 
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
@staticmethod
def from_forecast(forecast: Forecast, y_min: float = 0.0, y_max: float = 1.0, invert_scale: bool = False):
    """
    Convert the normalized forecast to a rescaled forecast with specified scale parameters.

    This method creates a new RescaledForecast instance using the current forecast's data,
    allowing you to specify the target range and whether to invert the scale.

    Parameters
    ----------
    y_min : float, default 0.0
        The minimum value of the target scale.
    y_max : float, default 1.0
        The maximum value of the target scale.
    invert_scale : bool, default False
        Whether to invert the scale before rescaling.

    Returns
    -------
    RescaledForecast
        A new forecast instance with values rescaled to the specified range.
    """

    return RescaledForecast(
        _id=forecast.id,
        data=forecast.data,
        text=forecast.text,
        y_min=y_min,
        y_max=y_max,
        invert_scale=invert_scale
    )

BetaParams

Bases: BaseModel

Collection of alpha and beta parameters for a Beta distribution.

The intuition for alpha and beta is simple. Consider the batting average of a baseball player. Alpha represents the number of hits the player records over a period of time. Beta represents the number of at-bats without a hit. Together, the batting average of the player over that period of time is alpha / (alpha + beta), which is exactly the mean of the Beta distribution. Also, as the player accumulates more at-bats, we become more and more confident of their true batting average.

Parameters:

Name Type Description Default
alpha float

The shape parameter of successes

 required
beta float

The shape parameter of failures

 required

Attributes:

Name Type Description
alpha float

The shape parameter of successes
beta float

The shape parameter of failures
Source code in src/chronulus/prediction.py 
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
class BetaParams(BaseModel):
    """Collection of alpha and beta parameters for a Beta distribution.

    The intuition for alpha and beta is simple. Consider the batting average of a baseball player. Alpha represents
    the number of hits the player records over a period of time. Beta represents the number of at-bats without a hit.
    Together, the batting average of the player over that period of time is alpha / (alpha + beta), which is exactly
    the mean of the Beta distribution. Also, as the player accumulates more at-bats, we become more and more confident
    of their true batting average.

    Parameters
    ----------
    alpha : float
        The shape parameter of successes
    beta : float
        The shape parameter of failures


    Attributes
    ----------
    alpha : float
        The shape parameter of successes
    beta : float
        The shape parameter of failures
    """

    alpha: float
    beta: float

ExpertOpinion

Bases: BaseModel

The opinion of an expert agent consulted by BinaryPredictor

Parameters:

Name Type Description Default
prob_a

The probability estimated or implied by complementation

 required
question

The reframed question that the agent considered during estimation

 required
notes

The text explanation justifying the expert's estimate

 required
beta_params BetaParams

The alpha and beta parameters for the Beta distribution over the opinion

 required

Attributes:

Name Type Description
prob_a float

The probability estimated or implied by complementation
question str

The reframed question that the agent considered during estimation
notes str

The text explanation justifying the expert's estimate
beta_params BetaParams

The alpha and beta parameters for the Beta distribution over the opinion
Source code in src/chronulus/prediction.py 
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
class ExpertOpinion(BaseModel):
    """The opinion of an expert agent consulted by BinaryPredictor

    Parameters
    ----------
    prob_a: float
        The probability estimated or implied by complementation
    question: str
        The reframed question that the agent considered during estimation
    notes: str
        The text explanation justifying the expert's estimate
    beta_params : BetaParams
        The alpha and beta parameters for the Beta distribution over the opinion


    Attributes
    ----------
    prob_a: float
        The probability estimated or implied by complementation
    question: str
        The reframed question that the agent considered during estimation
    notes: str
        The text explanation justifying the expert's estimate
    beta_params : BetaParams
        The alpha and beta parameters for the Beta distribution over the opinion

    """
    prob_a: float
    question: str
    notes: str
    negative: bool = False
    beta_params: Optional[BetaParams] = None
    _prob_a: Optional[float] = None

    def model_post_init(self, __context: Any) -> None:
        self._prob_a = self.prob_a
        if self.beta_params is not None:
            self.prob_a = self.beta_params.alpha / (self.beta_params.alpha + self.beta_params.beta)

    @property
    def prob(self):
        """Gets the estimated probability and its complement."""
        return self.prob_a, 1 - self.prob_a

    @property
    def text(self):
        """Gets the text representation of the expert opinion"""
        sections = [
            "[Negative]" if self.negative else "[Positive]",
            "Q: " + self.question,
            f"Pred: ({self.prob_a * 100:2.2f}%{'' if self.negative else '*'}, {(1 - self.prob_a) * 100:2.2f}%{'*' if self.negative else ''})",
            "A: " + self.notes,
        ]
        return "\n\n".join(sections)

prob property

Gets the estimated probability and its complement.

text property

Gets the text representation of the expert opinion

BinaryPair

Bases: BaseModel

A pair of ExpertOpinions produced independently by the same expert agent

Each agent consider the question posed by the user from the original perspective as well as its complementary one. Considering both perspectives mitigates framing bias and improves the consistency of the probability estimate.

Parameters:

Name Type Description Default
positive

The expert opinion of expert under the user's original perspective.

 required
negative

The expert opinion of expert from the perspective complementary to the user's original perspective.

 required
beta_params BetaParams

The alpha and beta parameters for the consensus Beta distribution over both opinions

 required

Attributes:

Name Type Description
positive ExpertOpinion

The expert opinion of expert under the user's original perspective.
negative ExpertOpinion

The expert opinion of expert from the perspective complementary to the user's original perspective.
beta_params BetaParams

The alpha and beta parameters for the consensus Beta distribution over both opinions
Source code in src/chronulus/prediction.py 
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
class BinaryPair(BaseModel):
    """A pair of ExpertOpinions produced independently by the same expert agent

    Each agent consider the question posed by the user from the original perspective as well as its complementary one.
    Considering both perspectives mitigates framing bias and improves the consistency of the probability estimate.

    Parameters
    ----------
    positive: ExpertOpinion
        The expert opinion of expert under the user's original perspective.
    negative: ExpertOpinion
        The expert opinion of expert from the perspective complementary to the user's original perspective.
    beta_params : BetaParams
        The alpha and beta parameters for the consensus Beta distribution over both opinions

    Attributes
    ----------
    positive: ExpertOpinion
        The expert opinion of expert under the user's original perspective.
    negative: ExpertOpinion
        The expert opinion of expert from the perspective complementary to the user's original perspective.
    beta_params : BetaParams
        The alpha and beta parameters for the consensus Beta distribution over both opinions

    """
    positive: ExpertOpinion
    negative: ExpertOpinion
    beta_params: Optional[BetaParams] = None

    def model_post_init(self, __context: Any) -> None:
        self.negative.negative = True

    @property
    def prob_a(self):
        """Get the consensus probability of the expert opinion pair."""
        if self.beta_params is None:
            return (self.positive.prob_a + self.negative.prob_a) / 2
        else:
            return self.beta_params.alpha / (self.beta_params.alpha + self.beta_params.beta)

    @property
    def prob(self):
        """Get the consensus probability and its complement over the expert opinion pair."""
        return self.prob_a, 1 - self.prob_a

    @property
    def text(self):
        """Gets the text representation of the pair of expert opinions"""
        return "\n\n".join([self.positive.text, self.negative.text])

prob_a property

Get the consensus probability of the expert opinion pair.

prob property

Get the consensus probability and its complement over the expert opinion pair.

text property

Gets the text representation of the pair of expert opinions

BinaryPrediction

Bases: Prediction

A class representing the output of a prediction request, containing both numerical results and explanatory text.

This class encapsulates the prediction results returned from the chronulus API, including a unique identifier, descriptive text, and the numerical predictions in a pandas DataFrame format.

Parameters:

Name Type Description Default
_id str

Unique identifier for the prediction.

 required
opinion_set BinaryPair

A set of opinions provided by the expert

 required

Attributes:

Name Type Description
_id str

Unique identifier for the prediction.
Source code in src/chronulus/prediction.py 
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
class BinaryPrediction(Prediction):
    """A class representing the output of a prediction request, containing both numerical results and explanatory text.

    This class encapsulates the prediction results returned from the chronulus API,
    including a unique identifier, descriptive text, and the numerical predictions in
    a pandas DataFrame format.

    Parameters
    ----------
    _id : str
        Unique identifier for the prediction.
    opinion_set : BinaryPair
        A set of opinions provided by the expert

    Attributes
    ----------
    _id : str
        Unique identifier for the prediction.

    """

    def __init__(self, _id: str, opinion_set: BinaryPair):
        super().__init__(_id)
        self._opinion_set = opinion_set

    @property
    def opinion_set(self) -> BinaryPair:
        """Gets the set of opinions provided by the expert."""
        return self._opinion_set

    @property
    def prob_a(self):
        """Get the consensus probability of the expert opinion set."""
        return self.opinion_set.prob_a

    @property
    def prob(self):
        """Get the consensus probability and its complement over the expert opinion set."""
        return self.prob_a, 1 - self.prob_a

    @property
    def text(self) -> str:
        """Get the text representation of the expert opinion set."""
        return self.opinion_set.text

    def to_dict(self):
        """Convert the prediction to a python dict

        Returns
        -------
        dict
            A python dict containing the prediction results.
        """

        return self.opinion_set.model_dump()

opinion_set property

Gets the set of opinions provided by the expert.

prob_a property

Get the consensus probability of the expert opinion set.

prob property

Get the consensus probability and its complement over the expert opinion set.

text property

Get the text representation of the expert opinion set.

to_dict()

Convert the prediction to a python dict

Returns:

Type Description
dict

A python dict containing the prediction results.
Source code in src/chronulus/prediction.py 
517
518
519
520
521
522
523
524
525
526
def to_dict(self):
    """Convert the prediction to a python dict

    Returns
    -------
    dict
        A python dict containing the prediction results.
    """

    return self.opinion_set.model_dump()

BinaryPredictionSet

A collection of BinaryPrediction results from BinaryPredictor

The class provides access to aggregate functions over the collection predictions, including access to the Beta distribution estimated over the underlying predictions.

Parameters:

Name Type Description Default
predictions List[BinaryPrediction]

The list of BinaryPredictions for each expert

 required
beta_params BetaParams

The alpha and beta parameters for the Beta distribution

 required
Source code in src/chronulus/prediction.py 
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
class BinaryPredictionSet:
    """
    A collection of BinaryPrediction results from BinaryPredictor

    The class provides access to aggregate functions over the collection predictions, including access to the
    Beta distribution estimated over the underlying predictions.

    Parameters
    ----------
    predictions : List[BinaryPrediction]
        The list of BinaryPredictions for each expert
    beta_params : BetaParams
        The alpha and beta parameters for the Beta distribution

    """

    def __init__(self, predictions: List[BinaryPrediction], beta_params: BetaParams):
        self.predictions = predictions
        self.beta_params = beta_params
        self.id_map = {p.id: i for i, p in enumerate(predictions)}

    @property
    def text(self):
        experts = []
        for i, pred in enumerate(self.predictions):
            expert = "\n\n".join([
                f"--- Expert {i + 1} ---",
                pred.text,
            ])
            experts.append(expert)
        return "\n\n".join(experts)

    def __len__(self):
        return len(self.predictions)

    @property
    def prob_a(self):
        alpha, beta = self.beta_params.alpha, self.beta_params.beta
        return alpha / (alpha + beta)

    @property
    def prob(self):
        return self.prob_a, 1 - self.prob_a

    def __getitem__(self, idx: Union[str, int,]):
        if isinstance(idx, str):
            return self.predictions[self.id_map[idx]]
        elif isinstance(idx, int):
            return self.predictions[idx]

    def __str__(self):
        return self.text

    def to_dict(self):
        """Convert the prediction set to a python dict

        Returns
        -------
        dict
            A python dict containing the prediction set results.
        """

        ps_dict = dict(
            predictions=[p.to_dict() for p in self.predictions],
            beta_params=self.beta_params.model_dump(),
            prob_a=self.prob_a,
            prob=self.prob,
        )

        return ps_dict

to_dict()

Convert the prediction set to a python dict

Returns:

Type Description
dict

A python dict containing the prediction set results.
Source code in src/chronulus/prediction.py 
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
def to_dict(self):
    """Convert the prediction set to a python dict

    Returns
    -------
    dict
        A python dict containing the prediction set results.
    """

    ps_dict = dict(
        predictions=[p.to_dict() for p in self.predictions],
        beta_params=self.beta_params.model_dump(),
        prob_a=self.prob_a,
        prob=self.prob,
    )

    return ps_dict