Skip to content

chronulus.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 
 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
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
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

    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) -> pd.DataFrame:
        """
        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
        -------
        pd.DataFrame
            DataFrame containing the forecast data with the first column as index.

        Raises
        ------
        UserWarning
            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:
            warnings.warn(
                "pandas is not installed but his method requires pandas."
                "Please install pandas using `pip install pandas` and then try again.",
                UserWarning
            )
        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)

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 
 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
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
UserWarning

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 
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
def to_pandas(self) -> pd.DataFrame:
    """
    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
    -------
    pd.DataFrame
        DataFrame containing the forecast data with the first column as index.

    Raises
    ------
    UserWarning
        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:
        warnings.warn(
            "pandas is not installed but his method requires pandas."
            "Please install pandas using `pip install pandas` and then try again.",
            UserWarning
        )
    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)

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 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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