from typing import Optional, List
from decimal import Decimal
from collections import UserDict
try:
import orjson as json
except ImportError:
try:
import rapidjson as json
except ImportError:
try:
import simplejson as json
except ImportError:
import json
try:
import numpy as np
HAS_NUMPY = True
except ImportError:
HAS_NUMPY = False
from validator_collection import validators, checkers
from highcharts_core import errors, utility_functions, constants
from highcharts_core.options.plot_options.series import SeriesOptions
from highcharts_core.options.series.data.base import DataBase
from highcharts_core.options.series.data.collections import DataPointCollection
[docs]class SeriesBase(SeriesOptions):
"""Generic base class for specific series configurations."""
def __init__(self, **kwargs):
self._data = None
self._id = None
self._index = None
self._legend_index = None
self._name = None
self._stack = None
self._x_axis = None
self._y_axis = None
self._z_index = None
self.data = kwargs.get('data', None)
self.id = kwargs.get('id', None)
self.index = kwargs.get('index', None)
self.legend_index = kwargs.get('legend_index', None)
self.name = kwargs.get('name', None)
self.stack = kwargs.get('stack', None)
self.x_axis = kwargs.get('x_axis', None)
self.y_axis = kwargs.get('y_axis', None)
self.z_index = kwargs.get('z_index', None)
super().__init__(**kwargs)
def __str__(self):
"""Return a human-readable :class:`str <python:str>` representation of the series.
.. warning::
To ensure that the result is human-readable, the string representation
will be generated *without* its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>`
property.
.. tip::
If you would like a *complete* and *unambiguous* :class:`str <python:str>`
representation, then you can:
* use the :meth:`__repr__() <highcharts_core.options.series.base.SeriesBase.__repr__>` method,
* call ``repr(my_series)``, or
* serialize the series to JSON using ``my_series.to_json()``.
:returns: A :class:`str <python:str>` representation of the chart.
:rtype: :class:`str <python:str>`
"""
as_dict = self.to_dict()
kwargs = {utility_functions.to_snake_case(key): as_dict[key]
for key in as_dict if key != 'data'}
kwargs_as_str = ', '.join([f'{key} = {repr(kwargs[key])}'
for key in kwargs])
return f'{self.__class__.__name__}({kwargs_as_str})'
def __getattr__(self, name):
"""Facilitates the retrieval of properties from the series and its underlying data.
The logic is:
1. If the attribute exists on the series object, then return it.
2. If ``.data`` is empty, then return :obj:`None <python:None>`.
3. If ``.data`` contains a
:class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`,
then return the attribute from the collection.
4. Since ``.data`` contains a list of data points, return an iterable
containing the attribute from each data point. If NumPy is available,
return this iterable as a NumPy :class:`ndarray <numpy:numpy.ndarray>`.
:param name: The name of the attribute to retrieve.
:type name: :class:`str <python:str>`
:returns: The value of the attribute.
:raises AttributeError: If ``name`` is not a valid attribute of the data point
class or the instance.
"""
try:
return super().__getattribute__(name)
except AttributeError as error:
if name in ['__iter__', '__next__', 'requires_js_object']:
raise error
pass
if not self.data:
raise AttributeError(name)
if isinstance(self.data, DataPointCollection):
return getattr(self.data, name)
results = [getattr(x, name) for x in self.data]
if HAS_NUMPY:
results = np.asarray(results)
return results
def __setattr__(self, name, value):
"""Updates the series attribute, or descendent attributes on the ``.data``
properties.
"""
try:
super().__setattr__(name, value)
return
except AttributeError:
pass
collection_cls = self._data_collection_class()
data_point_cls = self._data_point_class()
if not utility_functions.is_ndarray(self.data) and not self.data:
if HAS_NUMPY:
collection = collection_cls()
setattr(collection, name, value)
self.data = collection
elif checkers.is_iterable(value, forbid_literals = (str,
bytes,
dict,
UserDict)):
collection = collection_cls()
setattr(collection, name, value)
self.data = collection
else:
data_point = data_point_cls(name = value)
self._data = [data_point]
elif not self.data:
collection = collection_cls()
setattr(collection, name, value)
self.data = collection
elif checkers.is_type(self.data, 'DataPointCollection'):
setattr(self.data, name, value)
else:
if not checkers.is_iterable(value, forbid_literals = (str,
bytes,
dict,
UserDict)):
value = [value for x in self.data]
if len(self.data) > len(value):
value = value + [None for x in range(len(self.data) - len(value))]
elif len(self.data) < len(value):
self.data = self.data + [data_point_cls()
for x in range(len(value) - len(self.data))]
for index in range(len(self.data)):
setattr(self.data[index], name, value[index])
@classmethod
def _data_collection_class(cls):
"""Returns the class object used for the data collection.
:rtype: :class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
descendent
"""
return DataPointCollection
@classmethod
def _data_point_class(cls):
"""Returns the class object used for individual data points.
:rtype: :class:`DataBase <highcharts_core.options.series.data.base.DataBase>`
descendent
"""
return DataBase
@property
def _dot_path(self) -> Optional[str]:
"""The dot-notation path to the options key for the current class.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return f'series.{self.type}'
@property
def data(self) -> Optional[List[DataBase] | DataPointCollection]:
"""The collection of data points for the series. Defaults to
:obj:`None <python:None>`.
:rtype: :class:`DataBase` or
:class:`DataPointCollection <highcharts_core.options.series.data.collections.DataPointCollection>`
or :obj:`None <python:None>`
"""
return self._data
@data.setter
def data(self, value):
if not utility_functions.is_ndarray(value) and not value:
self._data = None
else:
self._data = self._data_point_class().from_array(value)
@property
def id(self) -> Optional[str]:
"""An id for the series. Defaults to :obj:`None <python:None>`.
.. hint::
This can be used (in JavaScript) after render time to get a pointer to the
series object through ``chart.get()``.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._id
@id.setter
def id(self, value):
self._id = validators.string(value, allow_empty = True)
@property
def index(self) -> Optional[int]:
"""The index for the series in the chart, affecting the internal index in the
(JavaScript) ``chart.series`` array, the visible Z-index, and the order of the
series in the legend. Defaults to :obj:`None <python:None>`.
:rtype: :class:`int <python:int>` or :obj:`None <python:None>`
"""
return self._index
@index.setter
def index(self, value):
self._index = validators.integer(value,
allow_empty = True,
minimum = 0)
@property
def legend_index(self) -> Optional[int]:
"""The sequential index for the series in the legend. Defaults to
:obj:`None <python:None>`.
:rtype: :class:`int <python:int>` or :obj:`None <python:None>`
"""
return self._legend_index
@legend_index.setter
def legend_index(self, value):
self._legend_index = validators.integer(value,
allow_empty = True,
minimum = 0)
@property
def name(self) -> Optional[str]:
"""The name of the series as shown in the legend, tooltip, etc. Defaults to
:obj:`None <python:None>`.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._name
@name.setter
def name(self, value):
self._name = validators.string(value, allow_empty = True)
@property
def stack(self) -> Optional[str]:
"""Indicates the "stack" into which the series should be grouped, if the chart
groups series into stacks. Defaults to :obj:`None <python:None>`.
.. note::
The value can be a string or a numeric value, provided that series in the same
stack all have the same value when converted to a string. For ease of ues,
Highcharts for Python will attempt to force the conversion of the relevant value
to a string.
:rtype: :class:`str <python:str>` or :obj:`None <python:None>`
"""
return self._stack
@stack.setter
def stack(self, value):
if not value:
self._stack = None
else:
self._stack = validators.string(value,
coerce_value = True)
@property
def x_axis(self) -> Optional[str | int]:
"""When using multiple X-axes, this setting determines on which axis the series
should be drawn. Its value should be either a numerical index position in the
:meth:`Options.x_axis` array (starting at 0), or a :class:`str <python:str>`
indicating the :meth:`id <XAxis.id>` of the axis to which the series should be
connected. Defaults to :obj:`None <python:None>`, which behaves as if the value
were set to ``0``.
:rtype: :class:`str <python:str>`, :class:`int <python:int>`, or
:obj:`None <python:None>`
"""
return self._x_axis
@x_axis.setter
def x_axis(self, value):
if value is None:
self._x_axis = None
else:
try:
value = validators.integer(value, minimum = 0)
except (ValueError, TypeError):
value = validators.string(value)
self._x_axis = value
@property
def y_axis(self) -> Optional[str | int]:
"""When using multiple Y-axes, this setting determines on which axis the series
should be drawn. Its value should be either a numerical index position in the
:meth:`Options.y_axis` array (starting at 0), or a :class:`str <python:str>`
indicating the :meth:`id <YAxis.id>` of the axis to which the series should be
connected. Defaults to :obj:`None <python:None>`, which behaves as if the value
were set to ``0``.
:rtype: :class:`str <python:str>`, :class:`int <python:int>`, or
:obj:`None <python:None>`
"""
return self._y_axis
@y_axis.setter
def y_axis(self, value):
if value is None:
self._y_axis = None
else:
try:
value = validators.integer(value, minimum = 0)
except (ValueError, TypeError):
value = validators.string(value)
self._y_axis = value
@property
def z_index(self) -> Optional[int | float | Decimal]:
"""The visual z-index of the series. Defaults to :obj:`None <python:None>`.
:rtype: numeric or :obj:`None <python:None>`
"""
return self._z_index
@z_index.setter
def z_index(self, value):
if value is None:
self._z_index = None
else:
self._z_index = validators.numeric(value)
@classmethod
def _get_kwargs_from_dict(cls, as_dict):
kwargs = {
'accessibility': as_dict.get('accessibility', None),
'allow_point_select': as_dict.get('allowPointSelect', None),
'animation': as_dict.get('animation', None),
'class_name': as_dict.get('className', None),
'clip': as_dict.get('clip', None),
'color': as_dict.get('color', None),
'cursor': as_dict.get('cursor', None),
'custom': as_dict.get('custom', None),
'dash_style': as_dict.get('dashStyle', None),
'data_labels': as_dict.get('dataLabels', None),
'description': as_dict.get('description', None),
'enable_mouse_tracking': as_dict.get('enableMouseTracking', None),
'events': as_dict.get('events', None),
'include_in_data_export': as_dict.get('includeInDataExport', None),
'keys': as_dict.get('keys', None),
'label': as_dict.get('label', None),
'legend_symbol': as_dict.get('legendSymbol', None),
'linked_to': as_dict.get('linkedTo', None),
'marker': as_dict.get('marker', None),
'on_point': as_dict.get('onPoint', None),
'opacity': as_dict.get('opacity', None),
'point': as_dict.get('point', None),
'point_description_formatter': as_dict.get('pointDescriptionFormatter', None),
'selected': as_dict.get('selected', None),
'show_checkbox': as_dict.get('showCheckbox', None),
'show_in_legend': as_dict.get('showInLegend', None),
'skip_keyboard_navigation': as_dict.get('skipKeyboardNavigation', None),
'sonification': as_dict.get('sonification', None),
'states': as_dict.get('states', None),
'sticky_tracking': as_dict.get('stickyTracking', None),
'threshold': as_dict.get('threshold', None),
'tooltip': as_dict.get('tooltip', None),
'turbo_threshold': as_dict.get('turboThreshold', None),
'visible': as_dict.get('visible', None),
'animation_limit': as_dict.get('animationLimit', None),
'boost_blending': as_dict.get('boostBlending', None),
'boost_threshold': as_dict.get('boostThreshold', None),
'color_axis': as_dict.get('colorAxis', None),
'color_index': as_dict.get('colorIndex', None),
'color_key': as_dict.get('colorKey', None),
'connect_ends': as_dict.get('connectEnds', None),
'connect_nulls': as_dict.get('connectNulls', None),
'crisp': as_dict.get('crisp', None),
'crop_threshold': as_dict.get('cropThreshold', None),
'data_sorting': as_dict.get('dataSorting', None),
'drag_drop': as_dict.get('dragDrop', None),
'find_nearest_point_by': as_dict.get('findNearestPointBy', None),
'get_extremes_from_all': as_dict.get('getExtremesFromAll', None),
'inactive_other_points': as_dict.get('inactiveOtherPoints', None),
'linecap': as_dict.get('linecap', None),
'line_width': as_dict.get('lineWidth', None),
'negative_color': as_dict.get('negativeColor', None),
'point_description_format': as_dict.get('pointDescriptionFormat', None),
'point_interval': as_dict.get('pointInterval', None),
'point_interval_unit': as_dict.get('pointIntervalUnit', None),
'point_placement': as_dict.get('pointPlacement', None),
'point_start': as_dict.get('pointStart', None),
'relative_x_value': as_dict.get('relativeXValue', None),
'shadow': as_dict.get('shadow', None),
'soft_threshold': as_dict.get('softThreshold', None),
'stacking': as_dict.get('stacking', None),
'step': as_dict.get('step', None),
'zone_axis': as_dict.get('zoneAxis', None),
'zones': as_dict.get('zones', None),
'data': as_dict.get('data', None),
'id': as_dict.get('id', None),
'index': as_dict.get('index', None),
'legend_index': as_dict.get('legendIndex', None),
'name': as_dict.get('name', None),
'stack': as_dict.get('stack', None),
'x_axis': as_dict.get('xAxis', None),
'y_axis': as_dict.get('yAxis', None),
'z_index': as_dict.get('zIndex', None),
}
return kwargs
def _to_untrimmed_dict(self, in_cls = None) -> dict:
untrimmed = {
'data': self.data,
'id': self.id,
'index': self.index,
'legendIndex': self.legend_index,
'name': self.name,
'stack': self.stack,
'xAxis': self.x_axis,
'yAxis': self.y_axis,
'zIndex': self.z_index,
}
parent_as_dict = super()._to_untrimmed_dict(in_cls = in_cls)
for key in parent_as_dict:
untrimmed[key] = parent_as_dict[key]
return untrimmed
[docs] def load_from_array(self, value):
"""Update the :meth:`.data <highcharts_core.options.series.base.SeriesBase.data>`
property with data loaded from an iterable in ``value``.
:param value: The value that should contain the data which will be converted into data
point instances.
.. note::
If ``value`` is not an iterable, it will be converted into an iterable to be
further de-serialized correctly.
:type value: iterable
"""
data_point_cls = self._data_point_class()
self.data = data_point_cls.from_array(value)
[docs] @classmethod
def from_array(cls, value, series_kwargs = None):
"""Create one instance of the series with ``data`` populated from ``value``.
:param value: The value that should contain the data which will be converted into data
point instances.
.. note::
If ``value`` is not an iterable, it will be converted into an iterable to be
further de-serialized correctly.
:type value: iterable
:param series_kwargs: Optional keyword arguments to apply when instanting the
series. Defaults to :obj:`None <python:None>`.
:type series_kwargs: :class:`dict <python:dict>` or :obj:`None <python:None>`
:returns: An instance of the series type with ``data`` populated from the value.
:rtype: :class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`
descendent
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
data_point_cls = cls._data_point_class()
data_points = data_point_cls.from_array(value)
series_kwargs['data'] = data_points
series = cls(**series_kwargs)
return series
[docs] def load_from_csv(self,
as_string_or_file,
property_column_map = None,
has_header_row = True,
delimiter = ',',
null_text = 'None',
wrapper_character = "'",
line_terminator = '\r\n',
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\",
series_in_rows = False,
series_index = True,
**kwargs):
"""Replace the existing
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
with a new value populated from data in a CSV string or file.
.. note::
For an example
:class:`LineSeries <highcharts_core.options.series.area.LineSeries>`, the
minimum code required would be:
.. code-block:: python
my_series = LineSeries()
# EXAMPLE 1. Minimal code - will attempt to update the line series
# taking x-values from the first column, and y-values from
# the second column. If there are too many columns in the CSV,
# will throw an error.
my_series = my_series.from_csv('some-csv-file.csv')
# EXAMPLE 2. More precise code - will attempt to update the line series
# mapping columns in the CSV file to properties on the series
# instance.
my_series = my_series.from_csv('some-csv-file.csv',
property_column_map = {
'x': 0,
'y': 3,
'id': 'id'
})
# EXAMPLE 3. More precise code - will update the line series
# using a specific series generated from the CSV file.
my_series = my_series.from_csv('some-csv-file.csv', series_index = 2)
As the example above shows, data is loaded into the ``my_series`` instance
from the CSV file with a filename ``some-csv-file.csv``. As shown in
EXAMPLE 1, unless otherwise specified, the :meth:`.x <CartesianData.x>`
values for each data point will be taken from the first (index 0) column
in the CSV file, while the :meth:`.y <CartesianData.y>` values will be
taken from the second column.
If the CSV has more than 2 columns, then this will throw an
:exc:`HighchartsCSVDeserializationError` because the function is not certain
which columns to use to update the series. If this happens, you can either:
#. As shown in EXAMPLE 2, precisely specify which columns to use by
providing a ``property_column_map`` argument. In EXAMPLE 2, the
:meth:`.x <CartesianData.x>` values for each data point will be taken
from the first (index 0) column in the CSV file. The
:meth:`.y <CartesianData.y>` values will be taken from the fourth
(index 3) column in the CSV file. And the
:meth:`.id <CartesianData.id>` values will be taken from a column whose
header row is labeled ``'id'`` (regardless of its index).
#. Supply a ``series_index`` argument, which indicates which of the series
generated from the CSV file should be used to update the instance.
:param as_string_or_file: The CSV data to use to pouplate data. Accepts either
the raw CSV data as a :class:`str <python:str>` or a path to a file in the
runtime environment that contains the CSV data.
.. tip::
Unwrapped empty column values are automatically interpreted as null
(:obj:`None <python:None>`).
:type as_string_or_file: :class:`str <python:str>` or Path-like
:param property_column_map: An optional :class:`dict <python:dict>` used to
indicate which data point property should be set to which CSV column. The keys
in the :class:`dict <python:dict>` should correspond to properties in the data
point class, while the value can either be a numerical index (starting with 0)
or a :class:`str <python:str>` indicating the label for the CSV column.
Defaults to :obj:`None <python:None>`.
.. warning::
If the ``property_column_map`` uses :class:`str <python:str>` values, the CSV
file *must* have a header row (this is expected, by default). If there is no
header row and a :class:`str <python:str>` value is found, a
:exc:`HighchartsCSVDeserializationError` will be raised.
:type property_column_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param has_header_row: If ``True``, indicates that the first row of
``as_string_or_file`` contains column labels, rather than actual data. Defaults
to ``True``.
:type has_header_row: :class:`bool <python:bool>`
:param delimiter: The delimiter used between columns. Defaults to ``,``.
:type delimiter: :class:`str <python:str>`
:param wrapper_character: The string used to wrap string values when
wrapping is applied. Defaults to ``'``.
:type wrapper_character: :class:`str <python:str>`
:param null_text: The string used to indicate an empty value if empty
values are wrapped. Defaults to `None`.
:type null_text: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
:type line_terminator: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
.. note::
The Python :mod:`csv <python:csv>` currently ignores the ``line_terminator``
parameter and always applies ``'\\r\\n'``, by design. The Python docs say this
may change in the future, so for future backwards compatibility we are
including it here.
:type line_terminator: :class:`str <python:str>`
:param wrap_all_strings: If ``True``, indicates that the CSV file has all string
data values wrapped in quotation marks. Defaults to ``False``.
.. warning::
If set to ``True``, the :mod:`csv <python:csv>` module will try to coerce any
value that is *not* wrapped in quotation marks to a
:class:`float <python:float>`. This can cause unexpected behavior, and
typically we recommend leaving this as ``False`` and then re-casting values
after they have been parsed.
:type wrap_all_strings: :class:`bool <python:bool>`
:param double_wrapper_character_when_nested: If ``True``, quote character is
doubled when appearing within a string value. If ``False``, the
``escape_character`` is used to prefix quotation marks. Defaults to ``False``.
:type double_wrapper_character_when_nested: :class:`bool <python:bool>`
:param escape_character: A one-character string that indicates the character used
to escape quotation marks if they appear within a string value that is already
wrapped in quotation marks. Defaults to ``\\`` (which is Python for ``'\'``,
which is Python's native escape character).
:type escape_character: :class:`str <python:str>`
:param series_in_rows: if ``True``, will attempt a streamlined cartesian series
with x-values taken from column names, y-values taken from row values, and
the series name taken from the row index. Defaults to
:obj:`False <python:False>`.
:type series_in_rows: :class:`bool <python:bool>`
:param series_index: if :obj:`None <python:None>`, will raise a
:exc:`HighchartsCSVDeserializationError <highcharts_core.errors.HighchartsCSVDeserializationError>`
if the CSV data contains more than one series and no ``property_column_map``
is provided. Otherwise, will update the instance with the series found
in the CSV at the ``series_index`` value. Defaults to
:obj:`None <python:None>`.
:type series_index: :class:`int <python:int>` or :obj:`None <python:None>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:raises HighchartsCSVDeserializationError: if ``property_column_map`` references
CSV columns by their label, but the CSV data does not contain a header row
"""
cls = self.__class__
new_instance = cls.from_csv(
as_string_or_file,
property_column_map = property_column_map,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = wrap_all_strings,
double_wrapper_character_when_nested = double_wrapper_character_when_nested,
escape_character = escape_character,
series_in_rows = series_in_rows,
series_index = series_index,
**kwargs
)
if series_index is None and isinstance(new_instance, list):
raise errors.HighchartsCSVDeserializationError(
f'Expected data for a single series, but got {len(new_instance)} when '
f'loading from CSV. Please either modify the structure of your CSV '
f'or provide more targeted instructions using the property_column_map '
f'argument.'
)
elif isinstance(new_instance, list):
new_instance = new_instance[series_index]
self.data = new_instance.data
@classmethod
def _from_csv_multi_map(cls,
as_string_or_file,
property_column_map = None,
has_header_row = True,
series_kwargs = None,
delimiter = ',',
null_text = 'None',
wrapper_character = "'",
line_terminator = '\r\n',
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\",
series_in_rows = False,
**kwargs):
"""Replace the existing
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
with a new value populated from data in a CSV string or file.
.. note::
For an example
:class:`LineSeries <highcharts_core.options.series.area.LineSeries>`, the
minimum code required would be:
.. code-block:: python
my_series = LineSeries()
my_series = my_series.from_csv('some-csv-file.csv',
property_column_map = {
'x': 0,
'y': 3,
'id': 'id'
})
As the example above shows, data is loaded into the ``my_series`` instance
from the CSV file with a filename ``some-csv-file.csv``. The
:meth:`x <CartesianData.x>`
values for each data point will be taken from the first (index 0) column in
the CSV file. The :meth:`y <CartesianData.y>` values will be taken from the
fourth (index 3) column in the CSV file. And the :meth:`id <CartesianData.id>`
values will be taken from a column whose header row is labeled ``'id'``
(regardless of its index).
:param as_string_or_file: The CSV data to use to pouplate data. Accepts either
the raw CSV data as a :class:`str <python:str>` or a path to a file in the
runtime environment that contains the CSV data.
.. tip::
Unwrapped empty column values are automatically interpreted as null
(:obj:`None <python:None>`).
:type as_string_or_file: :class:`str <python:str>` or Path-like
:param property_column_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which CSV column. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value can either be a numerical index (starting with 0) or a
:class:`str <python:str>` indicating the label for the CSV column. Defaults to
:obj:`None <python:None>`.
.. warning::
If the ``property_column_map`` uses :class:`str <python:str>` values, the CSV
file *must* have a header row (this is expected, by default). If there is no
header row and a :class:`str <python:str>` value is found, a
:exc:`HighchartsCSVDeserializationError` will be raised.
:type property_column_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param has_header_row: If ``True``, indicates that the first row of
``as_string_or_file`` contains column labels, rather than actual data. Defaults
to ``True``.
:type has_header_row: :class:`bool <python:bool>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from the CSV file instead.
:type series_kwargs: :class:`dict <python:dict>`
:param delimiter: The delimiter used between columns. Defaults to ``,``.
:type delimiter: :class:`str <python:str>`
:param wrapper_character: The string used to wrap string values when
wrapping is applied. Defaults to ``'``.
:type wrapper_character: :class:`str <python:str>`
:param null_text: The string used to indicate an empty value if empty
values are wrapped. Defaults to `None`.
:type null_text: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
:type line_terminator: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
.. note::
The Python :mod:`csv <python:csv>` currently ignores the ``line_terminator``
parameter and always applies ``'\\r\\n'``, by design. The Python docs say this
may change in the future, so for future backwards compatibility we are
including it here.
:type line_terminator: :class:`str <python:str>`
:param wrap_all_strings: If ``True``, indicates that the CSV file has all string
data values wrapped in quotation marks. Defaults to ``False``.
.. warning::
If set to ``True``, the :mod:`csv <python:csv>` module will try to coerce any
value that is *not* wrapped in quotation marks to a
:class:`float <python:float>`. This can cause unexpected behavior, and
typically we recommend leaving this as ``False`` and then re-casting values
after they have been parsed.
:type wrap_all_strings: :class:`bool <python:bool>`
:param double_wrapper_character_when_nested: If ``True``, quote character is
doubled when appearing within a string value. If ``False``, the
``escape_character`` is used to prefix quotation marks. Defaults to ``False``.
:type double_wrapper_character_when_nested: :class:`bool <python:bool>`
:param escape_character: A one-character string that indicates the character used
to escape quotation marks if they appear within a string value that is already
wrapped in quotation marks. Defaults to ``\\`` (which is Python for ``'\'``,
which is Python's native escape character).
:type escape_character: :class:`str <python:str>`
:param series_in_rows: if ``True``, will attempt a streamlined cartesian series
with x-values taken from column names, y-values taken from row values, and
the series name taken from the row index. Defaults to
:obj:`False <python:False>`.
:type series_in_rows: :class:`bool <python:bool>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:raises HighchartsCSVDeserializationError: if ``property_column_map`` references
CSV columns by their label, but the CSV data does not contain a header row
"""
try:
as_string_or_file = as_string_or_file.strip()
except AttributeError:
pass
property_column_map = validators.dict(property_column_map,
allow_empty = True) or {}
cleaned_column_map = {}
for key in property_column_map:
map_value = property_column_map.get(key, None)
if map_value is None:
continue
if not isinstance(map_value, int) and not has_header_row:
raise errors.HighchartsCSVDeserializationError(f'The supplied CSV '
f'data does not have a'
f'header row, but the '
f'property_column_map '
f'did not supply an '
f'index. Received: '
f'column name '
f'"{map_value}" '
f'instead.')
cleaned_column_map[key] = map_value
if not checkers.is_on_filesystem(as_string_or_file):
as_str = as_string_or_file
columns, csv_records = utility_functions.parse_csv(
as_str,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
else:
with open(as_string_or_file, 'r', newline = '') as file_:
columns, csv_records = utility_functions.parse_csv(
file_,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
fixed_values = {}
iterable_values = {}
number_of_series = 1
mismatched_series = {}
names = []
for key in cleaned_column_map:
map_value = cleaned_column_map[key]
is_iterable = not isinstance(map_value, (str, bytes, dict, UserDict)) and \
hasattr(map_value, '__iter__')
if is_iterable:
for item in map_value:
if item not in columns:
raise errors.HighchartsCSVDeserializationError(
f'property_column_map is looking for a column labeled '
f'"{item}", but no corresponding column was found.'
)
implied_series = len(map_value)
if number_of_series == 1 and implied_series > number_of_series:
number_of_series = implied_series
elif implied_series != number_of_series:
mismatched_series[key] = implied_series
iterable_values[key] = map_value
if key == 'y':
name_list = [x if isinstance(x, str) else columns[x]
for x in map_value]
names.extend(name_list)
else:
if isinstance(map_value, str) and map_value not in columns:
raise errors.HighchartsCSVDeserializationError(
f'property_column_map is looking for a column labeled '
f'"{map_value}", but no corresponding column was found.'
)
elif map_value not in columns and checkers.is_integer(
map_value,
coerce_value = True
) and int(map_value) > len(columns):
raise errors.HighchartsCSVDeserializationError(
f'property_column_map is looking for a column at index '
f'{map_value}, but no corresponding column was found.'
)
fixed_values[key] = map_value
if key == 'y':
if isinstance(map_value, str):
names.append(map_value)
else:
names.append(columns[map_value])
if mismatched_series:
raise errors.HighchartsCSVDeserializationError(
f'Unable to create series from CSV. The property map implied '
f'multiple series were needed, but properties had mismatched '
f'number of values:\n{mismatched_series}'
)
collections = []
for index in range(number_of_series):
collection_cls = cls._data_collection_class()
collection_instance = collection_cls()
for key in iterable_values:
iterable_value = iterable_values[key][index]
prop_array = [x.get(iterable_value, None) for x in csv_records]
for i, value in enumerate(prop_array):
if value and isinstance(value, str) and ',' in value:
test_value = value.replace(',', '')
if checkers.is_numeric(test_value):
value = test_value
prop_array[i] = value
setattr(collection_instance, key, prop_array)
for key in fixed_values:
fixed_value = fixed_values[key]
prop_array = [x.get(fixed_value, None) for x in csv_records]
for i, value in enumerate(prop_array):
if value and isinstance(value, str) and ',' in value:
test_value = value.replace(',', '')
if checkers.is_numeric(test_value):
value = test_value
prop_array[i] = value
setattr(collection_instance, key, prop_array)
getattr(collection_instance, key, None)
collections.append(collection_instance)
series_list = []
for index in range(number_of_series):
series_kwargs['data'] = collections[index]
series_instance = cls(**series_kwargs)
try:
series_instance.name = names[index]
except IndexError:
pass
for key in kwargs:
if key not in series_kwargs and key not in cleaned_column_map:
setattr(series_instance, key, kwargs[key])
series_list.append(series_instance)
return series_list
[docs] @classmethod
def from_csv(cls,
as_string_or_file,
property_column_map = None,
has_header_row = True,
series_kwargs = None,
delimiter = ',',
null_text = 'None',
wrapper_character = "'",
line_terminator = '\r\n',
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\",
series_in_rows = False,
series_index = None,
**kwargs):
"""Create one or more new :term:`series` instances with
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>`
populated from data in a CSV string or file.
.. note::
For an example
:class:`LineSeries <highcharts_core.options.series.area.LineSeries>`, the
minimum code required would be:
.. code-block:: python
# Create one or more LineSeries instances from the CSV file "some-csv-file.csv".
# EXAMPLE 1. The minimum code to produce one series for each
# column in the CSV file (excluding the first column):
my_series = LineSeries.from_csv('some-csv-file.csv')
# EXAMPLE 2. Produces ONE series with more precise configuration:
my_series = LineSeries.from_csv('some-csv-file.csv',
property_column_map = {
'x': 0,
'y': 3,
'id': 'id'
})
# EXAMPLE 3. Produces THREE series instances with
# more precise configuration:
my_series = LineSeries.from_csv('some-csv-file.csv',
property_column_map = {
'x': 0,
'y': [3, 5, 8],
'id': 'id'
})
As the example above shows, data is loaded into the ``my_series`` instance
from the CSV file with a filename ``some-csv-file.csv``. The
:meth:`x <CartesianData.x>`
values for each data point will be taken from the first (index 0) column in
the CSV file. The :meth:`y <CartesianData.y>` values will be taken from the
fourth (index 3) column in the CSV file. And the :meth:`id <CartesianData.id>`
values will be taken from a column whose header row is labeled ``'id'``
(regardless of its index).
:param as_string_or_file: The CSV data to use to pouplate data. Accepts either
the raw CSV data as a :class:`str <python:str>` or a path to a file in the
runtime environment that contains the CSV data.
.. tip::
Unwrapped empty column values are automatically interpreted as null
(:obj:`None <python:None>`).
:type as_string_or_file: :class:`str <python:str>` or Path-like
:param property_column_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which CSV column. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value can either be a numerical index (starting with 0) or a
:class:`str <python:str>` indicating the label for the CSV column. Defaults to
:obj:`None <python:None>`.
.. note::
If any of the values in ``property_column_map`` contain an iterable, then
one series will be produced for each item in the iterable. For example,
the following:
.. code-block:: python
{
'x': 0,
'y': [3, 5, 8]
}
will return *three* series, each of which will have its
:meth:`.x <CartesianData.x>` value populated from the first column
(index 0), and whose :meth:`.y <CartesianData.y>`
values will be populated from the fourth, sixth, and ninth columns (indices
3, 5, and 8), respectively.
.. warning::
If the ``property_column_map`` uses :class:`str <python:str>` values, the CSV
file *must* have a header row (this is expected, by default). If there is no
header row and a :class:`str <python:str>` value is found, a
:exc:`HighchartsCSVDeserializationError` will be raised.
:type property_column_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param has_header_row: If ``True``, indicates that the first row of
``as_string_or_file`` contains column labels, rather than actual data. Defaults
to ``True``.
:type has_header_row: :class:`bool <python:bool>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from the CSV file instead.
:type series_kwargs: :class:`dict <python:dict>`
:param delimiter: The delimiter used between columns. Defaults to ``,``.
:type delimiter: :class:`str <python:str>`
:param wrapper_character: The string used to wrap string values when
wrapping is applied. Defaults to ``'``.
:type wrapper_character: :class:`str <python:str>`
:param null_text: The string used to indicate an empty value if empty
values are wrapped. Defaults to `None`.
:type null_text: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
:type line_terminator: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
.. note::
The Python :mod:`csv <python:csv>` currently ignores the ``line_terminator``
parameter and always applies ``'\\r\\n'``, by design. The Python docs say this
may change in the future, so for future backwards compatibility we are
including it here.
:type line_terminator: :class:`str <python:str>`
:param wrap_all_strings: If ``True``, indicates that the CSV file has all string
data values wrapped in quotation marks. Defaults to ``False``.
.. warning::
If set to ``True``, the :mod:`csv <python:csv>` module will try to coerce any
value that is *not* wrapped in quotation marks to a
:class:`float <python:float>`. This can cause unexpected behavior, and
typically we recommend leaving this as ``False`` and then re-casting values
after they have been parsed.
:type wrap_all_strings: :class:`bool <python:bool>`
:param double_wrapper_character_when_nested: If ``True``, quote character is
doubled when appearing within a string value. If ``False``, the
``escape_character`` is used to prefix quotation marks. Defaults to ``False``.
:type double_wrapper_character_when_nested: :class:`bool <python:bool>`
:param escape_character: A one-character string that indicates the character used
to escape quotation marks if they appear within a string value that is already
wrapped in quotation marks. Defaults to ``\\\\`` (which is Python for ``'\\'``,
which is Python's native escape character).
:type escape_character: :class:`str <python:str>`
:param series_in_rows: if ``True``, will attempt a streamlined cartesian series
with x-values taken from column names, y-values taken from row values, and
the series name taken from the row index. Defaults to ``False``.
:obj:`False <python:False>`.
:type series_in_rows: :class:`bool <python:bool>`
:param series_index: If supplied, return the series that Highcharts for Python
generated from the CSV at the ``series_index`` position. Defaults to
:obj:`None <python:None>`, which returns all series generated from the CSV.
:type series_index: :class:`int <python:int>`, slice, or
:obj:`None <python:None>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:returns: A :term:`series` instance (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) OR
:class:`list <python:list>` of series instances with its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from the data in ``df``.
:rtype: :class:`list <python:list>` of series instances (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descendent
:raises HighchartsCSVDeserializationError: if ``property_column_map`` references
CSV columns by their label, but the CSV data does not contain a header row
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
if series_in_rows:
return cls.from_csv_in_rows(
as_string_or_file,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = wrap_all_strings,
double_wrapper_character_when_nested = double_wrapper_character_when_nested,
escape_character = escape_character,
series_index = series_index,
**kwargs
)
# SCENARIO 1: Has Property Map
if property_column_map:
series_list = cls._from_csv_multi_map(
as_string_or_file,
property_column_map = property_column_map,
has_header_row = has_header_row,
series_kwargs = series_kwargs,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = wrap_all_strings,
double_wrapper_character_when_nested = double_wrapper_character_when_nested,
escape_character = escape_character,
**kwargs
)
if len(series_list) == 1:
return series_list[0]
return series_list
# SCENARIO 2: Properties in KWARGS
collection_cls = cls._data_collection_class()
data_point_cls = cls._data_point_class()
props_from_array = data_point_cls._get_props_from_array()
if not props_from_array:
props_from_array = ['x', 'y']
property_map = {}
for prop in props_from_array:
if prop in kwargs:
property_map[prop] = kwargs[prop]
if property_map:
series_list = cls._from_csv_multi_map(
as_string_or_file,
property_column_map = property_map,
has_header_row = has_header_row,
series_kwargs = series_kwargs,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = wrap_all_strings,
double_wrapper_character_when_nested = double_wrapper_character_when_nested,
escape_character = escape_character,
**kwargs
)
for index in range(len(series_list)):
for key in kwargs:
if key not in props_from_array and key not in series_kwargs:
setattr(series_list[index], key, kwargs[key])
if len(series_list) == 1:
return series_list[0]
if series_index is not None:
return series_list[index]
return series_list
# SCENARIO 3: No Explicit Properties
if not checkers.is_on_filesystem(as_string_or_file):
as_str = as_string_or_file
columns, csv_records = utility_functions.parse_csv(
as_str,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
else:
with open(as_string_or_file, 'r', newline = '') as file_:
columns, csv_records = utility_functions.parse_csv(
file_,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
try:
series_idx = kwargs.get('index', columns[0])
except IndexError:
series_idx = kwargs.get('index', 0)
column_count = len(columns)
if not columns:
column_count = len(csv_records[0])
supported_dimensions = collection_cls._get_supported_dimensions()
# SCENARIO 3a: Single Series, Data Frame Columns align exactly to Data Point Properties
if column_count in supported_dimensions:
property_map = {}
props_from_array = data_point_cls._get_props_from_array(length = column_count)
if not props_from_array:
props_from_array = ['x', 'y']
property_map[props_from_array[0]] = [x.get(series_idx, None)
for x in csv_records]
for index, prop in enumerate(props_from_array[1:]):
if series_idx is not None:
prop_array = [x.get(columns[index + 1], index + 1)
for x in csv_records]
else:
prop_array = [x.get(columns[index], index)
for x in csv_records]
for i, value in enumerate(prop_array):
if value and isinstance(value, str) and ',' in value:
test_value = value.replace(',', '')
if checkers.is_numeric(test_value):
value = test_value
prop_array[i] = value
property_map[prop] = prop_array
collection = collection_cls()
for key in property_map:
setattr(collection, key, property_map[key])
series_kwargs['data'] = collection
series_instance = cls(**series_kwargs)
for key in kwargs:
if key not in series_kwargs and key not in property_map:
setattr(series_instance, key, kwargs[key])
return series_instance
# SCENARIO 3b: Multiple Series, Data Frame Columns correspond to multiples of Data Point Properties
reversed_dimensions = sorted(supported_dimensions, reverse = True)
columns_per_series = None
if reversed_dimensions:
for dimension in reversed_dimensions:
if series_idx is not None and dimension > 1 and column_count % (dimension - 1) == 0:
if dimension > 2 and props_from_array[-1] == 'name':
columns_per_series = dimension - 2
else:
columns_per_series = dimension - 1
break
if dimension > 1 and column_count % dimension == 0:
columns_per_series = dimension
break
elif dimension == 1:
columns_per_series = 1
if not columns_per_series:
raise errors.HighchartsCSVDeserializationError(
f'Could not determine how to deserialize CSV with {column_count}'
f' columns into a {collection_cls.__name__} instance. Please supply '
f'more precise instructions using property_column_map or '
f'by explicitly specificying data property kwargs.'
)
series_count = column_count // columns_per_series
if columns_per_series == 1 and series_idx:
series_count -= 1
series_list = []
for index in range(series_count):
start = 1 + (len(series_list) * columns_per_series)
property_map = {}
if series_idx is not None:
expected_length = columns_per_series + 1
else:
expected_length = columns_per_series
props_from_array = data_point_cls._get_props_from_array(length = expected_length)
if not props_from_array:
props_from_array = ['x', 'y']
property_map[props_from_array[0]] = [x.get(series_idx, None)
for x in csv_records]
has_implicit_series_name = 'name' not in kwargs and 'name' not in series_kwargs
if has_implicit_series_name:
try:
series_name = columns[start]
except (IndexError, TypeError):
series_name = None
else:
series_name = series_kwargs.get('name', None) or kwargs.get('name', None)
props_from_array = props_from_array[1:]
for idx, prop in enumerate(props_from_array):
index = start + idx
prop_array = [x.get(columns[index], idx) for x in csv_records]
property_map[prop] = prop_array
collection = collection_cls()
for key in property_map:
try:
setattr(collection, key, property_map[key])
except ValueError as error:
if key not in ['x', 'name'] and 'name' not in property_map:
setattr(collection, 'name', property_map[key])
else:
raise error
series_kwargs['data'] = collection
series_instance = cls(**series_kwargs)
for key in kwargs:
if key not in series_kwargs and key not in property_map:
setattr(series_instance, key, kwargs[key])
if 'name' not in series_kwargs and 'name' not in kwargs:
series_instance.name = series_name
series_list.append(series_instance)
if series_index is not None:
return series_list[series_index]
return series_list
[docs] @classmethod
def from_csv_in_rows(cls,
as_string_or_file,
has_header_row = True,
series_kwargs = None,
delimiter = ',',
null_text = 'None',
wrapper_character = "'",
line_terminator = '\r\n',
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\",
**kwargs):
"""Create a new :term:`series` instance with a
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from data in a CSV string or file.
.. note::
For an example
:class:`LineSeries <highcharts_core.options.series.area.LineSeries>`, the
minimum code required would be:
.. code-block:: python
my_series = LineSeries.from_csv_in_rows('some-csv-file.csv')
:param as_string_or_file: The CSV data to use to pouplate data. Accepts either
the raw CSV data as a :class:`str <python:str>` or a path to a file in the
runtime environment that contains the CSV data.
.. tip::
Unwrapped empty column values are automatically interpreted as null
(:obj:`None <python:None>`).
:type as_string_or_file: :class:`str <python:str>` or Path-like
:param has_header_row: If ``True``, indicates that the first row of
``as_string_or_file`` contains column labels, rather than actual data. Defaults
to ``True``.
:type has_header_row: :class:`bool <python:bool>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from the CSV file instead.
:type series_kwargs: :class:`dict <python:dict>`
:param delimiter: The delimiter used between columns. Defaults to ``,``.
:type delimiter: :class:`str <python:str>`
:param wrapper_character: The string used to wrap string values when
wrapping is applied. Defaults to ``'``.
:type wrapper_character: :class:`str <python:str>`
:param null_text: The string used to indicate an empty value if empty
values are wrapped. Defaults to `None`.
:type null_text: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
:type line_terminator: :class:`str <python:str>`
:param line_terminator: The string used to indicate the end of a line/record in
the CSV data. Defaults to ``'\\r\\n'``.
.. note::
The Python :mod:`csv <python:csv>` currently ignores the ``line_terminator``
parameter and always applies ``'\\r\\n'``, by design. The Python docs say this
may change in the future, so for future backwards compatibility we are
including it here.
:type line_terminator: :class:`str <python:str>`
:param wrap_all_strings: If ``True``, indicates that the CSV file has all string
data values wrapped in quotation marks. Defaults to ``False``.
.. warning::
If set to ``True``, the :mod:`csv <python:csv>` module will try to coerce any
value that is *not* wrapped in quotation marks to a
:class:`float <python:float>`. This can cause unexpected behavior, and
typically we recommend leaving this as ``False`` and then re-casting values
after they have been parsed.
:type wrap_all_strings: :class:`bool <python:bool>`
:param double_wrapper_character_when_nested: If ``True``, quote character is
doubled when appearing within a string value. If ``False``, the
``escape_character`` is used to prefix quotation marks. Defaults to ``False``.
:type double_wrapper_character_when_nested: :class:`bool <python:bool>`
:param escape_character: A one-character string that indicates the character used
to escape quotation marks if they appear within a string value that is already
wrapped in quotation marks. Defaults to ``\\\\`` (which is Python for ``'\\'``,
which is Python's native escape character).
:type escape_character: :class:`str <python:str>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:returns: A :term:`series` instance (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) OR
:class:`list <python:list>` of series instances with its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from the data in ``df``.
:rtype: :class:`list <python:list>` of series instances (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descendent
:raises HighchartsCSVDeserializationError: if ``property_column_map`` references
CSV columns by their label, but the CSV data does not contain a header row
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
if not checkers.is_on_filesystem(as_string_or_file):
as_str = as_string_or_file
columns, csv_records = utility_functions.parse_csv(
as_str,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
else:
with open(as_string_or_file, 'r', newline = '') as file_:
columns, csv_records = utility_functions.parse_csv(
file_,
has_header_row = has_header_row,
delimiter = delimiter,
null_text = null_text,
wrapper_character = wrapper_character,
line_terminator = line_terminator,
wrap_all_strings = False,
double_wrapper_character_when_nested = False,
escape_character = "\\"
)
collection_cls = cls._data_collection_class()
supported_dimensions = collection_cls._get_supported_dimensions()
if 2 not in supported_dimensions:
raise errors.HighchartsPandasDeserializationError(
f'Unable to create a collection of {cls.__name__} instances '
f'from CSV using a 2-dimensional array because {cls.__name__} does '
f'not support 2-dimensional arrays as inputs. Please use a '
f'different series type, or transpose the CSV to a columnar structure '
f'and supply a column_property_map for greater precision.'
)
data_properties = collection_cls._get_props_from_array()
if columns:
x_values = columns[1:]
else:
x_values = [x for x in range(len(csv_records[0].keys()) - 1)]
name_key = list(csv_records[0].keys())[0]
name_values = [row[name_key] for row in csv_records]
series_count = len(csv_records)
series_list = []
for row in range(series_count):
series_name = name_values[row]
y_values = [x for x in list(csv_records[row].values())[1:]]
for i, value in enumerate(y_values):
if value and isinstance(value, str) and ',' in value:
test_value = value.replace(',', '')
if checkers.is_numeric(test_value):
value = test_value
y_values[i] = value
as_array = zip(x_values, y_values)
collection = collection_cls.from_array(as_array)
series_instance_kwargs = series_kwargs.copy()
series_instance_kwargs['data'] = collection
series_instance_kwargs['name'] = series_name
series_instance = cls(**series_instance_kwargs)
for key in kwargs:
if key not in series_instance_kwargs and key not in data_properties:
setattr(series_instance, key, kwargs[key])
series_list.append(series_instance)
return series_list
[docs] def load_from_pandas(self,
df,
property_map = None,
series_in_rows = False,
series_index = None):
"""Replace the contents of the
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
with data points populated from a `pandas <https://pandas.pydata.org/>`_
:class:`DataFrame <pandas:pandas.DataFrame>`.
:param df: The :class:`DataFrame <pandas:pandas.DataFrame>` from which data should be
loaded.
:type df: :class:`DataFrame <pandas:pandas.DataFrame>`
:param property_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which column in ``df``. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value should indicate the label for the
:class:`DataFrame <pandas:pandas.DataFrame>` column. Defaults to
:obj:`None <python:None>`.
:type property_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param series_in_rows: if ``True``, will attempt a streamlined cartesian series
with x-values taken from column names, y-values taken from row values, and
the series name taken from the row index. Defaults to
:obj:`False <python:False>`.
:type series_in_rows: :class:`bool <python:bool>`
:param series_index: If supplied, return the series that Highcharts for Python
generated from ``df`` at the ``series_index`` value. Defaults to
:obj:`None <python:None>`, which returns all series generated from ``df``.
.. warning::
If :obj:`None <python:None>` and Highcharts for Python generates multiple
series, then a :exc:`HighchartsPandasDeserializationError` will be raised.
:type series_index: :class:`int <python:int>`, or :obj:`None <python:None>`
:raises HighchartsPandasDeserializationError: if ``property_map`` references
a column that does not exist in the data frame
:raises HighchartsPandasDeserializationError: if ``series_index`` is
:obj:`None <python:None>`, and it is ambiguous which series generated from
the dataframe should be used
:raises HighchartsDependencyError: if `pandas <https://pandas.pydata.org/>`_ is
not available in the runtime environment
"""
cls = self.__class__
new_instance = cls.from_pandas(df,
property_map = property_map,
series_in_rows = series_in_rows)
if series_index is None and isinstance(new_instance, list):
raise errors.HighchartsPandasDeserializationError(
f'Expected data for a single series, but got {len(new_instance)} when '
f'loading from df. Please either modify the structure of df '
f'or provide more targeted instructions using the property_map '
f'argument.'
)
elif isinstance(new_instance, list):
new_instance = new_instance[series_index]
self.data = new_instance.data
@classmethod
def _from_pandas_multi_map(cls,
df,
property_map,
series_kwargs = None,
**kwargs):
"""Create one or more :term:`series` instances whose
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` properties
are populated from a `pandas <https://pandas.pydata.org/>`_
:class:`DataFrame <pandas:pandas.DataFrame>`, when ``property_map`` suggests there are
multiple series.
:param df: The :class:`DataFrame <pandas:pandas.DataFrame>` from which data should be
loaded.
:type df: :class:`DataFrame <pandas:pandas.DataFrame>`
:param property_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which column in ``df``. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value should indicate the label for the
:class:`DataFrame <pandas:pandas.DataFrame>` column. Defaults to :obj:`None <python:None>`
:type property_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from ``df`` instead.
:type series_kwargs: :class:`dict <python:dict>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:returns: A :term:`series` instance (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) OR
:class:`list <python:list>` of series instances with its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from the data in ``df``.
:rtype: :class:`list <python:list>` of series instances (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descendent
:raises HighchartsPandasDeserializationError: if ``property_map`` references
a column that does not exist in the data frame
:raises HighchartsDependencyError: if `pandas <https://pandas.pydata.org/>`_ is
not available in the runtime environment
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
fixed_values = {}
iterable_values = {}
number_of_series = 1
mismatched_series = {}
names = []
for key in property_map:
map_value = property_map[key]
is_iterable = not isinstance(map_value, (str, bytes, dict, UserDict)) and \
hasattr(map_value, '__iter__')
if is_iterable:
for item in map_value:
if item not in df.columns.values:
raise errors.HighchartsPandasDeserializationError(
f'Unable to find a column labeled "{item}" in df.'
)
implied_series = len(map_value)
if number_of_series == 1 and implied_series > number_of_series:
number_of_series = implied_series
elif implied_series != number_of_series:
mismatched_series[key] = implied_series
iterable_values[key] = map_value
if key == 'y':
names.extend(map_value)
else:
if map_value not in df.columns.values:
if map_value != df.index.name:
raise errors.HighchartsPandasDeserializationError(
f'Unable to find a column labeled "{map_value}" in df.'
)
fixed_values[key] = map_value
if key == 'y':
names.append(map_value)
if mismatched_series:
raise errors.HighchartsPandasDeserializationError(
f'Unable to create series from df. The property map implied '
f'multiple series were needed, but properties had mismatched '
f'number of values:\n{mismatched_series}'
)
collections = []
for index in range(number_of_series):
collection_cls = cls._data_collection_class()
collection_instance = collection_cls()
for key in iterable_values:
iterable_value = iterable_values[key][index]
prop_array = df[iterable_value].values
setattr(collection_instance, key, prop_array)
for key in fixed_values:
fixed_value = fixed_values[key]
try:
prop_array = df[fixed_value].values
except KeyError:
prop_array = df.index.values
setattr(collection_instance, key, prop_array)
collections.append(collection_instance)
series_list = []
for index in range(number_of_series):
series_kwargs['data'] = collections[index]
series_instance = cls(**series_kwargs)
try:
series_instance.name = names[index]
except IndexError:
pass
for key in kwargs:
if key not in series_kwargs and property_map:
setattr(series_instance, key, kwargs[key])
series_list.append(series_instance)
return series_list
[docs] @classmethod
def from_pandas_in_rows(cls,
df,
series_kwargs = None,
series_index = None,
**kwargs):
"""Create a collection of :term:`series` instances, one for each
row in ``df``.
:param df: The :class:`DataFrame <pyspark:pyspark.sql.DataFrame>` from which data
should be loaded.
:type df: :class:`DataFrame <pyspark:pyspark.sql.DataFrame>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be
*overwritten*. The ``data`` value will be created from ``df`` instead.
:type series_kwargs: :class:`dict <python:dict>`
:param series_index: If supplied, return the series that Highcharts for Python
generated from ``df`` at the ``series_index`` value. Defaults to
:obj:`None <python:None>`, which returns all series generated from ``df``.
:type series_index: :class:`int <python:int>`, slice, or
:obj:`None <python:None>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:returns: Collection of :term:`series` instances corresponding, with one series
per row in ``df``, and where:
* the series x-values are populated from the column labels in ``df``
* the series name is set to the row label from ``df``
* the series y-values are populated from the values within that row in ``df``
:rtype: :class:`list <python:list>` of
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descendent
instances
"""
try:
from pandas import DataFrame
except ImportError:
raise errors.HighchartsDependencyError('pandas is not available in the '
'runtime environment. Please install '
'using "pip install pandas"')
if not checkers.is_type(df, ('DataFrame')):
raise errors.HighchartsValueError(f'df is expected to be a Pandas DataFrame.'
f'Was: {df.__class__.__name__}')
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
collection_cls = cls._data_collection_class()
supported_dimensions = collection_cls._get_supported_dimensions()
if 2 not in supported_dimensions:
raise errors.HighchartsPandasDeserializationError(
f'Unable to create a collection of {cls.__name__} instances '
f'from df using a 2-dimensional array because {cls.__name__} does '
f'not support 2-dimensional arrays as inputs. Please use a '
f'different series type, or transpose df to a columnar structure '
f'and supply a property_map for greater precision.'
)
data_properties = collection_cls._get_props_from_array()
x_values = df.columns.values
name_values = df.index.values
series_count = len(df)
series_list = []
for row in range(series_count):
series_name = name_values[row]
y_values = df.iloc[[row]].values
y_values = y_values.reshape(x_values.shape)
as_array = np.column_stack((x_values, y_values))
collection = collection_cls.from_array(as_array)
series_instance_kwargs = series_kwargs.copy()
series_instance_kwargs['data'] = collection
series_instance_kwargs['name'] = series_name
series_instance = cls(**series_instance_kwargs)
for key in kwargs:
if key not in series_instance_kwargs and key not in data_properties:
setattr(series_instance, key, kwargs[key])
series_list.append(series_instance)
if series_index is not None:
return series_list[series_index]
return series_list
[docs] @classmethod
def from_pandas(cls,
df,
property_map = None,
series_kwargs = None,
series_in_rows = False,
series_index = None,
**kwargs):
"""Create one or more :term:`series` instances whose
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` properties
are populated from a `pandas <https://pandas.pydata.org/>`_
:class:`DataFrame <pandas:pandas.DataFrame>`.
.. code-block:: python
# Given a Pandas DataFrame instance named "df"
from highcharts_core.chart import Chart
from highcharts_core.options.series.area import LineSeries
# Creating a Series from the DataFrame
## EXAMPLE 1. Minimum code required. Creates one or more series.
my_series = LineSeries.from_pandas(df)
## EXAMPLE 2. More precise configuration. Creates ONE series.
my_series = LineSeries.from_pandas(df, series_index = 2)
## EXAMPLE 3. More precise configuration. Creates ONE series.
my_series = LineSeries.from_pandas(df,
property_map = {
'x': 'date',
'y': 'value',
'id': 'id'
})
## EXAMPLE 4. More precise configuration. Creates THREE series.
my_series = LineSeries.from_pandas(df,
property_map = {
'x': 'date',
'y': ['value1', 'value2', 'value3'],
'id': 'id'
})
:param df: The :class:`DataFrame <pandas:pandas.DataFrame>` from which data should be
loaded.
:type df: :class:`DataFrame <pandas:pandas.DataFrame>`
:param property_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which column in ``df``. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value should indicate the label for the
:class:`DataFrame <pandas:pandas.DataFrame>` column. Defaults to
:obj:`None <python:None>`.
.. note::
If any of the values in ``property_map`` contain an iterable, then
one series will be produced for each item in the iterable. For example,
the following:
.. code-block:: python
{
'x': 'timestamp',
'y': ['value1', 'value2', 'value3']
}
will return *three* series, each of which will have its
:meth:`.x <CartesianData.x>` value populated from the column
labeled ``'timestamp'``, and whose :meth:`.y <CartesianData.y>`
values will be populated from the columns labeled ``'value1'``,
``'value2'``, and ``'value3'``, respectively.
:type property_map: :class:`dict <python:dict>` or :obj:`None <python:None>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from ``df`` instead.
:type series_kwargs: :class:`dict <python:dict>`
:param series_in_rows: if ``True``, will attempt a streamlined cartesian series
with x-values taken from column names, y-values taken from row values, and
the series name taken from the row index. Defaults to ``False``.
:obj:`False <python:False>`.
:type series_in_rows: :class:`bool <python:bool>`
:param series_index: If supplied, return the series that Highcharts for Python
generated from ``df`` at the ``series_index`` value. Defaults to
:obj:`None <python:None>`, which returns all series generated from ``df``.
:type series_index: :class:`int <python:int>`, slice, or
:obj:`None <python:None>`
:param **kwargs: Remaining keyword arguments will be attempted on the resulting
:term:`series` instance and the data points it contains.
:returns: A :term:`series` instance (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) OR
:class:`list <python:list>` of series instances with its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from the data in ``df``.
:rtype: :class:`list <python:list>` of series instances (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) or
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descendent
:raises HighchartsPandasDeserializationError: if ``property_map`` references
a column that does not exist in the data frame
:raises HighchartsDependencyError: if `pandas <https://pandas.pydata.org/>`_ is
not available in the runtime environment
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
# SCENARIO 0: Series in Rows
if series_in_rows:
return cls.from_pandas_in_rows(df,
series_kwargs,
series_index = series_index,
**kwargs)
# SCENARIO 1: Has Property Map
if property_map:
series_list = cls._from_pandas_multi_map(df,
property_map,
series_kwargs,
**kwargs)
if len(series_list) == 1:
return series_list[0]
if series_index is not None:
return series_list[series_index]
return series_list
# SCENARIO 2: Properties in KWARGS
collection_cls = cls._data_collection_class()
data_point_cls = cls._data_point_class()
props_from_array = data_point_cls._get_props_from_array()
if not props_from_array:
props_from_array = ['x', 'y']
property_map = {}
for prop in props_from_array:
if prop in kwargs:
property_map[prop] = kwargs[prop]
if property_map:
series_list = cls._from_pandas_multi_map(df,
property_map,
series_kwargs)
for index in range(len(series_list)):
for key in kwargs:
if key not in props_from_array and key not in series_kwargs:
setattr(series_list[index], key, kwargs[key])
if len(series_list) == 1:
return series_list[0]
if series_index is not None:
return series_list[series_index]
return series_list
# SCENARIO 3: No Explicit Properties
series_idx = kwargs.get('index', df.index)
column_count = len(df.columns)
supported_dimensions = collection_cls._get_supported_dimensions()
# SCENARIO 3a: Single Series, Data Frame Columns align exactly to Data Point Properties
if column_count in supported_dimensions:
property_map = {}
props_from_array = data_point_cls._get_props_from_array(length = column_count)
if not props_from_array:
props_from_array = ['x', 'y']
property_map[props_from_array[0]] = series_idx
for index, prop in enumerate(props_from_array[1:]):
prop_value = df.iloc[:, index + 1].values
property_map[prop] = prop_value
collection = collection_cls()
for key in property_map:
setattr(collection, key, property_map[key])
series_kwargs['data'] = collection
series_instance = cls(**series_kwargs)
for key in kwargs:
if key not in series_kwargs and key not in property_map:
setattr(series_instance, key, kwargs[key])
return series_instance
# SCENARIO 3b: Multiple Series, Data Frame Columns correspond to multiples of Data Point Properties
reversed_dimensions = sorted(supported_dimensions, reverse = True)
columns_per_series = None
if reversed_dimensions:
for dimension in reversed_dimensions:
if series_idx is not None and dimension > 1 and column_count % (dimension - 1) == 0:
if dimension > 2 and props_from_array[-1] == 'name':
columns_per_series = dimension - 2
else:
columns_per_series = dimension - 1
break
elif dimension > 1 and column_count % dimension == 0:
columns_per_series = dimension
break
elif dimension == 1:
columns_per_series = 1
if not columns_per_series:
raise errors.HighchartsPandasDeserializationError(
f'Could not determine how to deserialize data frame with {column_count}'
f' columns into a {collection_cls.__name__} instance. Please supply '
f'more precise instructions using property_map or '
f'by explicitly specificying data property kwargs.'
)
series_count = column_count // columns_per_series
series_list = []
for index in range(series_count):
start = len(series_list) * columns_per_series
property_map = {}
if series_idx is not None:
expected_length = columns_per_series + 1
else:
expected_length = columns_per_series
props_from_array = data_point_cls._get_props_from_array(length = expected_length)
if not props_from_array:
props_from_array = ['x', 'y']
property_map[props_from_array[0]] = series_idx
has_implicit_series_name = 'name' not in kwargs and 'name' not in series_kwargs
if has_implicit_series_name:
series_name = df.columns[start]
else:
series_name = series_kwargs.get('name', None) or kwargs.get('name', None)
for index, prop in enumerate(props_from_array[1:]):
index = start + index
prop_value = df.iloc[:, index].values
property_map[prop] = prop_value
collection = collection_cls()
for key in property_map:
setattr(collection, key, property_map[key])
series_kwargs['data'] = collection
series_kwargs['name'] = series_name
series_instance = cls(**series_kwargs)
for key in kwargs:
if key not in series_kwargs and key not in property_map:
setattr(series_instance, key, kwargs[key])
series_list.append(series_instance)
if series_index is not None:
return series_list[index]
return series_list
[docs] def load_from_pyspark(self,
df,
property_map):
"""Replaces the contents of the
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
with values from a `PySpark <https://spark.apache.org/docs/latest/api/python/>`_
:class:`DataFrame <pyspark:pyspark.sql.DataFrame>`.
:param df: The :class:`DataFrame <pyspark:pyspark.sql.DataFrame>` from which data
should be loaded.
:type df: :class:`DataFrame <pyspark:pyspark.sql.DataFrame>`
:param property_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which column in ``df``. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value should indicate the label for the
:class:`DataFrame <pyspark:pyspark.sql.DataFrame>` column.
:type property_map: :class:`dict <python:dict>`
:raises HighchartsPySparkDeserializationError: if ``property_map`` references
a column that does not exist in the data frame
:raises HighchartsDependencyError: if
`PySpark <https://spark.apache.org/docs/latest/api/python/>`_ is not available
in the runtime environment
"""
try:
from pyspark.sql import DataFrame
except ImportError:
raise errors.HighchartsDependencyError('pyspark is not available in the '
'runtime environment. Please install '
'using "pip install pyspark"')
if not checkers.is_type(df, ('DataFrame')):
raise errors.HighchartsValueError(f'df is expected to be a PySpark DataFrame.'
f'Was: {df.__class__.__name__}')
property_map = validators.dict(property_map)
column_instances = []
for key in property_map:
map_value = property_map[key]
if map_value not in df.columns:
raise errors.HighchartsPySparkDeserializationError(
f'Unable to find a column labeled "{map_value}" in df.'
)
column_instance = getattr(df, map_value)
column_instances.append(column_instance)
narrower_df = df.select(*column_instances)
rdd_as_jsons = narrower_df.toJSON()
df_as_dicts = [json.loads(x) for x in rdd_as_jsons.toLocalIterator()]
records_as_dicts = []
for record in df_as_dicts:
record_as_dict = {}
for key in property_map:
map_value = property_map[key]
record_as_dict[key] = record.get(map_value, None)
records_as_dicts.append(record_as_dict)
self.data = records_as_dicts
[docs] @classmethod
def from_pyspark(cls,
df,
property_map,
series_kwargs = None):
"""Create a :term:`series` instance whose
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
is populated from a `PySpark <https://spark.apache.org/docs/latest/api/python/>`_
:class:`DataFrame <pyspark:pyspark.sql.DataFrame>`.
:param df: The :class:`DataFrame <pyspark:pyspark.sql.DataFrame>` from which data
should be loaded.
:type df: :class:`DataFrame <pyspark:pyspark.sql.DataFrame>`
:param property_map: A :class:`dict <python:dict>` used to indicate which
data point property should be set to which column in ``df``. The keys in the
:class:`dict <python:dict>` should correspond to properties in the data point
class, while the value should indicate the label for the
:class:`DataFrame <pyspark:pyspark.sql.DataFrame>` column.
:type property_map: :class:`dict <python:dict>`
:param series_kwargs: An optional :class:`dict <python:dict>` containing keyword
arguments that should be used when instantiating the series instance. Defaults
to :obj:`None <python:None>`.
.. warning::
If ``series_kwargs`` contains a ``data`` key, its value will be *overwritten*.
The ``data`` value will be created from ``df`` instead.
:type series_kwargs: :class:`dict <python:dict>`
:returns: A :term:`series` instance (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`) with its
:meth:`.data <highcharts_core.options.series.base.SeriesBase.data>` property
populated from the data in ``df``.
:rtype: :class:`list <python:list>` of series instances (descended from
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`)
:raises HighchartsPySparkDeserializationError: if ``property_map`` references
a column that does not exist in the data frame
:raises HighchartsDependencyError: if
`PySpark <https://spark.apache.org/docs/latest/api/python/>`_ is not available
in the runtime environment
"""
series_kwargs = validators.dict(series_kwargs, allow_empty = True) or {}
instance = cls(**series_kwargs)
instance.load_from_pyspark(df, property_map)
return instance
[docs] def to_chart(self, chart_kwargs = None, options_kwargs = None):
"""Create a :class:`Chart <highcharts_core.chart.Chart>` instance containing the
series instance.
:param chart_kwargs: Optional keyword arguments to use when constructing the
:class:`Chart <highcharts_core.chart.Chart>` instance. Defaults to
:obj:`None <python:None>`.
:type chart_kwargs: :class:`dict <python:dict>`
:param options_kwargs: Optional keyword arguments to use when constructing the
chart's :class:`HighchartsOptions <highcharts_core.options.HighchartsOptions>`
object. Defaults to :obj:`None <python:None>`.
.. warning::
If your ``chart_kwargs`` contains an ``options`` key, its value
will be overwritten if you supply ``options_kwargs``.
:type options_kwargs: :class:`dict <python:dict>`
:returns: A :class:`Chart <highcharts_core.chart.Chart>` instance containing the
series instance.
:rtype: :class:`Chart <highcharts_core.chart.Chart>`
"""
from highcharts_core.chart import Chart
chart_kwargs = validators.dict(chart_kwargs, allow_empty = True) or {}
as_chart = Chart(**chart_kwargs)
if options_kwargs:
as_chart.options = options_kwargs
as_chart.add_series(self)
return as_chart
[docs] def display(self,
global_options = None,
container = None,
retries = 5,
interval = 1000,
chart_kwargs = None,
options_kwargs = None):
"""Display the series in `Jupyter Labs <https://jupyter.org/>`_ or
`Jupyter Notebooks <https://jupyter.org/>`_.
:param global_options: The :term:`shared options` to use when rendering the chart.
Defaults to :obj:`None <python:None>`
:type global_options: :class:`SharedOptions <highcharts_stock.global_options.shared_options.SharedOptions>`
or :obj:`None <python:None>`
:param container: The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
:obj:`None <python:None>`, which applies the :meth:`.container <highcharts_core.chart.Chart.container>`
property if set, and ``'highcharts_target_div'`` if not set.
.. note::
Highcharts for Python will append a 6-character random string to the value of ``container``
to ensure uniqueness of the chart's container when rendering in a Jupyter Notebook/Labs context. The
:class:`Chart <highcharts_core.chart.Chart>` instance will retain the mapping between container and the
random string so long as the instance exists, thus allowing you to easily update the rendered chart by
calling the :meth:`.display() <highcharts_core.chart.Chart.display>` method again.
If you wish to create a new chart from the instance that does not update the existing chart, then you can do
so by specifying a new ``container`` value.
:type container: :class:`str <python:str>` or :obj:`None <python:None>`
:param retries: The number of times to retry rendering the chart. Used to avoid race conditions with the
Highcharts script. Defaults to 5.
:type retries: :class:`int <python:int>`
:param interval: The number of milliseconds to wait between retrying rendering the chart. Defaults to 1000 (1
seocnd).
:type interval: :class:`int <python:int>`
:param chart_kwargs: Optional keyword arguments to use when constructing the
:class:`Chart <highcharts_core.chart.Chart>` instance. Defaults to
:obj:`None <python:None>`.
:type chart_kwargs: :class:`dict <python:dict>`
:param options_kwargs: Optional keyword arguments to use when constructing the
chart's :class:`HighchartsOptions <highcharts_core.options.HighchartsOptions>`
object. Defaults to :obj:`None <python:None>`.
.. warning::
If your ``chart_kwargs`` contains an ``options`` key, its value
will be overwritten if you supply ``options_kwargs``.
:type options_kwargs: :class:`dict <python:dict>`
:raises HighchartsDependencyError: if
`ipython <https://ipython.readthedocs.io/en/stable/>`_ is not available in the
runtime environment
"""
as_chart = self.to_chart(chart_kwargs = chart_kwargs,
options_kwargs = options_kwargs)
as_chart.display(global_options = global_options,
container = container,
retries = retries,
interval = interval)
[docs] def convert_to(self, series_type):
"""Creates a new series of ``series_type`` from the current series.
:param series_type: The series type that should be returned.
:type series_type: :class:`str <python:str>` or
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>`-descended
.. warning::
This operation is *not* guaranteed to work converting between all series
types. This is because some series types have different properties, different
logic / functionality for their properties, and may have entirely different
data requirements.
In general, this method is expected to be *lossy* in nature, meaning that when
the series can be converted "close enough" the series will be converted.
However, if the target ``series_type`` does not support certain properties set
on the original instance, then those settings will *not* be propagated to the
new series.
In certain cases, this method may raise an
:exc:`HighchartsSeriesConversionError <highcharts_core.errors.HighchartsSeriesConversionError>`
if the method is unable to convert (even losing some data) the original into
``series_type``.
:returns: A new series of ``series_type``, maintaining relevant properties and
data from the original instance.
:rtype: ``series_type``
:class:`SeriesBase <highcharts_core.options.series.base.SeriesBase>` descendant
:raises HighchartsSeriesConversionError: if unable to convert (even after losing
some data) the original instance into an instance of ``series_type``.
:raises HighchartsValueError: if ``series_type`` is not a recognized series type
"""
from highcharts_core.options.series.series_generator import SERIES_CLASSES
if isinstance(series_type, str):
series_type = series_type.lower()
if series_type not in SERIES_CLASSES:
raise errors.HighchartsValueError(f'series_type expects a valid Highcharts '
f'series type. Received: {series_type}')
series_type_name = series_type
series_type = SERIES_CLASSES.get(series_type)
elif not issubclass(series_type, SeriesBase):
raise errors.HighchartsValueError(f'series_type expects a valid Highcharts '
f'series type. Received: {series_type}')
else:
series_type_name = series_type.__name__
as_js_literal = self.to_js_literal()
try:
target = series_type.from_js_literal(as_js_literal)
except (ValueError, TypeError):
raise errors.HighchartsSeriesConversionError(f'Unable to convert '
f'{self.__class__.__name__} instance '
f'to {series_type_name}')
return target