From 0350eb79f2fed0fef9f880bce43c73ab20c370ac Mon Sep 17 00:00:00 2001 From: hjoaquim Date: Thu, 25 Jan 2024 14:27:57 +0000 Subject: [PATCH] reviewed readme --- .../obbject_extensions/charting/README.md | 79 ++++++++++++------- .../charting/openbb_charting/__init__.py | 4 +- .../openbb_charting/charting_router.py | 12 --- .../charting/tests/test_charting.py | 2 +- 4 files changed, 53 insertions(+), 44 deletions(-) diff --git a/openbb_platform/obbject_extensions/charting/README.md b/openbb_platform/obbject_extensions/charting/README.md index f5fa06f1012..9a8bc6541dd 100644 --- a/openbb_platform/obbject_extensions/charting/README.md +++ b/openbb_platform/obbject_extensions/charting/README.md @@ -8,6 +8,9 @@ The library includes: - a set of charting components - prebuilt charts for a set of commands that are built-in OpenBB extensions +>[!NOTE] +> The charting library is in fact an [`OBBject` extension](https://docs.openbb.co/platform/development/developer-guidelines/obbject_extensions) which means you'll have the functionality it exposes on every command result. + ## Installation To install the extension, run the following command in this folder: @@ -52,43 +55,31 @@ equity_data.show() > Note: The `show()` method currently works either in a Jupyter Notebook or in a standalone python script with a PyWry based backend properly initialized. -## Add a visualization to an existing Platform command +Alternatively, you can use the fact that the `openbb-charting` is an `OBBject` extension and use its available methods. -One should first ensure that the already implemented endpoint is available in the [charting router](/openbb_platform/extensions/charting/openbb_charting/charting_router.py). +```python +from openbb import obb +res = obb.equity.price.historical("AAPL") +res.charting.show() +``` -To do so, you can run: - `python openbb_platform/extensions/charting/openbb_charting/builder.py` - which will read all the available endpoints and add them to the charting router. +The above code will produce the same effect as the previous example. -Afterwards, you'll need to add the visualization to the [charting router](/openbb_platform/extensions/charting/openbb_charting/charting_router.py). The convention to match the endpoint with the respective charting function is the following: +### Discovering available charts -- `/equity/price/historical` -> `equity_price_historical` -- `/technical/ema` -> `technical_ema` +Not all the endpoints are currently supported by the charting extension. To discover which endpoints are supported, you can run the following command: -When you spot the charting function on the charting router file, you can add the visualization to it. +```python +from openbb_charting import Charting +Charting.functions() +``` -The implementation should leverage the already existing classes and methods to do so, namely: - -- `OpenBBFigure` -- `OpenBBFigureTable` -- `PlotlyTA` - -Note that the return of each charting function should respect the already defined return types: `Tuple[OpenBBFigure, Dict[str, Any]]`. - -The returned tuple contains a `OpenBBFigure` that is an interactive plotly figure which can be used in a Python interpreter, and a `Dict[str, Any]` that contains the raw data leveraged by the API. - -After you're done implementing the charting function, you can use either the Python interface or the API to get the chart. To do so, you'll only need to set the already available `chart` argument to `True`. - -### Using the `to_chart` OBBject method - -The `OBBject` is the custom OpenBB object that is returned by the Platform commands. -It implements a set of `to_` functions that enable the user to easily transform the data into a different format. +### Using the `to_chart` method The `to_chart` function should be taken as an advanced feature, as it requires the user to have a good understanding of the charting extension and the `OpenBBFigure` class. The user can use any number of `**kwargs` that will be passed to the `PlotlyTA` class in order to build custom visualizations with custom indicators and similar. -Refer to the [`to_chart` implementation](openbb_charting/core/to_chart.py) for further details. - > Note that, this method will only work to some limited extent with data that is not standardized. > Also, it is currently designed only to handle time series (OHLCV) data. @@ -110,7 +101,7 @@ Example usage: stoch=dict(length=14), ema=dict(length=[20,30,50]), ) - res.to_chart(**{"indicators": indicators}) + res.charting.to_chart(**{"indicators": indicators}) ``` @@ -118,7 +109,37 @@ Example usage: ```python - from openbb_charting.core.plotly_ta.data_classes import ChartIndicators - ChartIndicators.get_available_indicators() + # if you have a command result already + res.charting.indicators + + # or if you want to know in standalone fashion + from openbb_charting import Charting + Charting.indicators() ``` + +## Add a visualization to an existing Platform command + +One should first ensure that the already implemented endpoint is available in the [charting router](/openbb_platform/obbject_extensions/charting/openbb_charting/charting_router.py). + +To do so, you can run: + `python openbb_platform/obbject_extensions/charting/openbb_charting/builder.py` - which will read all the available endpoints and add them to the charting router. + +Afterwards, you'll need to add the visualization to the [charting router]. The convention to match the endpoint with the respective charting function is the following: + +- `/equity/price/historical` -> `equity_price_historical` +- `/technical/ema` -> `technical_ema` + +When you spot the charting function on the charting router file, you can add the visualization to it. + +The implementation should leverage the already existing classes and methods to do so, namely: + +- `OpenBBFigure` +- `PlotlyTA` + +Note that the return of each charting function should respect the already defined return types: `Tuple[OpenBBFigure, Dict[str, Any]]`. + +The returned tuple contains a `OpenBBFigure` that is an interactive plotly figure which can be used in a Python interpreter, and a `Dict[str, Any]` that contains the raw data leveraged by the API. + +After you're done implementing the charting function, you can use either the Python interface or the API to get the chart. To do so, you'll only need to set the already available `chart` argument to `True`. +Or accessing the `charting` attribute of the `OBBject` object: `my_obbject.charting.show()`. diff --git a/openbb_platform/obbject_extensions/charting/openbb_charting/__init__.py b/openbb_platform/obbject_extensions/charting/openbb_charting/__init__.py index 8088504e377..32c359eb820 100644 --- a/openbb_platform/obbject_extensions/charting/openbb_charting/__init__.py +++ b/openbb_platform/obbject_extensions/charting/openbb_charting/__init__.py @@ -44,8 +44,8 @@ class Charting: ) self._handle_backend() - @property - def indicators(self): + @classmethod + def indicators(cls): """Returns a list of the available indicators.""" return ChartIndicators.get_available_indicators() diff --git a/openbb_platform/obbject_extensions/charting/openbb_charting/charting_router.py b/openbb_platform/obbject_extensions/charting/openbb_charting/charting_router.py index 1033a106332..7c038550f52 100644 --- a/openbb_platform/obbject_extensions/charting/openbb_charting/charting_router.py +++ b/openbb_platform/obbject_extensions/charting/openbb_charting/charting_router.py @@ -173,15 +173,3 @@ def technical_ema(**kwargs) -> Tuple["OpenBBFigure", Dict[str, Any]]: """Exponential moving average chart.""" ma_type = "ema" return _ta_ma(ma_type, **kwargs) - - -# def equity_fundamental_multiples(**kwargs) -> Tuple["OpenBBFigure", Dict[str, Any]]: -# """Equity multiples chart.""" -# data = basemodel_to_df(kwargs["obbject_item"], index=kwargs.get("index", "date")) -# standard_params = kwargs["standard_params"].__dict__ -# columnwidth = standard_params.get("columnwidth", None) - -# tbl_fig = OpenBBFigureTable(tabular_data=data, columnwidth=columnwidth) -# content = tbl_fig.to_table().show(external=True).to_plotly_json() - -# return tbl_fig, content diff --git a/openbb_platform/obbject_extensions/charting/tests/test_charting.py b/openbb_platform/obbject_extensions/charting/tests/test_charting.py index 100f9eb0293..5bf517f40d6 100644 --- a/openbb_platform/obbject_extensions/charting/tests/test_charting.py +++ b/openbb_platform/obbject_extensions/charting/tests/test_charting.py @@ -45,7 +45,7 @@ def test_indicators(mock_get_available_indicators, obbject): obj = Charting(obbject) # Act - result = obj.indicators + result = obj.indicators() # Assert assert result == ["indicator1", "indicator2", "indicator3"]