`.track_configurations`

to_json(filename=None, encoding='utf-8')

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 a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes 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'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property active_when: ActiveWhen | CallbackFunction | None

The condition for when a track should be active or not.

Accepts either a (Javascript) CallbackFunction or an ActiveWhen configuration object.

Note

If a callback function is used, it should return a boolean for whether or not the track should be active.

The function is called for each audio event, and receives a parameter object with time, and potentially point and value properties depending on the track.

point is available if the audio event is related to a data point.

value is available if the track is used as a context track, and .value_interval is used.

Return type:: ActiveWhen or CallbackFunction or None.

property instrument: str | None

The instrument to use for playing. Defaults to 'piano'.

Accepts:

'flute'

'saxophone'

'trumpet'

'sawsynth'

'wobble'

'basic1'

'basic2'

'sine'

'sineGlide'

'triangle'

'square'

'sawtooth'

'noise'

'filteredNoise'

'wind'

Return type:: str

property mapping: SonificationMapping | None

Mapping options for the audio parameter.

Return type:: SonificationMapping or None

property midi_name: str | None

The name to use for a track when exporting it to MIDI. If None, will use the series name if the track is related to a series. Defaults to None.

Return type:: str or None

property point_grouping: SonificationGrouping | None

Options for configurign the grouping of points.

Return type:: SonificationGrouping or None

property round_to_musical_notes: bool | None

If True, will round pitch matching to musical notes in 440Hz standard tuning. If False, will play the exact mapped/configured note even if it is out of tune as per standard tuning. Defaults to True.

Return type:: bool or None

property show_play_marker: bool | None

If True, displays the play marker (tooltip and/or crosshair) for a track. Defaults to True.

Return type:: bool or None

property type: str | None

The type of track.

Note

In the context of an InstrumentTrackConfiguration, this will always return 'instrument' if not None.

Return type:: str or None

class: `SpeechTrackConfiguration`

class SpeechTrackConfiguration(**kwargs)[source]

Configuration of a Speech Track for use in sonification.

Class Inheritance

Inheritance diagram of SpeechTrackConfiguration

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. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
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

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

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 a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

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) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

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.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list

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.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

to_json(filename=None, encoding='utf-8')

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 a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes 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'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property active_when: ActiveWhen | CallbackFunction | None

The condition for when a track should be active or not.

Accepts either a (Javascript) CallbackFunction or an ActiveWhen configuration object.

Note

If a callback function is used, it should return a boolean for whether or not the track should be active.

The function is called for each audio event, and receives a parameter object with time, and potentially point and value properties depending on the track.

point is available if the audio event is related to a data point.

value is available if the track is used as a context track, and .value_interval is used.

Return type:: ActiveWhen or CallbackFunction or None.

property language: str | None

The language to speak in for speech tracks, as an IETF BCP 47 language tag. Defaults to 'en-US'.

Return type:: str or None

property mapping: SonificationMapping | None

Mapping options for the audio parameter.

Return type:: SonificationMapping or None

property point_grouping: SonificationGrouping | None

Options for configurign the grouping of points.

Return type:: SonificationGrouping or None

property preferred_voice: str | None

The name of the voice synthesis to prefer for speech tracks. If None or unavabilable, will fall back to the default voice for the selected language. Defaults to None.

Warning

Different platforms (operating systems in which your users will view your visualizations) provide different voices for web speech synthesis.

Return type:: str or None

property show_play_marker: bool | None

If True, displays the play marker (tooltip and/or crosshair) for a track. Defaults to True.

Return type:: bool or None

property type: str | None

The type of track. Accepts either 'instrument' or 'speech'. Defaults to 'instrument'.

Return type:: str or None

class: `ContextTrackConfiguration`

class ContextTrackConfiguration(**kwargs)[source]

Configuration of a Context Track for use in sonification.

Class Inheritance

Inheritance diagram of ContextTrackConfiguration

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. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
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

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

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 a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

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) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

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.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list

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.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

to_json(filename=None, encoding='utf-8')

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 a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes 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'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property active_when: ActiveWhen | CallbackFunction | None

The condition for when a track should be active or not.

Accepts either a (Javascript) CallbackFunction or an ActiveWhen configuration object.

Note

If a callback function is used, it should return a boolean for whether or not the track should be active.

The function is called for each audio event, and receives a parameter object with time, and potentially point and value properties depending on the track.

point is available if the audio event is related to a data point.

value is available if the track is used as a context track, and .value_interval is used.

Return type:: ActiveWhen or CallbackFunction or None.

property instrument: str | None

The instrument to use for playing. Defaults to 'piano'.

Accepts:

'flute'

'saxophone'

'trumpet'

'sawsynth'

'wobble'

'basic1'

'basic2'

'sine'

'sineGlide'

'triangle'

'square'

'sawtooth'

'noise'

'filteredNoise'

'wind'

Return type:: str

property language: str | None

The language to speak in for speech tracks, as an IETF BCP 47 language tag. Defaults to 'en-US'.

Return type:: str or None

property mapping: SonificationMapping | None

Mapping options for the audio parameter.

Return type:: SonificationMapping or None

property midi_name: str | None

The name to use for a track when exporting it to MIDI. If None, will use the series name if the track is related to a series. Defaults to None.

Return type:: str or None

property point_grouping: SonificationGrouping | None

Options for configurign the grouping of points.

Return type:: SonificationGrouping or None

property preferred_voice: str | None

The name of the voice synthesis to prefer for speech tracks. If None or unavabilable, will fall back to the default voice for the selected language. Defaults to None.

Warning

Different platforms (operating systems in which your users will view your visualizations) provide different voices for web speech synthesis.

Return type:: str or None

property round_to_musical_notes: bool | None

If True, will round pitch matching to musical notes in 440Hz standard tuning. If False, will play the exact mapped/configured note even if it is out of tune as per standard tuning. Defaults to True.

Return type:: bool or None

property show_play_marker: bool | None

If True, displays the play marker (tooltip and/or crosshair) for a track. Defaults to True.

Return type:: bool or None

property time_interval: int | float | Decimal | None

Determines the number of milliseconds between playback of a context track. Defaults to None.

Return type:: numeric or None

property type: str | None

The type of track. Accepts either 'instrument' or 'speech'. Defaults to 'instrument'.

Return type:: str or None

property value_interval: int | float | Decimal | None

Determines the number of units between playback of a context track, where units are determined by .value_prop.

For example, setting .value_prop to 'x' and .value_interval to 5 means the context track should be played for every 5th value of 'x'.

Note

The context audio events will be mapped to time according to the prop value relative to the min/max values for that prop.

Return type:: numeric or None

property value_map_function: str | None

Determines how to map context events to time when using the .value_interval property. Accepts either 'linear' or 'logarithmic'. Defaults to 'linear'.

Return type:: str or None

property value_prop: str | None

The data point property to use when evaluating whether to play the context track in conjunction with .value_interval Defaults to None.

Return type:: str or None

class: `ActiveWhen`

class ActiveWhen(**kwargs)[source]

Definition of the condition for when a track should be active or not.

Class Inheritance

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. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
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

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

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 a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

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) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

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.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list

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.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

to_json(filename=None, encoding='utf-8')

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 a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes 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'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property crossing_down: int | float | Decimal | None

Track will be active when the property indicated by .prop is at or below this value. Defaults to None.

Warning

If both .crossing_down and .crossing_up are defined, the track will be active if either condition is met.

Return type:: numeric or None

property crossing_up: int | float | Decimal | None

Track will be active when the property indicated by .prop is at or above this value. Defaults to None.

Warning

If both .crossing_up and .crossing_down are defined, the track will be active if either condition is met.

Return type:: numeric or None

property max: int | float | Decimal | None

Track will be active when the property indicated by .prop is at or below this value. Defaults to None.

Return type:: numeric or None

property min: int | float | Decimal | None

Track will be active when the property indicated by .prop is at or above this value. Defaults to None.

Return type:: numeric or None

property prop: str | None

The data point property to use when evaluating the condition, for example 'y' or 'x'. Defaults to None.

Return type:: str or None

class: `TrackConfigurationBase`

class TrackConfigurationBase(**kwargs)[source]

Base class for use in configuring Sonification tracks.

Class Inheritance

Inheritance diagram of TrackConfigurationBase

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. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
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

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

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 a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

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) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

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.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list

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.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

to_json(filename=None, encoding='utf-8')

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 a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes 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'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type: