.area
class: AreaSeries
- class AreaSeries(**kwargs)[source]
Options for a specific Area series.
Class Inheritance
- convert_to(series_type)
Creates a new series of
series_type
from the current series.- Parameters:
series_type (
str
orSeriesBase
-descended) – The series type that should be returned.
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
HighchartsSeriesConversionError
if the method is unable to convert (even losing some data) the original intoseries_type
.- Returns:
A new series of
series_type
, maintaining relevant properties and data from the original instance.- Return type:
series_type
SeriesBase
descendant- Raises:
HighchartsSeriesConversionError – if unable to convert (even after losing some data) the original instance into an instance of
series_type
.HighchartsValueError – if
series_type
is not a recognized series type
- copy(other=None, overwrite=True, **kwargs)
Copy the configuration settings from this instance to the
other
instance.- Parameters:
other (
HighchartsMeta
) – The target instance to which the properties of this instance should be copied. IfNone
, will create a new instance and populate it with properties copied fromself
. Defaults toNone
.overwrite (
bool
) – ifTrue
, properties inother
that are already set will be overwritten by their counterparts inself
. Defaults toTrue
.kwargs – Additional keyword arguments. Some special descendents of
HighchartsMeta
may have special implementations of this method which rely on additional keyword arguments.
- Returns:
A mutated version of
other
with new property values
- display(global_options=None, container=None, retries=5, interval=1000, chart_kwargs=None, options_kwargs=None)
Display the series in Jupyter Labs or Jupyter Notebooks.
- Parameters:
global_options (
SharedOptions
orNone
) – The shared options to use when rendering the chart. Defaults toNone
The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
None
, which applies the.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. TheChart
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.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.retries (
int
) – The number of times to retry rendering the chart. Used to avoid race conditions with the Highcharts script. Defaults to 5.interval (
int
) – The number of milliseconds to wait between retrying rendering the chart. Defaults to 1000 (1 seocnd).chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Raises:
HighchartsDependencyError – if ipython is not available in the runtime environment
- classmethod from_array(value, series_kwargs=None)
Create one instance of the series with
data
populated fromvalue
.- Parameters:
value (iterable) –
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.series_kwargs (
dict
orNone
) – Optional keyword arguments to apply when instanting the series. Defaults toNone
.
- Returns:
An instance of the series type with
data
populated from the value.- Return type:
SeriesBase
descendent
- classmethod from_csv(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 series instances with
.data
populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:# 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 filenamesome-csv-file.csv
. Thex
values for each data point will be taken from the first (index 0) column in the CSV file. They
values will be taken from the fourth (index 3) column in the CSV file. And theid
values will be taken from a column whose header row is labeled'id'
(regardless of its index).- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –A
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.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:{ 'x': 0, 'y': [3, 5, 8] }
will return three series, each of which will have its
.x
value populated from the first column (index 0), and whose.y
values will be populated from the fourth, sixth, and ninth columns (indices 3, 5, and 8), respectively.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated from the CSV at theseries_index
position. Defaults toNone
, which returns all series generated from the CSV.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_csv_in_rows(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 series instance with a
.data
property populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:my_series = LineSeries.from_csv_in_rows('some-csv-file.csv')
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)
Construct an instance of the class from a
dict
object.
- classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)
Return a Python object representation of a Highcharts JavaScript object literal.
- Parameters:
as_str_or_file (
str
) – The JavaScript object literal, represented either as astr
or as a filename which contains the JS object literal.allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
._break_loop_on_failure (
bool
) – IfTrue
, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults toFalse
.
- Returns:
A Python object representation of the Highcharts JavaScript object literal.
- Return type:
HighchartsMeta
- classmethod from_json(as_json_or_file, allow_snake_case: bool = True)
Construct an instance of the class from a JSON string.
- Parameters:
as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
.
- Returns:
A Python objcet representation of
as_json
.- Return type:
HighchartsMeta
- classmethod from_pandas(df, property_map=None, series_kwargs=None, series_in_rows=False, series_index=None, **kwargs)
Create one or more series instances whose
.data
properties are populated from a pandasDataFrame
.# 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' })
- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.A
dict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.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:{ 'x': 'timestamp', 'y': ['value1', 'value2', 'value3'] }
will return three series, each of which will have its
.x
value populated from the column labeled'timestamp'
, and whose.y
values will be populated from the columns labeled'value1'
,'value2'
, and'value3'
, respectively.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameif pandas is not available in the runtime environment
- classmethod from_pandas_in_rows(df, series_kwargs=None, series_index=None, **kwargs)
Create a collection of series instances, one for each row in
df
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
Collection of 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
- Return type:
list
ofSeriesBase
-descendent instances
- classmethod from_pyspark(df, property_map, series_kwargs=None)
Create a series instance whose
.data
property is populated from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.
- Returns:
A series instance (descended from
SeriesBase
) with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
)- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- get_required_modules(include_extension=False) List[str]
Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.
- load_from_array(value)
Update the
.data
property with data loaded from an iterable invalue
.- Parameters:
value (iterable) –
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.
- load_from_csv(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
.data
property with a new value populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be: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 filenamesome-csv-file.csv
. As shown in EXAMPLE 1, unless otherwise specified, the.x
values for each data point will be taken from the first (index 0) column in the CSV file, while the.y
values will be taken from the second column.If the CSV has more than 2 columns, then this will throw an
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.x
values for each data point will be taken from the first (index 0) column in the CSV file. The.y
values will be taken from the fourth (index 3) column in the CSV file. And the.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.
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –An optional
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.series_index (
int
orNone
) – ifNone
, will raise aHighchartsCSVDeserializationError
if the CSV data contains more than one series and noproperty_column_map
is provided. Otherwise, will update the instance with the series found in the CSV at theseries_index
value. Defaults toNone
.**kwargs –
Remaining keyword arguments will be attempted on the resulting 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
- load_from_pandas(df, property_map=None, series_in_rows=False, series_index=None)
Replace the contents of the
.data
property with data points populated from a pandasDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
orNone
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.If supplied, return the series that Highcharts for Python generated from
df
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.Warning
If
None
and Highcharts for Python generates multiple series, then aHighchartsPandasDeserializationError
will be raised.
- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameHighchartsPandasDeserializationError – if
series_index
isNone
, and it is ambiguous which series generated from the dataframe should be usedif pandas is not available in the runtime environment
- load_from_pyspark(df, property_map)
Replaces the contents of the
.data
property with values from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.
- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- to_chart(chart_kwargs=None, options_kwargs=None)
Create a
Chart
instance containing the series instance.- Parameters:
chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Returns:
A
Chart
instance containing the series instance.- Return type:
- to_dict() dict
Generate a
dict
representation of the object compatible with the Highcharts JavaScript library.Note
The
dict
representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.
- to_js_literal(filename=None, encoding='utf-8', careful_validation=False) str | None
Return the object represented as a
str
containing the JavaScript object literal.- Parameters:
along the way using the esprima-python library. Defaults to
False
.Warning
Setting this value to
True
will significantly degrade serialization performance, though it may prove useful for debugging purposes.
- to_json(filename=None, encoding='utf-8', for_export: bool = False)
Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.
Note
This method will either return a standard
str
or abytes
object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be abytes
representation of the string.- Parameters:
filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to
None
encoding (
str
) – The character encoding to apply to the resulting object. Defaults to'utf-8'
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
A JSON representation of the object compatible with the Highcharts library.
- Return type:
- static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) dict
Remove keys from
untrimmed
whose values areNone
and convert values that have.to_dict()
methods.- Parameters:
untrimmed (
dict
) – Thedict
whose values may still beNone
or Python objects.to_json (
bool
) – IfTrue
, will remove all keys fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
Trimmed
dict
- Return type:
- static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)
Convert any
EnforcedNullType
values inuntrimmed
to'null'
.- Parameters:
untrimmed (iterable) – The iterable whose members may still be
None
or Python objects.to_json (
bool
) – IfTrue
, will remove all members fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Return type:
iterable
- property accessibility: TypeOptionsAccessibility | None
Accessibility options for a series.
- Return type:
TypeOptionsAccessibility
orNone
- property allow_point_select: bool | None
Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).
The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript)
getSelectedPoints()
function.And alternative way of selecting points is through dragging.
Defaults to
False
.
- property animation: bool | AnimationOptions | None
Enable or disable the initial animation when a series is displayed.
The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see
Chart.animation
and theanimation
parameter under the (JavaScript) API methods. The following properties are supported:defer
: The animation delay time in milliseconds.duration
: The duration of the animation in milliseconds.easing
: Can be a string reference to an easing function set on the Math object or a function.
Warning
Due to poor performance, animation is disabled in old IE browsers for several chart types.
- Return type:
AnimationOptions
orNone
- property animation_limit: int | float | Decimal | None
For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to
None
.For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set
animation_limit
tofloat("inf")
(which represents infinity).- Return type:
numeric or
None
- property boost_threshold: int | None
Set the point threshold for when a series should enter boost mode. Defaults to
5000
.Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.
To disable boosting on the series, set the
boost_threshold
to0
. Setting it to1
will force boosting.Note
The
AreaOptions.crop_threshold()
also affects this setting.When zooming in on a series that has fewer points than the
crop_threshold
, all points are rendered although outside the visible plot area, and theboost_threshold
won’t take effect.
- property class_name: str | None
The additional CSS class name to apply to the series’ graphical elements.
Note
This option is additive to the default class names - it does not replace them.
- property clip: bool | None
If
False
, allows the series to be rendered in the entire plot area. IfTrue
, constrains where the series can be rendered within the plot area. Defaults toTrue
.
- property color: str | Gradient | Pattern | None
The main color of the series.
In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the
Options.colors()
array.
- property color_axis: str | int | bool | None
When using dual or multiple color axes, this setting defines which color axis the particular series is connected to. It refers to either the
ColorAxis.id()
or the index of the axis in theColorAxis
array, with0
being the first. Set this option toFalse
to prevent a series from connecting to the default color axis.Defaults to
0
.
- property color_index: int | None
When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name
highcharts-color-{n}
.Tip
New in version Highcharts: (JS) v.11
With Highcharts (JS) v.11, using CSS variables of the form
--highcharts-color-{n}
make changing the color scheme very simple.Defaults to
None
.
- property color_key: str | None
Determines what data value should be used to calculate point color if
AreaOptions.color_axis()
is used.Note
Requires to set
min
andmax
if some custom point property is used or if approximation for data grouping is set to'sum'
.
- property connect_ends: bool | None
If
True
, connect the ends of a line series plot across the extremes. Defaults toNone
.Warning
Applies to polar charts only.
- property connect_nulls: bool | None
If
True
, connect a graph line across null points. IfFalse
, renders a gap between the points on either side of the null point. Defaults toFalse
.
- property crisp: bool | None
If
True
, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults toTrue
.Hint
In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting
crisp
toFalse
may look better, even though each column is rendered blurry.
- property crop_threshold: int | None
When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to
300
.The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.
- property cursor: str | None
The style of cursor to use when the user’s mouse hovers over the data series.
Acceptable values are:
'alias'
'all-scroll'
'auto'
'cell'
'col-resize'
'context-menu'
'copy'
'crosshair'
'default'
'e-resize'
'ew-resize'
'grab'
'grabbing'
'help'
'move'
'n-resize'
'ne-resize'
'nesw-resize'
'no-drop'
'none'
'not-allowed'
'ns-resize'
'nw-resize'
'nwse-resize'
'pointer'
'progress'
'row-resize'
's-resize'
'se-resize'
'sw-resize'
'text'
'vertical-text'
'w-resize'
'wait'
'zoom-in'
'zoom-out'
- property custom: JavaScriptDict | None
A reserved subspace to store options and values for customized functionality.
Here you can add additional data for your own event callbacks and formatter callbacks.
- property dash_style: str | None
Name of the dash style to use for the graph, or for some series types the outline of each shape.
Accepts one of the following values:
‘Dash’,
‘DashDot’,
‘Dot’,
‘LongDash’,
‘LongDashDot’,
‘LongDashDotDot’,
‘ShortDash’,
‘ShortDashDot’,
‘ShortDashDotDot’,
‘ShortDot’,
‘Solid’
- property data: List[CartesianData] | CartesianDataCollection | None
Collection of data that represents the series. Defaults to
None
.While the series type returns a collection of
CartesianData
instances, it accepts as input three different types of data:area_series = AreaSeries() area_series.data = [0, 5, 3, 5]
A one-dimensional collection of numerical values. Each member of the collection will be interpreted as a
y
-value, with its correspondingx
value automatically determined.If
AreaSeries.point_start()
isNone
,x
values will begin at0
. Otherwise, they will start atpoint_start
.If
AreaSeries.point_interval()
isNone
,x
values will be incremented by1
. Otherwise, they will be incremented by the value ofpoint_interval
.area_series = AreaSeries() # Category X-axis area_series.data = [ ['Category A', 0], ['Category B', 5], ['Category C', 3], ['Category D', 5] ] # Numerical X-axis area_series.data = [ [9, 0], [1, 5], [2, 3], [7, 5] ]
A two-dimensional collection of values. Each member of the collection will be interpreted as an
x
andy
pair. Thex
value can be astr
,date
,datetime
, or numeric value.Note
If the
x
value is astr
, it will be interpreted as the name of the data point.A one-dimensional collection of
CartesianData
objects.
- property data_labels: DataLabel | List[DataLabel] | None
Options for the series data labels, appearing next to each data point.
Note
To have multiple data labels per data point, you can also supply a collection of
DataLabel
configuration settings.
- property data_sorting: DataSorting | None
Options for the series data sorting.
- Return type:
DataSorting
orNone
- property description: str | None
A description of the series to add to the screen reader information about the series.
- property drag_drop: DragDropOptions | None
The draggable-points module allows points to be moved around or modified in the chart.
In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:
point.dragStart
point.drag
point.drop
- Return type:
DragDropOptions
orNone
- property enable_mouse_tracking: bool | None
If
True
, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). IfFalse
, disables mouse tracking for the series (which can help performance). Defaults toTrue
.
- property events: SeriesEvents | None
General event handlers for the series items.
Note
These event hooks can also be attached to the series at run time using the (JavaScript)
Highcharts.addEvent()
function.- Return type:
SeriesEvents
orNone
- property fill_color: str | Gradient | Pattern | EnforcedNullType | None
Fill color or gradient for the area. When
EnforcedNullType
, the series’ color is used with the series’fill_opacity
.- Return type:
None
,Gradient
,Pattern
, orEnforcedNullType
- property fill_opacity: int | float | Decimal | None
Fill opacity for the area. Defaults to
0.75
.When you set an explicit
fill_color
, thefill_opacity
is not applied. Instead, you should define the opacity in thefill_color
with an rgba color definition.The
fill_opacity
setting, also the default setting, overrides the alpha component of the color setting.- Return type:
numeric or
None
- property find_nearest_point_by: str | None
Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.
If
None
, defaults to'xy'
for scatter series and'x'
for most other series. If the data has duplicate x-values, it is recommended to set this to'xy'
to allow hovering over all points.Applies only to series types using nearest neighbor search (not direct hover) for tooltip.
- property get_extremes_from_all: bool | None
If
True
, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.Warning
Applies to Cartesian series only.
- property id: str | None
An id for the series. Defaults to
None
.Hint
This can be used (in JavaScript) after render time to get a pointer to the series object through
chart.get()
.
- property inactive_other_points: bool | None
- If
True
, highlights only the hovered point and fades the other points. Defaults to
False
.Warning
Scatter-type series require enabling the ‘inactive’ marker state and adjusting opacity. This approach could affect performance
with large datasets.
- If
- property include_in_data_export: bool | None
If
False
, will prevent the data series from being included in any form of data export. Defaults toTrue
.
- property index: int | None
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 toNone
.
- property keys: List[str] | None
An array specifying which option maps to which key in the data point array.
This makes it convenient to work with unstructured data arrays from different sources.
- property label: SeriesLabel | None
Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.
Note
The series labels currently work with series types having a graph or an area.
- Return type:
SeriesLabel
orNone
- property legend_index: int | None
The sequential index for the series in the legend. Defaults to
None
.
- property legend_symbol: str | None
The type of legend symbol to render for the series. Accepts either
'lineMarker'
,'areaMarker'
, or'rectangle'
. Defaults to'rectangle'
.- Return type:
- property line_color: str | Gradient | Pattern | None
A separate color for the graph line. When
None
, by default the line takes the color of the series, but theline_color
setting allows setting a separate color for the line without altering thefill_color
.
- property line_width: int | float | Decimal | None
Pixel width of the graph line. Defaults to
2
.- Return type:
numeric or
None
- property linecap: str | None
The SVG value used for the
stroke-linecap
andstroke-linejoin
of a line graph. Defaults to'round'
, which means that lines are rounded in the ends and bends.
- property linked_to: str | None
The id of another series to link to.
Hint
The value can be
':previous'
to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.Note
If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.
- property marker: Marker | None
Options for the point markers of line-like series.
Properties like
fill_color
,line_color
andline_width
define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.- Return type:
Marker
orNone
- property name: str | None
The name of the series as shown in the legend, tooltip, etc. Defaults to
None
.
- property negative_color: str | Gradient | Pattern | None
The color for the parts of the graph or points that are below the
AreaOptions.threshold()
.Note
Zones
take precedence over the negative color. Usingnegative_color
is equivalent to applying a zone with value of 0.
- property negative_fill_color: str | Gradient | Pattern | None
A separate color for the negative part of the area.
- property on_point: OnPointOptions | None
Options for the Series on point feature, which is currently only supported by
pie
andsunburst
chargs.- Return type:
OnPointOptions
orNone
- property opacity: float | None
Opacity of a series parts: line, fill (e.g. area), and labels.
- Return type:
- property point_description_format: str | None
A format string to use instead of the default for point descriptions on the series. Defaults to
None
.Note
Overrides the chart-wide configuration, as applicable.
- property point_description_formatter: CallbackFunction | None
Same as for
Accessibility.series.description_formatter()
, only for an individual series. Overrides the chart-wide configuration.- Return type:
CallbackFunction
orNone
- property point_interval: int | float | Decimal | None
If no x values are given for the points in a series,
point_interval
defines the interval of the x values. Defaults to1
.For example, if a series contains one value every decade starting from year 0, set
point_interval
to10
. In true datetime axes, thepoint_interval
is set in milliseconds.Hint
point_interval
can be also be combined withpoint_interval_unit
to draw irregular time intervals.Note
If combined with
relative_x_value
, an x value can be set on each point, and thepoint_interval
is added x times to thepoint_start
setting.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- Return type:
numeric or
None
- property point_interval_unit: str | None
On datetime series, this allows for setting the
point_interval
to irregular time units, day, month, and year.A day is usually the same as 24 hours, but
point_interval_unit
also takes the DST crossover into consideration when dealing with local time.Combine this option with
point_interval
to draw weeks, quarters, 6 month periods, 10 year periods, etc.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- property point_placement: int | float | Decimal | str | None
Used to determine the placement of the point in relation to tick marks on the X axis. Defaults to
None
, which behaves as undefined in cartesian charts, and"between"
in polar charts.Accepts possible values:
'on'
- where the point will not create any padding of the X axis. In a polar column chart this means that the first column points directly north."between"
- where the columns will be laid out between ticks. This is useful for example for visualising an amount between two points in time or in a certain sector of a polar chart.a numeric value - where
0
is on the axis value,-0.5
is between this value and the previous, and0.5
is between this value and the next. Unlike the textual options, numeric point placement options won’t affect axis padding.
Warning
Requires
point_range
to work. For column series this is computed, but for line-type series it needs to be set.Note
For the xrange series type and gantt charts, if the Y axis is a category axis, the
point_placement
applies to the Y axis rather than the (typically datetime) X axis.
- property point_start: int | float | Decimal | None
If no x values are given for the points in a series,
point_start
defines on what value to start. For example, if a series contains one yearly value starting from 1945, setpoint_start
to1945
. Defaults to0
.Note
If combined with
relative_x_value
, an x value can be set on each point. The x value from the point options is multiplied bypoint_interval
and added topoint_start
to produce a modified x value.- Return type:
numeric or
None
- property relative_x_value: bool | None
When
True
, X values in the data set are relative to the currentpoint_start
,point_interval
, andpoint_interval_unit
settings. This allows compression of the data for datasets with irregular X values. Defaults toFalse
.The real X values are computed on the formula
f(x) = ax + b
, wherea
is thepoint_interval
(optionally with a time unit given bypoint_interval_unit
), andb
is thepoint_start
.
- property selected: bool | None
If
True
, the series is selected initially (by default, without user interaction). Defaults toFalse
.Note
If
GenericTypeOptions.show_checkbox()
isTrue
, then the checkbox will be checked ifselected
isTrue
.
- property shadow: bool | ShadowOptions | None
Configuration for the shadow to apply to the tooltip. Defaults to
False
.If
False
, no shadow is applied.- Returns:
The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.
- Return type:
bool
orShadowOptions
- property show_checkbox: bool | None
If
True
, a checkbox is displayed next to the legend item to allow selecting the series.Note
The state of the checkbox is controlled by the
GenericTypeOptions.selected()
property.
- property show_in_legend: bool | None
Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.
If
True
, the accessibility module will skip past this series when executing keyboard navigation.
- property soft_threshold: bool | None
When
True
, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults toTrue
.For example, if
False
, a series of0, 1, 2, 3
will make the Y axis show negative values according to themin_padidng
option. IfTrue
, the Y axis starts at 0.- Return type:
- property sonification: SeriesSonification | None
Sonification configuration for the series type/series.
- Return type:
- property stack: str | None
Indicates the “stack” into which the series should be grouped, if the chart groups series into stacks. Defaults to
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.
- property stacking: str | None
Whether to stack the values of each series on top of each other. Defaults to
None
.Acceptable values are:
None
to disable stacking,"normal"
to stack by value or"percent"
'stream'
(for streamgraph series type only)'overlap'
(for waterfall series type only)
Note
When stacking is enabled, data must be sorted in ascending X order.
- property states: States | None
Configuration for state-specific configuration to apply to the data series.
- Return type:
States
orNone
- property step: str | None
Whether to apply steps to the line. Defaults to
None
.Possible values are:
'left'
'center'
'right'
- property sticky_tracking: bool | None
Sticky tracking of mouse events.
When
True
, the (JavaScript)mouseOut
event on a series is not triggered until the mouse moves over another series, or out of the plot area.When
False
, the (JavaScript)mouseOut
event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.When
False
andPlotOptions.tooltip.shared()
is alsoFalse
, the tooltip will be hidden when moving the mouse between series.Defaults to
True
for line and area type series, but toFalse
for columns, pies, etc.Note
The boost module will force this option because of technical limitations.
- property threshold: int | float | Decimal | EnforcedNullType | None
The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to
0
.If
EnforcedNullType
, the columns extend from the padding Y axis minimum.- Return type:
numeric or
EnforcedNullType
orNone
- property tooltip: Tooltip | None
A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.
- Return type:
Tooltip
orNone
- property track_by_area: bool | None
When
True
, the whole area should respond to mouseover tooltips and other mouse or touch events. WhenFalse
, only the line responds to mouse/touch events. Defaults toFalse
.- Return type:
- property turbo_threshold: int | None
When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to
0
orNone
to disable.Defaults to
1000
.Note
In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.
- property type: str
Indicates the type of series that is represented by this instance.
Warning
This proprety is read-only!
- Return type:
- property visible: bool | None
If
True
, the series is initially visible. IfFalse
, the series is hidden by default. Defaults toTrue
.
- property x_axis: str | int | None
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
Options.x_axis()
array (starting at 0), or astr
indicating theid
of the axis to which the series should be connected. Defaults toNone
, which behaves as if the value were set to0
.
- property y_axis: str | int | None
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
Options.y_axis()
array (starting at 0), or astr
indicating theid
of the axis to which the series should be connected. Defaults toNone
, which behaves as if the value were set to0
.
- property z_index: int | float | Decimal | None
The visual z-index of the series. Defaults to
None
.- Return type:
numeric or
None
class: AreaRangeSeries
- class AreaRangeSeries(**kwargs)[source]
Options to apply to an AreaRange series. The area range series is a carteseian series with higher and lower values for each point along an X axis, where the area between the values is shaded.
Class Inheritance
- convert_to(series_type)
Creates a new series of
series_type
from the current series.- Parameters:
series_type (
str
orSeriesBase
-descended) – The series type that should be returned.
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
HighchartsSeriesConversionError
if the method is unable to convert (even losing some data) the original intoseries_type
.- Returns:
A new series of
series_type
, maintaining relevant properties and data from the original instance.- Return type:
series_type
SeriesBase
descendant- Raises:
HighchartsSeriesConversionError – if unable to convert (even after losing some data) the original instance into an instance of
series_type
.HighchartsValueError – if
series_type
is not a recognized series type
- copy(other=None, overwrite=True, **kwargs)
Copy the configuration settings from this instance to the
other
instance.- Parameters:
other (
HighchartsMeta
) – The target instance to which the properties of this instance should be copied. IfNone
, will create a new instance and populate it with properties copied fromself
. Defaults toNone
.overwrite (
bool
) – ifTrue
, properties inother
that are already set will be overwritten by their counterparts inself
. Defaults toTrue
.kwargs – Additional keyword arguments. Some special descendents of
HighchartsMeta
may have special implementations of this method which rely on additional keyword arguments.
- Returns:
A mutated version of
other
with new property values
- display(global_options=None, container=None, retries=5, interval=1000, chart_kwargs=None, options_kwargs=None)
Display the series in Jupyter Labs or Jupyter Notebooks.
- Parameters:
global_options (
SharedOptions
orNone
) – The shared options to use when rendering the chart. Defaults toNone
The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
None
, which applies the.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. TheChart
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.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.retries (
int
) – The number of times to retry rendering the chart. Used to avoid race conditions with the Highcharts script. Defaults to 5.interval (
int
) – The number of milliseconds to wait between retrying rendering the chart. Defaults to 1000 (1 seocnd).chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Raises:
if ipython is not available in the runtime environment
- classmethod from_array(value, series_kwargs=None)
Create one instance of the series with
data
populated fromvalue
.- Parameters:
value (iterable) –
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.series_kwargs (
dict
orNone
) – Optional keyword arguments to apply when instanting the series. Defaults toNone
.
- Returns:
An instance of the series type with
data
populated from the value.- Return type:
SeriesBase
descendent
- classmethod from_csv(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 series instances with
.data
populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:# 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 filenamesome-csv-file.csv
. Thex
values for each data point will be taken from the first (index 0) column in the CSV file. They
values will be taken from the fourth (index 3) column in the CSV file. And theid
values will be taken from a column whose header row is labeled'id'
(regardless of its index).- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –A
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.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:{ 'x': 0, 'y': [3, 5, 8] }
will return three series, each of which will have its
.x
value populated from the first column (index 0), and whose.y
values will be populated from the fourth, sixth, and ninth columns (indices 3, 5, and 8), respectively.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated from the CSV at theseries_index
position. Defaults toNone
, which returns all series generated from the CSV.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_csv_in_rows(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 series instance with a
.data
property populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:my_series = LineSeries.from_csv_in_rows('some-csv-file.csv')
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)
Construct an instance of the class from a
dict
object.
- classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)
Return a Python object representation of a Highcharts JavaScript object literal.
- Parameters:
as_str_or_file (
str
) – The JavaScript object literal, represented either as astr
or as a filename which contains the JS object literal.allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
._break_loop_on_failure (
bool
) – IfTrue
, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults toFalse
.
- Returns:
A Python object representation of the Highcharts JavaScript object literal.
- Return type:
HighchartsMeta
- classmethod from_json(as_json_or_file, allow_snake_case: bool = True)
Construct an instance of the class from a JSON string.
- Parameters:
as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
.
- Returns:
A Python objcet representation of
as_json
.- Return type:
HighchartsMeta
- classmethod from_pandas(df, property_map=None, series_kwargs=None, series_in_rows=False, series_index=None, **kwargs)
Create one or more series instances whose
.data
properties are populated from a pandasDataFrame
.# 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' })
- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.A
dict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.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:{ 'x': 'timestamp', 'y': ['value1', 'value2', 'value3'] }
will return three series, each of which will have its
.x
value populated from the column labeled'timestamp'
, and whose.y
values will be populated from the columns labeled'value1'
,'value2'
, and'value3'
, respectively.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameif pandas is not available in the runtime environment
- classmethod from_pandas_in_rows(df, series_kwargs=None, series_index=None, **kwargs)
Create a collection of series instances, one for each row in
df
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
Collection of 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
- Return type:
list
ofSeriesBase
-descendent instances
- classmethod from_pyspark(df, property_map, series_kwargs=None)
Create a series instance whose
.data
property is populated from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.
- Returns:
A series instance (descended from
SeriesBase
) with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
)- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- get_required_modules(include_extension=False) List[str]
Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.
- load_from_array(value)
Update the
.data
property with data loaded from an iterable invalue
.- Parameters:
value (iterable) –
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.
- load_from_csv(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
.data
property with a new value populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be: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 filenamesome-csv-file.csv
. As shown in EXAMPLE 1, unless otherwise specified, the.x
values for each data point will be taken from the first (index 0) column in the CSV file, while the.y
values will be taken from the second column.If the CSV has more than 2 columns, then this will throw an
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.x
values for each data point will be taken from the first (index 0) column in the CSV file. The.y
values will be taken from the fourth (index 3) column in the CSV file. And the.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.
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –An optional
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.series_index (
int
orNone
) – ifNone
, will raise aHighchartsCSVDeserializationError
if the CSV data contains more than one series and noproperty_column_map
is provided. Otherwise, will update the instance with the series found in the CSV at theseries_index
value. Defaults toNone
.**kwargs –
Remaining keyword arguments will be attempted on the resulting 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
- load_from_pandas(df, property_map=None, series_in_rows=False, series_index=None)
Replace the contents of the
.data
property with data points populated from a pandasDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
orNone
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.If supplied, return the series that Highcharts for Python generated from
df
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.Warning
If
None
and Highcharts for Python generates multiple series, then aHighchartsPandasDeserializationError
will be raised.
- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameHighchartsPandasDeserializationError – if
series_index
isNone
, and it is ambiguous which series generated from the dataframe should be usedif pandas is not available in the runtime environment
- load_from_pyspark(df, property_map)
Replaces the contents of the
.data
property with values from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.
- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- to_chart(chart_kwargs=None, options_kwargs=None)
Create a
Chart
instance containing the series instance.- Parameters:
chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Returns:
A
Chart
instance containing the series instance.- Return type:
- to_dict() dict
Generate a
dict
representation of the object compatible with the Highcharts JavaScript library.Note
The
dict
representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.
- to_js_literal(filename=None, encoding='utf-8', careful_validation=False) str | None
Return the object represented as a
str
containing the JavaScript object literal.- Parameters:
along the way using the esprima-python library. Defaults to
False
.Warning
Setting this value to
True
will significantly degrade serialization performance, though it may prove useful for debugging purposes.
- to_json(filename=None, encoding='utf-8', for_export: bool = False)
Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.
Note
This method will either return a standard
str
or abytes
object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be abytes
representation of the string.- Parameters:
filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to
None
encoding (
str
) – The character encoding to apply to the resulting object. Defaults to'utf-8'
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
A JSON representation of the object compatible with the Highcharts library.
- Return type:
- static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) dict
Remove keys from
untrimmed
whose values areNone
and convert values that have.to_dict()
methods.- Parameters:
untrimmed (
dict
) – Thedict
whose values may still beNone
or Python objects.to_json (
bool
) – IfTrue
, will remove all keys fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
Trimmed
dict
- Return type:
- static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)
Convert any
EnforcedNullType
values inuntrimmed
to'null'
.- Parameters:
untrimmed (iterable) – The iterable whose members may still be
None
or Python objects.to_json (
bool
) – IfTrue
, will remove all members fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Return type:
iterable
- property accessibility: TypeOptionsAccessibility | None
Accessibility options for a series.
- Return type:
TypeOptionsAccessibility
orNone
- property allow_point_select: bool | None
Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).
The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript)
getSelectedPoints()
function.And alternative way of selecting points is through dragging.
Defaults to
False
.
- property animation: bool | AnimationOptions | None
Enable or disable the initial animation when a series is displayed.
The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see
Chart.animation
and theanimation
parameter under the (JavaScript) API methods. The following properties are supported:defer
: The animation delay time in milliseconds.duration
: The duration of the animation in milliseconds.easing
: Can be a string reference to an easing function set on the Math object or a function.
Warning
Due to poor performance, animation is disabled in old IE browsers for several chart types.
- Return type:
AnimationOptions
orNone
- property animation_limit: int | float | Decimal | None
For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to
None
.For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set
animation_limit
tofloat("inf")
(which represents infinity).- Return type:
numeric or
None
- property boost_threshold: int | None
Set the point threshold for when a series should enter boost mode. Defaults to
5000
.Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.
To disable boosting on the series, set the
boost_threshold
to0
. Setting it to1
will force boosting.Note
The
AreaOptions.crop_threshold()
also affects this setting.When zooming in on a series that has fewer points than the
crop_threshold
, all points are rendered although outside the visible plot area, and theboost_threshold
won’t take effect.
- property class_name: str | None
The additional CSS class name to apply to the series’ graphical elements.
Note
This option is additive to the default class names - it does not replace them.
- property clip: bool | None
If
False
, allows the series to be rendered in the entire plot area. IfTrue
, constrains where the series can be rendered within the plot area. Defaults toTrue
.
- property color: str | Gradient | Pattern | None
The main color of the series.
In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the
Options.colors()
array.
- property color_axis: str | int | bool | None
When using dual or multiple color axes, this setting defines which color axis the particular series is connected to. It refers to either the
ColorAxis.id()
or the index of the axis in theColorAxis
array, with0
being the first. Set this option toFalse
to prevent a series from connecting to the default color axis.Defaults to
0
.
- property color_index: int | None
When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name
highcharts-color-{n}
.Tip
New in version Highcharts: (JS) v.11
With Highcharts (JS) v.11, using CSS variables of the form
--highcharts-color-{n}
make changing the color scheme very simple.Defaults to
None
.
- property color_key: str | None
Determines what data value should be used to calculate point color if
AreaOptions.color_axis()
is used.Note
Requires to set
min
andmax
if some custom point property is used or if approximation for data grouping is set to'sum'
.
- property connect_ends: bool | None
If
True
, connect the ends of a line series plot across the extremes. Defaults toNone
.Warning
Applies to polar charts only.
- property connect_nulls: bool | None
If
True
, connect a graph line across null points. IfFalse
, renders a gap between the points on either side of the null point. Defaults toFalse
.
- property crisp: bool | None
If
True
, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults toTrue
.Hint
In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting
crisp
toFalse
may look better, even though each column is rendered blurry.
- property crop_threshold: int | None
When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to
300
.The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.
- property cursor: str | None
The style of cursor to use when the user’s mouse hovers over the data series.
Acceptable values are:
'alias'
'all-scroll'
'auto'
'cell'
'col-resize'
'context-menu'
'copy'
'crosshair'
'default'
'e-resize'
'ew-resize'
'grab'
'grabbing'
'help'
'move'
'n-resize'
'ne-resize'
'nesw-resize'
'no-drop'
'none'
'not-allowed'
'ns-resize'
'nw-resize'
'nwse-resize'
'pointer'
'progress'
'row-resize'
's-resize'
'se-resize'
'sw-resize'
'text'
'vertical-text'
'w-resize'
'wait'
'zoom-in'
'zoom-out'
- property custom: JavaScriptDict | None
A reserved subspace to store options and values for customized functionality.
Here you can add additional data for your own event callbacks and formatter callbacks.
- property dash_style: str | None
Name of the dash style to use for the graph, or for some series types the outline of each shape.
Accepts one of the following values:
‘Dash’,
‘DashDot’,
‘Dot’,
‘LongDash’,
‘LongDashDot’,
‘LongDashDotDot’,
‘ShortDash’,
‘ShortDashDot’,
‘ShortDashDotDot’,
‘ShortDot’,
‘Solid’
- property data: List[RangeData] | RangeDataCollection | None
Collection of data that represents the series. Defaults to
None
.While the series type returns a collection of
RangeData
instances, it accepts as input two different types of data:area_range_series = AreaRangeSeries() # Category X-axis area_range_series.data = [ ['Category A', 8, 3], ['Category B', 1, 1], ['Category C', 6, 8] ] # Numerical X-axis area_range_series.data = [ [0, 8, 3], [1, 1, 1], [2, 6, 8] ]
A three-dimensional collection of numerical values. Each member of the collection will be interpreted as an
x
value, alow
value, and ahigh
value.The
x
value can be astr
,date
,datetime
, or numeric value.Note
If the
x
value is astr
, it will be interpreted as the name of the data point.area_range_series = AreaRangeSeries() area_series.data = [ [8, 3], [1, 1], [6, 8] ]
A two-dimensional collection of values. Each member of the collection will be interpreted as an
low
andhigh
value. Thex
values are automatically inferred:If
AreaSeries.point_start()
isNone
,x
values will begin at0
. Otherwise, they will start atpoint_start
.If
AreaSeries.point_interval()
isNone
,x
values will be incremented by1
. Otherwise, they will be incremented by the value ofpoint_interval
.A one-dimensional collection of
RangeData
objects.
- property data_labels: DataLabel | List[DataLabel] | None
Options for the series data labels, appearing next to each data point.
Note
To have multiple data labels per data point, you can also supply a collection of
DataLabel
configuration settings.
- property data_sorting: DataSorting | None
Options for the series data sorting.
- Return type:
DataSorting
orNone
- property description: str | None
A description of the series to add to the screen reader information about the series.
- property drag_drop: DragDropOptions | None
The draggable-points module allows points to be moved around or modified in the chart.
In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:
point.dragStart
point.drag
point.drop
- Return type:
DragDropOptions
orNone
- property enable_mouse_tracking: bool | None
If
True
, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). IfFalse
, disables mouse tracking for the series (which can help performance). Defaults toTrue
.
- property events: SeriesEvents | None
General event handlers for the series items.
Note
These event hooks can also be attached to the series at run time using the (JavaScript)
Highcharts.addEvent()
function.- Return type:
SeriesEvents
orNone
- property fill_color: str | Gradient | Pattern | EnforcedNullType | None
Fill color or gradient for the area. When
EnforcedNullType
, the series’ color is used with the series’fill_opacity
.- Return type:
None
,Gradient
,Pattern
, orEnforcedNullType
- property fill_opacity: int | float | Decimal | None
Fill opacity for the area. Defaults to
0.75
.When you set an explicit
fill_color
, thefill_opacity
is not applied. Instead, you should define the opacity in thefill_color
with an rgba color definition.The
fill_opacity
setting, also the default setting, overrides the alpha component of the color setting.- Return type:
numeric or
None
- property find_nearest_point_by: str | None
Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.
If
None
, defaults to'xy'
for scatter series and'x'
for most other series. If the data has duplicate x-values, it is recommended to set this to'xy'
to allow hovering over all points.Applies only to series types using nearest neighbor search (not direct hover) for tooltip.
- property get_extremes_from_all: bool | None
If
True
, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.Warning
Applies to Cartesian series only.
- property id: str | None
An id for the series. Defaults to
None
.Hint
This can be used (in JavaScript) after render time to get a pointer to the series object through
chart.get()
.
- property inactive_other_points: bool | None
- If
True
, highlights only the hovered point and fades the other points. Defaults to
False
.Warning
Scatter-type series require enabling the ‘inactive’ marker state and adjusting opacity. This approach could affect performance
with large datasets.
- If
- property include_in_data_export: bool | None
If
False
, will prevent the data series from being included in any form of data export. Defaults toTrue
.
- property index: int | None
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 toNone
.
- property keys: List[str] | None
An array specifying which option maps to which key in the data point array.
This makes it convenient to work with unstructured data arrays from different sources.
- property label: SeriesLabel | None
Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.
Note
The series labels currently work with series types having a graph or an area.
- Return type:
SeriesLabel
orNone
- property legend_index: int | None
The sequential index for the series in the legend. Defaults to
None
.
- property legend_symbol: str | None
The type of legend symbol to render for the series. Accepts either
'lineMarker'
,'areaMarker'
, or'rectangle'
. Defaults to'rectangle'
.- Return type:
- property line_color: str | Gradient | Pattern | None
A separate color for the graph line. When
None
, by default the line takes the color of the series, but theline_color
setting allows setting a separate color for the line without altering thefill_color
.
- property line_width: int | float | Decimal | None
Pixel width of the graph line. Defaults to
2
.- Return type:
numeric or
None
- property linecap: str | None
The SVG value used for the
stroke-linecap
andstroke-linejoin
of a line graph. Defaults to'round'
, which means that lines are rounded in the ends and bends.
- property linked_to: str | None
The id of another series to link to.
Hint
The value can be
':previous'
to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.Note
If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.
- property low_marker: Marker | None
Options for the point markers of line-like series.
Properties like
fill_color
,line_color
andline_width
define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.- Return type:
Marker
orNone
- property marker: Marker | None
Options for the point markers of line-like series.
Properties like
fill_color
,line_color
andline_width
define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.- Return type:
Marker
orNone
- property name: str | None
The name of the series as shown in the legend, tooltip, etc. Defaults to
None
.
- property negative_color: str | Gradient | Pattern | None
The color for the parts of the graph or points that are below the
AreaOptions.threshold()
.Note
Zones
take precedence over the negative color. Usingnegative_color
is equivalent to applying a zone with value of 0.
- property negative_fill_color: str | Gradient | Pattern | None
A separate color for the negative part of the area.
- property on_point: OnPointOptions | None
Options for the Series on point feature, which is currently only supported by
pie
andsunburst
chargs.- Return type:
OnPointOptions
orNone
- property opacity: float | None
Opacity of a series parts: line, fill (e.g. area), and labels.
- Return type:
- property point_description_format: str | None
A format string to use instead of the default for point descriptions on the series. Defaults to
None
.Note
Overrides the chart-wide configuration, as applicable.
- property point_description_formatter: CallbackFunction | None
Same as for
Accessibility.series.description_formatter()
, only for an individual series. Overrides the chart-wide configuration.- Return type:
CallbackFunction
orNone
- property point_interval: int | float | Decimal | None
If no x values are given for the points in a series,
point_interval
defines the interval of the x values. Defaults to1
.For example, if a series contains one value every decade starting from year 0, set
point_interval
to10
. In true datetime axes, thepoint_interval
is set in milliseconds.Hint
point_interval
can be also be combined withpoint_interval_unit
to draw irregular time intervals.Note
If combined with
relative_x_value
, an x value can be set on each point, and thepoint_interval
is added x times to thepoint_start
setting.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- Return type:
numeric or
None
- property point_interval_unit: str | None
On datetime series, this allows for setting the
point_interval
to irregular time units, day, month, and year.A day is usually the same as 24 hours, but
point_interval_unit
also takes the DST crossover into consideration when dealing with local time.Combine this option with
point_interval
to draw weeks, quarters, 6 month periods, 10 year periods, etc.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- property point_placement: int | float | Decimal | str | None
Used to determine the placement of the point in relation to tick marks on the X axis. Defaults to
None
, which behaves as undefined in cartesian charts, and"between"
in polar charts.Accepts possible values:
'on'
- where the point will not create any padding of the X axis. In a polar column chart this means that the first column points directly north."between"
- where the columns will be laid out between ticks. This is useful for example for visualising an amount between two points in time or in a certain sector of a polar chart.a numeric value - where
0
is on the axis value,-0.5
is between this value and the previous, and0.5
is between this value and the next. Unlike the textual options, numeric point placement options won’t affect axis padding.
Warning
Requires
point_range
to work. For column series this is computed, but for line-type series it needs to be set.Note
For the xrange series type and gantt charts, if the Y axis is a category axis, the
point_placement
applies to the Y axis rather than the (typically datetime) X axis.
- property point_start: int | float | Decimal | None
If no x values are given for the points in a series,
point_start
defines on what value to start. For example, if a series contains one yearly value starting from 1945, setpoint_start
to1945
. Defaults to0
.Note
If combined with
relative_x_value
, an x value can be set on each point. The x value from the point options is multiplied bypoint_interval
and added topoint_start
to produce a modified x value.- Return type:
numeric or
None
- property relative_x_value: bool | None
When
True
, X values in the data set are relative to the currentpoint_start
,point_interval
, andpoint_interval_unit
settings. This allows compression of the data for datasets with irregular X values. Defaults toFalse
.The real X values are computed on the formula
f(x) = ax + b
, wherea
is thepoint_interval
(optionally with a time unit given bypoint_interval_unit
), andb
is thepoint_start
.
- property selected: bool | None
If
True
, the series is selected initially (by default, without user interaction). Defaults toFalse
.Note
If
GenericTypeOptions.show_checkbox()
isTrue
, then the checkbox will be checked ifselected
isTrue
.
- property shadow: bool | ShadowOptions | None
Configuration for the shadow to apply to the tooltip. Defaults to
False
.If
False
, no shadow is applied.- Returns:
The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.
- Return type:
bool
orShadowOptions
- property show_checkbox: bool | None
If
True
, a checkbox is displayed next to the legend item to allow selecting the series.Note
The state of the checkbox is controlled by the
GenericTypeOptions.selected()
property.
- property show_in_legend: bool | None
Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.
If
True
, the accessibility module will skip past this series when executing keyboard navigation.
- property soft_threshold: bool | None
When
True
, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults toTrue
.For example, if
False
, a series of0, 1, 2, 3
will make the Y axis show negative values according to themin_padidng
option. IfTrue
, the Y axis starts at 0.- Return type:
- property sonification: SeriesSonification | None
Sonification configuration for the series type/series.
- Return type:
- property stack: str | None
Indicates the “stack” into which the series should be grouped, if the chart groups series into stacks. Defaults to
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.
- property stacking: str | None
Whether to stack the values of each series on top of each other. Defaults to
None
.Acceptable values are:
None
to disable stacking,"normal"
to stack by value or"percent"
'stream'
(for streamgraph series type only)'overlap'
(for waterfall series type only)
Note
When stacking is enabled, data must be sorted in ascending X order.
- property states: States | None
Configuration for state-specific configuration to apply to the data series.
- Return type:
States
orNone
- property step: str | None
Whether to apply steps to the line. Defaults to
None
.Possible values are:
'left'
'center'
'right'
- property sticky_tracking: bool | None
Sticky tracking of mouse events.
When
True
, the (JavaScript)mouseOut
event on a series is not triggered until the mouse moves over another series, or out of the plot area.When
False
, the (JavaScript)mouseOut
event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.When
False
andPlotOptions.tooltip.shared()
is alsoFalse
, the tooltip will be hidden when moving the mouse between series.Defaults to
True
for line and area type series, but toFalse
for columns, pies, etc.Note
The boost module will force this option because of technical limitations.
- property threshold: int | float | Decimal | EnforcedNullType | None
The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to
0
.If
EnforcedNullType
, the columns extend from the padding Y axis minimum.- Return type:
numeric or
EnforcedNullType
orNone
- property tooltip: Tooltip | None
A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.
- Return type:
Tooltip
orNone
- property track_by_area: bool | None
When
True
, the whole area should respond to mouseover tooltips and other mouse or touch events. WhenFalse
, only the line responds to mouse/touch events. Defaults toFalse
.- Return type:
- property turbo_threshold: int | None
When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to
0
orNone
to disable.Defaults to
1000
.Note
In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.
- property type: str
Indicates the type of series that is represented by this instance.
Warning
This proprety is read-only!
- Return type:
- property visible: bool | None
If
True
, the series is initially visible. IfFalse
, the series is hidden by default. Defaults toTrue
.
- property x_axis: str | int | None
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
Options.x_axis()
array (starting at 0), or astr
indicating theid
of the axis to which the series should be connected. Defaults toNone
, which behaves as if the value were set to0
.
- property y_axis: str | int | None
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
Options.y_axis()
array (starting at 0), or astr
indicating theid
of the axis to which the series should be connected. Defaults toNone
, which behaves as if the value were set to0
.
- property z_index: int | float | Decimal | None
The visual z-index of the series. Defaults to
None
.- Return type:
numeric or
None
class: AreaSplineSeries
- class AreaSplineSeries(**kwargs)[source]
Options to apply to an AreaSpline series. The area spline series is an area series where the graph between the points is smoothed into a spline.
Class Inheritance
- convert_to(series_type)
Creates a new series of
series_type
from the current series.- Parameters:
series_type (
str
orSeriesBase
-descended) – The series type that should be returned.
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
HighchartsSeriesConversionError
if the method is unable to convert (even losing some data) the original intoseries_type
.- Returns:
A new series of
series_type
, maintaining relevant properties and data from the original instance.- Return type:
series_type
SeriesBase
descendant- Raises:
HighchartsSeriesConversionError – if unable to convert (even after losing some data) the original instance into an instance of
series_type
.HighchartsValueError – if
series_type
is not a recognized series type
- copy(other=None, overwrite=True, **kwargs)
Copy the configuration settings from this instance to the
other
instance.- Parameters:
other (
HighchartsMeta
) – The target instance to which the properties of this instance should be copied. IfNone
, will create a new instance and populate it with properties copied fromself
. Defaults toNone
.overwrite (
bool
) – ifTrue
, properties inother
that are already set will be overwritten by their counterparts inself
. Defaults toTrue
.kwargs – Additional keyword arguments. Some special descendents of
HighchartsMeta
may have special implementations of this method which rely on additional keyword arguments.
- Returns:
A mutated version of
other
with new property values
- display(global_options=None, container=None, retries=5, interval=1000, chart_kwargs=None, options_kwargs=None)
Display the series in Jupyter Labs or Jupyter Notebooks.
- Parameters:
global_options (
SharedOptions
orNone
) – The shared options to use when rendering the chart. Defaults toNone
The ID to apply to the HTML container when rendered in Jupyter Labs. Defaults to
None
, which applies the.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. TheChart
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.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.retries (
int
) – The number of times to retry rendering the chart. Used to avoid race conditions with the Highcharts script. Defaults to 5.interval (
int
) – The number of milliseconds to wait between retrying rendering the chart. Defaults to 1000 (1 seocnd).chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Raises:
if ipython is not available in the runtime environment
- classmethod from_array(value, series_kwargs=None)
Create one instance of the series with
data
populated fromvalue
.- Parameters:
value (iterable) –
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.series_kwargs (
dict
orNone
) – Optional keyword arguments to apply when instanting the series. Defaults toNone
.
- Returns:
An instance of the series type with
data
populated from the value.- Return type:
SeriesBase
descendent
- classmethod from_csv(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 series instances with
.data
populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:# 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 filenamesome-csv-file.csv
. Thex
values for each data point will be taken from the first (index 0) column in the CSV file. They
values will be taken from the fourth (index 3) column in the CSV file. And theid
values will be taken from a column whose header row is labeled'id'
(regardless of its index).- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –A
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.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:{ 'x': 0, 'y': [3, 5, 8] }
will return three series, each of which will have its
.x
value populated from the first column (index 0), and whose.y
values will be populated from the fourth, sixth, and ninth columns (indices 3, 5, and 8), respectively.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated from the CSV at theseries_index
position. Defaults toNone
, which returns all series generated from the CSV.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_csv_in_rows(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 series instance with a
.data
property populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be:my_series = LineSeries.from_csv_in_rows('some-csv-file.csv')
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created from the CSV file instead.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsCSVDeserializationError – if
property_column_map
references CSV columns by their label, but the CSV data does not contain a header row
- classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)
Construct an instance of the class from a
dict
object.
- classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)
Return a Python object representation of a Highcharts JavaScript object literal.
- Parameters:
as_str_or_file (
str
) – The JavaScript object literal, represented either as astr
or as a filename which contains the JS object literal.allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
._break_loop_on_failure (
bool
) – IfTrue
, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults toFalse
.
- Returns:
A Python object representation of the Highcharts JavaScript object literal.
- Return type:
HighchartsMeta
- classmethod from_json(as_json_or_file, allow_snake_case: bool = True)
Construct an instance of the class from a JSON string.
- Parameters:
as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (
bool
) – IfTrue
, interpretssnake_case
keys as equivalent tocamelCase
keys. Defaults toTrue
.
- Returns:
A Python objcet representation of
as_json
.- Return type:
HighchartsMeta
- classmethod from_pandas(df, property_map=None, series_kwargs=None, series_in_rows=False, series_index=None, **kwargs)
Create one or more series instances whose
.data
properties are populated from a pandasDataFrame
.# 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' })
- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.A
dict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.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:{ 'x': 'timestamp', 'y': ['value1', 'value2', 'value3'] }
will return three series, each of which will have its
.x
value populated from the column labeled'timestamp'
, and whose.y
values will be populated from the columns labeled'value1'
,'value2'
, and'value3'
, respectively.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.False
.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
A series instance (descended from
SeriesBase
) ORlist
of series instances with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
) orSeriesBase
-descendent- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameif pandas is not available in the runtime environment
- classmethod from_pandas_in_rows(df, series_kwargs=None, series_index=None, **kwargs)
Create a collection of series instances, one for each row in
df
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.series_index (
int
, slice, orNone
) – If supplied, return the series that Highcharts for Python generated fromdf
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.**kwargs –
Remaining keyword arguments will be attempted on the resulting series instance and the data points it contains.
- Returns:
Collection of 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
- Return type:
list
ofSeriesBase
-descendent instances
- classmethod from_pyspark(df, property_map, series_kwargs=None)
Create a series instance whose
.data
property is populated from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.series_kwargs (
dict
) –An optional
dict
containing keyword arguments that should be used when instantiating the series instance. Defaults toNone
.Warning
If
series_kwargs
contains adata
key, its value will be overwritten. Thedata
value will be created fromdf
instead.
- Returns:
A series instance (descended from
SeriesBase
) with its.data
property populated from the data indf
.- Return type:
list
of series instances (descended fromSeriesBase
)- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- get_required_modules(include_extension=False) List[str]
Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.
- load_from_array(value)
Update the
.data
property with data loaded from an iterable invalue
.- Parameters:
value (iterable) –
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.
- load_from_csv(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
.data
property with a new value populated from data in a CSV string or file.Note
For an example
LineSeries
, the minimum code required would be: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 filenamesome-csv-file.csv
. As shown in EXAMPLE 1, unless otherwise specified, the.x
values for each data point will be taken from the first (index 0) column in the CSV file, while the.y
values will be taken from the second column.If the CSV has more than 2 columns, then this will throw an
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.x
values for each data point will be taken from the first (index 0) column in the CSV file. The.y
values will be taken from the fourth (index 3) column in the CSV file. And the.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.
- Parameters:
as_string_or_file (
str
or Path-like) –The CSV data to use to pouplate data. Accepts either the raw CSV data as a
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 (
None
).property_column_map (
dict
orNone
) –An optional
dict
used to indicate which data point property should be set to which CSV column. The keys in thedict
should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or astr
indicating the label for the CSV column. Defaults toNone
.has_header_row (
bool
) – IfTrue
, indicates that the first row ofas_string_or_file
contains column labels, rather than actual data. Defaults toTrue
.delimiter (
str
) – The delimiter used between columns. Defaults to,
.wrapper_character (
str
) – The string used to wrap string values when wrapping is applied. Defaults to'
.null_text (
str
) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.line_terminator (
str
) – The string used to indicate the end of a line/record in the CSV data. Defaults to'\r\n'
.line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to
'\r\n'
.Note
The Python
csv
currently ignores theline_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.wrap_all_strings (
bool
) –If
True
, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults toFalse
.double_wrapper_character_when_nested (
bool
) – IfTrue
, quote character is doubled when appearing within a string value. IfFalse
, theescape_character
is used to prefix quotation marks. Defaults toFalse
.escape_character (
str
) – 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).series_in_rows (
bool
) – ifTrue
, 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 toFalse
.series_index (
int
orNone
) – ifNone
, will raise aHighchartsCSVDeserializationError
if the CSV data contains more than one series and noproperty_column_map
is provided. Otherwise, will update the instance with the series found in the CSV at theseries_index
value. Defaults toNone
.**kwargs –
Remaining keyword arguments will be attempted on the resulting 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
- load_from_pandas(df, property_map=None, series_in_rows=False, series_index=None)
Replace the contents of the
.data
property with data points populated from a pandasDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
orNone
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column. Defaults toNone
.series_in_rows (
bool
) – ifTrue
, 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 toFalse
.If supplied, return the series that Highcharts for Python generated from
df
at theseries_index
value. Defaults toNone
, which returns all series generated fromdf
.Warning
If
None
and Highcharts for Python generates multiple series, then aHighchartsPandasDeserializationError
will be raised.
- Raises:
HighchartsPandasDeserializationError – if
property_map
references a column that does not exist in the data frameHighchartsPandasDeserializationError – if
series_index
isNone
, and it is ambiguous which series generated from the dataframe should be usedif pandas is not available in the runtime environment
- load_from_pyspark(df, property_map)
Replaces the contents of the
.data
property with values from a PySparkDataFrame
.- Parameters:
df (
DataFrame
) – TheDataFrame
from which data should be loaded.property_map (
dict
) – Adict
used to indicate which data point property should be set to which column indf
. The keys in thedict
should correspond to properties in the data point class, while the value should indicate the label for theDataFrame
column.
- Raises:
HighchartsPySparkDeserializationError – if
property_map
references a column that does not exist in the data frameif PySpark is not available in the runtime environment
- to_chart(chart_kwargs=None, options_kwargs=None)
Create a
Chart
instance containing the series instance.- Parameters:
chart_kwargs (
dict
) – Optional keyword arguments to use when constructing theChart
instance. Defaults toNone
.options_kwargs (
dict
) –Optional keyword arguments to use when constructing the chart’s
HighchartsOptions
object. Defaults toNone
.Warning
If your
chart_kwargs
contains anoptions
key, its value will be overwritten if you supplyoptions_kwargs
.
- Returns:
A
Chart
instance containing the series instance.- Return type:
- to_dict() dict
Generate a
dict
representation of the object compatible with the Highcharts JavaScript library.Note
The
dict
representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.
- to_js_literal(filename=None, encoding='utf-8', careful_validation=False) str | None
Return the object represented as a
str
containing the JavaScript object literal.- Parameters:
along the way using the esprima-python library. Defaults to
False
.Warning
Setting this value to
True
will significantly degrade serialization performance, though it may prove useful for debugging purposes.
- to_json(filename=None, encoding='utf-8', for_export: bool = False)
Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.
Note
This method will either return a standard
str
or abytes
object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be abytes
representation of the string.- Parameters:
filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to
None
encoding (
str
) – The character encoding to apply to the resulting object. Defaults to'utf-8'
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
A JSON representation of the object compatible with the Highcharts library.
- Return type:
- static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) dict
Remove keys from
untrimmed
whose values areNone
and convert values that have.to_dict()
methods.- Parameters:
untrimmed (
dict
) – Thedict
whose values may still beNone
or Python objects.to_json (
bool
) – IfTrue
, will remove all keys fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Returns:
Trimmed
dict
- Return type:
- static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)
Convert any
EnforcedNullType
values inuntrimmed
to'null'
.- Parameters:
untrimmed (iterable) – The iterable whose members may still be
None
or Python objects.to_json (
bool
) – IfTrue
, will remove all members fromuntrimmed
that are not serializable to JSON. Defaults toFalse
.context (
str
orNone
) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults toNone
.for_export (
bool
) – IfTrue
, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults toFalse
.
- Return type:
iterable
- property accessibility: TypeOptionsAccessibility | None
Accessibility options for a series.
- Return type:
TypeOptionsAccessibility
orNone
- property allow_point_select: bool | None
Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).
The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript)
getSelectedPoints()
function.And alternative way of selecting points is through dragging.
Defaults to
False
.
- property animation: bool | AnimationOptions | None
Enable or disable the initial animation when a series is displayed.
The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see
Chart.animation
and theanimation
parameter under the (JavaScript) API methods. The following properties are supported:defer
: The animation delay time in milliseconds.duration
: The duration of the animation in milliseconds.easing
: Can be a string reference to an easing function set on the Math object or a function.
Warning
Due to poor performance, animation is disabled in old IE browsers for several chart types.
- Return type:
AnimationOptions
orNone
- property animation_limit: int | float | Decimal | None
For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to
None
.For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set
animation_limit
tofloat("inf")
(which represents infinity).- Return type:
numeric or
None
- property boost_threshold: int | None
Set the point threshold for when a series should enter boost mode. Defaults to
5000
.Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.
To disable boosting on the series, set the
boost_threshold
to0
. Setting it to1
will force boosting.Note
The
AreaOptions.crop_threshold()
also affects this setting.When zooming in on a series that has fewer points than the
crop_threshold
, all points are rendered although outside the visible plot area, and theboost_threshold
won’t take effect.
- property class_name: str | None
The additional CSS class name to apply to the series’ graphical elements.
Note
This option is additive to the default class names - it does not replace them.
- property clip: bool | None
If
False
, allows the series to be rendered in the entire plot area. IfTrue
, constrains where the series can be rendered within the plot area. Defaults toTrue
.
- property color: str | Gradient | Pattern | None
The main color of the series.
In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the
Options.colors()
array.
- property color_axis: str | int | bool | None
When using dual or multiple color axes, this setting defines which color axis the particular series is connected to. It refers to either the
ColorAxis.id()
or the index of the axis in theColorAxis
array, with0
being the first. Set this option toFalse
to prevent a series from connecting to the default color axis.Defaults to
0
.
- property color_index: int | None
When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name
highcharts-color-{n}
.Tip
New in version Highcharts: (JS) v.11
With Highcharts (JS) v.11, using CSS variables of the form
--highcharts-color-{n}
make changing the color scheme very simple.Defaults to
None
.
- property color_key: str | None
Determines what data value should be used to calculate point color if
AreaOptions.color_axis()
is used.Note
Requires to set
min
andmax
if some custom point property is used or if approximation for data grouping is set to'sum'
.
- property connect_ends: bool | None
If
True
, connect the ends of a line series plot across the extremes. Defaults toNone
.Warning
Applies to polar charts only.
- property connect_nulls: bool | None
If
True
, connect a graph line across null points. IfFalse
, renders a gap between the points on either side of the null point. Defaults toFalse
.
- property crisp: bool | None
If
True
, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults toTrue
.Hint
In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting
crisp
toFalse
may look better, even though each column is rendered blurry.
- property crop_threshold: int | None
When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to
300
.The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.
- property cursor: str | None
The style of cursor to use when the user’s mouse hovers over the data series.
Acceptable values are:
'alias'
'all-scroll'
'auto'
'cell'
'col-resize'
'context-menu'
'copy'
'crosshair'
'default'
'e-resize'
'ew-resize'
'grab'
'grabbing'
'help'
'move'
'n-resize'
'ne-resize'
'nesw-resize'
'no-drop'
'none'
'not-allowed'
'ns-resize'
'nw-resize'
'nwse-resize'
'pointer'
'progress'
'row-resize'
's-resize'
'se-resize'
'sw-resize'
'text'
'vertical-text'
'w-resize'
'wait'
'zoom-in'
'zoom-out'
- property custom: JavaScriptDict | None
A reserved subspace to store options and values for customized functionality.
Here you can add additional data for your own event callbacks and formatter callbacks.
- property dash_style: str | None
Name of the dash style to use for the graph, or for some series types the outline of each shape.
Accepts one of the following values:
‘Dash’,
‘DashDot’,
‘Dot’,
‘LongDash’,
‘LongDashDot’,
‘LongDashDotDot’,
‘ShortDash’,
‘ShortDashDot’,
‘ShortDashDotDot’,
‘ShortDot’,
‘Solid’
- property data: List[CartesianData] | CartesianDataCollection | None
Collection of data that represents the series. Defaults to
None
.While the series type returns a collection of
CartesianData
instances, it accepts as input three different types of data:area_series = AreaSeries() area_series.data = [0, 5, 3, 5]
A one-dimensional collection of numerical values. Each member of the collection will be interpreted as a
y
-value, with its correspondingx
value automatically determined.If
AreaSeries.point_start()
isNone
,x
values will begin at0
. Otherwise, they will start atpoint_start
.If
AreaSeries.point_interval()
isNone
,x
values will be incremented by1
. Otherwise, they will be incremented by the value ofpoint_interval
.area_series = AreaSeries() # Category X-axis area_series.data = [ ['Category A', 0], ['Category B', 5], ['Category C', 3], ['Category D', 5] ] # Numerical X-axis area_series.data = [ [9, 0], [1, 5], [2, 3], [7, 5] ]
A two-dimensional collection of values. Each member of the collection will be interpreted as an
x
andy
pair. Thex
value can be astr
,date
,datetime
, or numeric value.Note
If the
x
value is astr
, it will be interpreted as the name of the data point.A one-dimensional collection of
CartesianData
objects.
- property data_labels: DataLabel | List[DataLabel] | None
Options for the series data labels, appearing next to each data point.
Note
To have multiple data labels per data point, you can also supply a collection of
DataLabel
configuration settings.
- property data_sorting: DataSorting | None
Options for the series data sorting.
- Return type:
DataSorting
orNone
- property description: str | None
A description of the series to add to the screen reader information about the series.
- property drag_drop: DragDropOptions | None
The draggable-points module allows points to be moved around or modified in the chart.
In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:
point.dragStart
point.drag
point.drop
- Return type:
DragDropOptions
orNone
- property enable_mouse_tracking: bool | None
If
True
, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). IfFalse
, disables mouse tracking for the series (which can help performance). Defaults toTrue
.
- property events: SeriesEvents | None
General event handlers for the series items.
Note
These event hooks can also be attached to the series at run time using the (JavaScript)
Highcharts.addEvent()
function.- Return type:
SeriesEvents
orNone
- property fill_color: str | Gradient | Pattern | EnforcedNullType | None
Fill color or gradient for the area. When
EnforcedNullType
, the series’ color is used with the series’fill_opacity
.- Return type:
None
,Gradient
,Pattern
, orEnforcedNullType
- property fill_opacity: int | float | Decimal | None
Fill opacity for the area. Defaults to
0.75
.When you set an explicit
fill_color
, thefill_opacity
is not applied. Instead, you should define the opacity in thefill_color
with an rgba color definition.The
fill_opacity
setting, also the default setting, overrides the alpha component of the color setting.- Return type:
numeric or
None
- property find_nearest_point_by: str | None
Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.
If
None
, defaults to'xy'
for scatter series and'x'
for most other series. If the data has duplicate x-values, it is recommended to set this to'xy'
to allow hovering over all points.Applies only to series types using nearest neighbor search (not direct hover) for tooltip.
- property get_extremes_from_all: bool | None
If
True
, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.Warning
Applies to Cartesian series only.
- property id: str | None
An id for the series. Defaults to
None
.Hint
This can be used (in JavaScript) after render time to get a pointer to the series object through
chart.get()
.
- property inactive_other_points: bool | None
- If
True
, highlights only the hovered point and fades the other points. Defaults to
False
.Warning
Scatter-type series require enabling the ‘inactive’ marker state and adjusting opacity. This approach could affect performance
with large datasets.
- If
- property include_in_data_export: bool | None
If
False
, will prevent the data series from being included in any form of data export. Defaults toTrue
.
- property index: int | None
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 toNone
.
- property keys: List[str] | None
An array specifying which option maps to which key in the data point array.
This makes it convenient to work with unstructured data arrays from different sources.
- property label: SeriesLabel | None
Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.
Note
The series labels currently work with series types having a graph or an area.
- Return type:
SeriesLabel
orNone
- property legend_index: int | None
The sequential index for the series in the legend. Defaults to
None
.
- property legend_symbol: str | None
The type of legend symbol to render for the series. Accepts either
'lineMarker'
,'areaMarker'
, or'rectangle'
. Defaults to'rectangle'
.- Return type:
- property line_color: str | Gradient | Pattern | None
A separate color for the graph line. When
None
, by default the line takes the color of the series, but theline_color
setting allows setting a separate color for the line without altering thefill_color
.
- property line_width: int | float | Decimal | None
Pixel width of the graph line. Defaults to
2
.- Return type:
numeric or
None
- property linecap: str | None
The SVG value used for the
stroke-linecap
andstroke-linejoin
of a line graph. Defaults to'round'
, which means that lines are rounded in the ends and bends.
- property linked_to: str | None
The id of another series to link to.
Hint
The value can be
':previous'
to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.Note
If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.
- property marker: Marker | None
Options for the point markers of line-like series.
Properties like
fill_color
,line_color
andline_width
define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.- Return type:
Marker
orNone
- property name: str | None
The name of the series as shown in the legend, tooltip, etc. Defaults to
None
.
- property negative_color: str | Gradient | Pattern | None
The color for the parts of the graph or points that are below the
AreaOptions.threshold()
.Note
Zones
take precedence over the negative color. Usingnegative_color
is equivalent to applying a zone with value of 0.
- property negative_fill_color: str | Gradient | Pattern | None
A separate color for the negative part of the area.
- property on_point: OnPointOptions | None
Options for the Series on point feature, which is currently only supported by
pie
andsunburst
chargs.- Return type:
OnPointOptions
orNone
- property opacity: float | None
Opacity of a series parts: line, fill (e.g. area), and labels.
- Return type:
- property point_description_format: str | None
A format string to use instead of the default for point descriptions on the series. Defaults to
None
.Note
Overrides the chart-wide configuration, as applicable.
- property point_description_formatter: CallbackFunction | None
Same as for
Accessibility.series.description_formatter()
, only for an individual series. Overrides the chart-wide configuration.- Return type:
CallbackFunction
orNone
- property point_interval: int | float | Decimal | None
If no x values are given for the points in a series,
point_interval
defines the interval of the x values. Defaults to1
.For example, if a series contains one value every decade starting from year 0, set
point_interval
to10
. In true datetime axes, thepoint_interval
is set in milliseconds.Hint
point_interval
can be also be combined withpoint_interval_unit
to draw irregular time intervals.Note
If combined with
relative_x_value
, an x value can be set on each point, and thepoint_interval
is added x times to thepoint_start
setting.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- Return type:
numeric or
None
- property point_interval_unit: str | None
On datetime series, this allows for setting the
point_interval
to irregular time units, day, month, and year.A day is usually the same as 24 hours, but
point_interval_unit
also takes the DST crossover into consideration when dealing with local time.Combine this option with
point_interval
to draw weeks, quarters, 6 month periods, 10 year periods, etc.Warning
This options applies to the series data, not the interval of the axis ticks, which is independent.
- property point_placement: int | float | Decimal | str | None
Used to determine the placement of the point in relation to tick marks on the X axis. Defaults to
None
, which behaves as undefined in cartesian charts, and"between"
in polar charts.Accepts possible values:
'on'
- where the point will not create any padding of the X axis. In a polar column chart this means that the first column points directly north."between"
- where the columns will be laid out between ticks. This is useful for example for visualising an amount between two points in time or in a certain sector of a polar chart.a numeric value - where
0
is on the axis value,-0.5
is between this value and the previous, and0.5
is between this value and the next. Unlike the textual options, numeric point placement options won’t affect axis padding.
Warning
Requires
point_range
to work. For column series this is computed, but for line-type series it needs to be set.Note
For the xrange series type and gantt charts, if the Y axis is a category axis, the
point_placement
applies to the Y axis rather than the (typically datetime) X axis.
- property point_start: int | float | Decimal | None
If no x values are given for the points in a series,
point_start
defines on what value to start. For example, if a series contains one yearly value starting from 1945, setpoint_start
to1945
. Defaults to0
.Note
If combined with
relative_x_value
, an x value can be set on each point. The x value from the point options is multiplied bypoint_interval
and added topoint_start
to produce a modified x value.- Return type:
numeric or
None
- property relative_x_value: bool | None
When
True
, X values in the data set are relative to the currentpoint_start
,point_interval
, andpoint_interval_unit
settings. This allows compression of the data for datasets with irregular X values. Defaults toFalse
.The real X values are computed on the formula
f(x) = ax + b
, wherea
is thepoint_interval
(optionally with a time unit given bypoint_interval_unit
), andb
is thepoint_start
.
- property selected: bool | None
If
True
, the series is selected initially (by default, without user interaction). Defaults toFalse
.Note
If
GenericTypeOptions.show_checkbox()
isTrue
, then the checkbox will be checked ifselected
isTrue
.
- property shadow: bool | ShadowOptions | None
Configuration for the shadow to apply to the tooltip. Defaults to
False
.If
False
, no shadow is applied.- Returns:
The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.
- Return type:
bool
orShadowOptions
- property show_checkbox: bool | None
If
True
, a checkbox is displayed next to the legend item to allow selecting the series.Note
The state of the checkbox is controlled by the
GenericTypeOptions.selected()
property.
- property show_in_legend: bool | None
Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.
If
True
, the accessibility module will skip past this series when executing keyboard navigation.
- property soft_threshold: bool | None
When
True
, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults toTrue
.For example, if
False
, a series of0, 1, 2, 3
will make the Y axis show negative values according to themin_padidng
option. IfTrue
, the Y axis starts at 0.- Return type:
- property sonification: SeriesSonification | None
Sonification configuration for the series type/series.
- Return type:
- property stack: str | None
Indicates the “stack” into which the series should be grouped, if the chart groups series into stacks. Defaults to
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.
- property stacking: str | None
Whether to stack the values of each series on top of each other. Defaults to
None
.Acceptable values are:
None
to disable stacking,"normal"
to stack by value or"percent"
'stream'
(for streamgraph series type only)'overlap'
(for waterfall series type only)
Note
When stacking is enabled, data must be sorted in ascending X order.
- property states: States | None
Configuration for state-specific configuration to apply to the data series.
- Return type:
States
orNone
- property step: str | None
Whether to apply steps to the line. Defaults to
None
.Possible values are:
'left'
'center'
'right'
- property sticky_tracking: bool | None
Sticky tracking of mouse events.
When
True
, the (JavaScript)mouseOut
event on a series is not triggered until the mouse moves over another series, or out of the plot area.When
False
, the (JavaScript)mouseOut
event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.When
False
andPlotOptions.tooltip.shared()
is alsoFalse
, the tooltip will be hidden when moving the mouse between series.Defaults to
True
for line and area type series, but toFalse
for columns, pies, etc.Note
The boost module will force this option because of technical limitations.
- property threshold: int | float | Decimal | EnforcedNullType | None
The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to
0
.If
EnforcedNullType
, the columns extend from the padding Y axis minimum.- Return type:
numeric or
EnforcedNullType
orNone
- property tooltip: Tooltip | None
A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.
- Return type:
Tooltip
orNone
- property track_by_area: bool | None
When
True
, the whole area should respond to mouseover tooltips and other mouse or touch events. WhenFalse
, only the line responds to mouse/touch events. Defaults toFalse
.- Return type:
- property turbo_threshold: int | None
When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to
0
orNone
to disable.Defaults to
1000
.Note
In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.
- property type: str