canvasxpress

[view_source]

The CanvasXpress package provides Python friendly management of the Javascript- based CanvasXpress library. For an overview and detailed instructions about CanvasXpress specifically please visit the site.

canvasxpress.util

[view_source]

canvasxpress.util.example

[view_source]

canvasxpress.util.example.generator

[view_source]

generate_canvasxpress_code_from_json_file

def generate_canvasxpress_code_from_json_file(cx_json_path: str, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str

[view_source]

Generates a string with a CanvasXPress in Python declaration using a CanvasXpress reproducible research JSON stored in a file.

Arguments:

A valid path to the reproducible JSON text from which a CanvasXPress
object is to be built and then converted into example code.
Default `True`.  Indicate if include headers should be prefixed.
Default `True`.  Indicate if rendering should be included in the
example code.
Default `False`.  Indicate if Jupyter rendering should be performed;
otherwise, popup rendering will suffixed.
  • cx_json_path: str
  • document_includes: bool
  • document_render: bool
  • document_jupyter_render: bool

Returns:

str

generate_canvasxpress_code_from_json

def generate_canvasxpress_code_from_json(cx_json: str, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str

[view_source]

Generates a string with a CanvasXPress in Python declaration using a CanvasXpress reproducible research JSON.

Arguments:

The reproducible JSON text from which a CanvasXPress object is to be
built and then converted into example code.
Default `True`.  Indicate if include headers should be prefixed.
Default `True`.  Indicate if rendering should be included in the
example code.
Default `False`.  Indicate if Jupyter rendering should be performed;
otherwise, popup rendering will suffixed.
  • cx_json: str
  • document_includes: bool
  • document_render: bool
  • document_jupyter_render: bool

Returns:

str

generate_canvasxpress_code

def generate_canvasxpress_code(cx: CanvasXpress, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str

[view_source]

Generates a string with a CanvasXPress in Python declaration.

Arguments:

The `CanvasXpress` object from which to generate the example code.
Default `True`.  Indicate if include headers should be prefixed.
Default `True`.  Indicate if rendering should be included in the
example code.
Default `False`.  Indicate if Jupyter rendering should be performed;
otherwise, popup rendering will suffixed.
  • cx: CanvasXpress
  • document_includes: bool
  • document_render: bool
  • document_jupyter_render: bool

Returns:

str

canvasxpress.util.example.generate_tutorials

[view_source]

This file can be executed to convert the reproducible JSON files located at [project]/tutorials/reproducible_json/*.json into tutorials for general use.

get_json_file_paths

def get_json_file_paths() -> List[str]

[view_source]

Returns a list of all reproducible JSON files tracked for tutorials.

Returns:

list[str]

get_type_from_filename

def get_type_from_filename(file_name: str) -> str

[view_source]

Returns the type of chart from a reproducible JSON filename.

Arguments:

The name of the file without parent path.
  • file_name: str

Returns:

str

get_index_from_filename

def get_index_from_filename(file_name: str) -> str

[view_source]

Returns the index of chart from a reproducible JSON filename.

Arguments:

The name of the file without parent path.
  • file_name: str

Returns:

str

create_jupyer_template_text

def create_jupyer_template_text(chart_type: str, chart_index: str, chart_code: str) -> str

[view_source]

Generates the text for a Jupyter Notebook example given a chart's type, index, and code. :param: chart_type: str The type text (e.g., bar) for the chart.

Arguments:

The index text (e.g., 1) for the chart.
The chart source code.
  • chart_index: str
  • chart_code: str

Returns:

str

canvasxpress.util.template

[view_source]

render_from_template

def render_from_template(template: str, data: dict) -> str

[view_source]

Updates the template text with the provided data.

Arguments:

:returns The adjusted template text - template: str The name of the template file - data: The dict of str values with which to update the template text

canvasxpress.config

[view_source]

The config package provides functionality for managing or assigning configuration values associated with CanvasXpress objects.

canvasxpress.config.type

[view_source]

CXConfig Objects

@total_ordering
class CXConfig(ABC)

[view_source]

CXConfig provides the means by which CanvasXpress objects can be configured for customized rendering and interaction.

label

@property
def label() -> str

[view_source]

Provides the label for the configuration.

Returns:

str

value

@property
@abstractmethod
def value() -> Any

[view_source]

Provides the value for the configuration. Must be implemented by concrete classes.

Returns:

Any

value

@value.setter
@abstractmethod
def value(value: Any) -> None

[view_source]

Sets the value of the configuration. Must be implemented by concrete classes.

Arguments:

The value to be accepted.  Will be more specific with concrete
implementations, such as `str` for string configurations.
  • value: Any

render

def render() -> dict

[view_source]

Renders the value in a form suitable for use in preparing Javascript. Typically, this will be the native value.

Returns:

dict

__init__

def __init__(label: str, value: Any)

[view_source]

Initializes a new CXConfig object with a label and value.

Arguments:

The label for the configuration.
The value for the configuration.  See the `value` property for the
concrete implementation for allowed types.
  • label: str
  • value: Any

__copy__

def __copy__() -> 'CXConfig'

[view_source]

copy constructor that provides a new CXConfig of the same type with the data referenced.

Returns:

CXConfig of the proper type

__deepcopy__

def __deepcopy__(memo)

[view_source]

deepcopy constructor that provides a new CXConfig of the same type with the a deepcopy of the data.

Returns:

CXConfig of the proper type

__hash__

def __hash__() -> int

[view_source]

Provides a hash proxy for the object as converted into its repr form.

Returns:

int

__lt__

def __lt__(other: 'CXConfig') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXConfig` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXConfig') -> bool

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXConfig` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the object into a JSON string.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXConfig object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXString Objects

class CXString(CXConfig)

[view_source]

A CXConfig object that manages str values.

value

@property
def value() -> str

[view_source]

Provides the value for the configuration.

Returns:

str

value

@value.setter
def value(value: Union[object, str]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then an empty `str` will be used.
  • value: str

__init__

def __init__(label: str, value: str)

[view_source]

Initializes the configuration with a str value.

CXBool Objects

class CXBool(CXConfig)

[view_source]

A CXConfig object that manages bool values.

value

@property
def value() -> bool

[view_source]

Provides the value for the configuration.

Returns:

bool

value

@value.setter
def value(value: Union[object, bool]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then `False` will be used.
  • value: bool

__init__

def __init__(label: str, value: bool)

[view_source]

Initializes the configuration with a bool value.

__str__

def __str__() -> str

[view_source]

str function. Converts the object into a Javascript statement.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXBool object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXFloat Objects

class CXFloat(CXConfig)

[view_source]

A CXConfig object that manages float values.

value

@property
def value() -> float

[view_source]

Provides the value for the configuration.

Returns:

float

value

@value.setter
def value(value: Union[object, float]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then `float(0.0)` will be used.
  • value: float

__init__

def __init__(label: str, value: float)

[view_source]

Initializes the configuration with a float value.

CXInt Objects

class CXInt(CXConfig)

[view_source]

A CXConfig object that manages int values.

value

@property
def value() -> int

[view_source]

Provides the value for the configuration.

Returns:

int

value

@value.setter
def value(value: Union[object, int]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then `int(0)` will be used.
  • value: int

__init__

def __init__(label: str, value: int)

[view_source]

Initializes the configuration with an int value.

CXDict Objects

class CXDict(CXConfig)

[view_source]

A CXConfig object that manages dict values.

value

@property
def value() -> dict

[view_source]

Provides the value for the configuration.

Returns:

dict

value

@value.setter
def value(value: Union[dict, str, None]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then `dict()` will be used.
  • value: dict

__init__

def __init__(label: str, value: Union[dict, str, None]) -> None

[view_source]

Initializes the CXData object with data. Only dict or compatible data types are accepted.

__lt__

def __lt__(other: 'CXDict') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXDict` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXDict') -> bool

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXDict` The object to compare.
  • other:

Returns:

bool

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXDict object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXList Objects

class CXList(CXConfig)

[view_source]

A CXConfig object that manages list values.

value

@property
def value() -> list

[view_source]

Provides the value for the configuration.

Returns:

list

value

@value.setter
def value(value: Union[object, list]) -> None

[view_source]

Sets the value of the configuration.

Arguments:

If `None` then `list()` will be used.
  • value: list

__init__

def __init__(label: str, value: list)

[view_source]

Initializes the configuration with a list value.

CXRGBAColor Objects

class CXRGBAColor(CXDict)

[view_source]

A CXConfig object that manages str Javascript rgba() values.

is_color_str

@staticmethod
def is_color_str(value: str)

[view_source]

A static method that evaluates a given string to see if it represents a Javascript rgba() statement.

Arguments:

A string to evaluate.  A valid Javascript value has the form
`rgba(r, g, b, a)` where RGB values are `int` from 0-255 and A is a
`float` from 0.0 to 1.0.
  • value: str

Returns:

bool

is_color_list

@staticmethod
def is_color_list(value: list)

[view_source]

A static method that evaluates a given list to see if it represents a Javascript rgba() statement.

Arguments:

A list to evaluate.  A valid Javascript value has the form
`rgba(r, g, b, a)` where RGB values are `int` from 0-255 and A is a
`float` from 0.0 to 1.0.
  • value: list

Returns:

bool

is_color_dict

@staticmethod
def is_color_dict(value: dict)

[view_source]

A static method that evaluates a given dict to see if it represents a Javascript rgba() statement.

Arguments:

A dict to evaluate.  A valid Javascript value has the form
`rgba(r, g, b, a)` where RGB values are `int` from 0-255 and A is a
`float` from 0.0 to 1.0.  For the dict to be valid its keys must be
lower case r, g, b, and a characters.
  • value: dict

Returns:

bool

value

@CXDict.value.setter
def value(value: Union['CXRGBAColor', dict, list, str]) -> None

[view_source]

Sets the RGBA value from an existing CXRGBAColor object, or a dict, list, or string following the Javascript rgba() format.

Arguments:

The value to be accepted.  See the `is_color_*()` methods for
acceptable formats.
  • value: Union['CXRGBAColor', dict, list, str]

render

def render() -> Any

[view_source]

Renders the value in a form suitable for use in preparing Javascript. Typically, this will be the native value.

Returns:

Any

__init__

def __init__(label: str, value: Union['CXRGBAColor', dict, list, str])

[view_source]

Initializes a new CXRGBAColor object using the RGBA value from an existing CXRGBAColor object, or a dict, list, or string following the Javascript rgba() format.

Arguments:

The value to be accepted.  See the `is_color_*()` methods for
acceptable formats.
  • value: Union['CXRGBAColor', dict, list, str]

__str__

def __str__() -> str

[view_source]

str function. Converts the object into a JSON string.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXRGBAColor object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXRGBColor Objects

class CXRGBColor(CXDict)

[view_source]

A CXConfig object that manages str Javascript rgb() values.

is_color_str

@staticmethod
def is_color_str(value: str)

[view_source]

A static method that evaluates a given string to see if it represents a Javascript rgb() statement.

Arguments:

A string to evaluate.  A valid Javascript value has the form
`rgb(r, g, b)` where RGB values are `int` from 0-255.
  • value: str

Returns:

bool

is_color_list

@staticmethod
def is_color_list(value: list)

[view_source]

A static method that evaluates a given list to see if it represents a Javascript rgb() statement.

Arguments:

A list to evaluate.  A valid Javascript value has the form
`rgb(r, g, b)` where RGB values are `int` from 0-255.
  • value: list

Returns:

bool

is_color_dict

@staticmethod
def is_color_dict(value: dict)

[view_source]

A static method that evaluates a given dict to see if it represents a Javascript rgb() statement.

Arguments:

A dict to evaluate.  A valid Javascript value has the form
`rgba(r, g, b)` where RGB values are `int` from 0-255.  For the dict
 to be valid its keys must be lower case r, g, and b characters.
  • value: dict

Returns:

bool

value

@CXDict.value.setter
def value(value: Union['CXRGBColor', dict, list, str]) -> None

[view_source]

Sets the RGB value from an existing CXRGBColor object, or a dict, list, or string following the Javascript rgb() format.

Arguments:

The value to be accepted.  See the `is_color_*()` methods for
acceptable formats.
  • value: Union['CXRGBColor', dict, list, str]

render

def render() -> dict

[view_source]

Renders the value in a form suitable for use in preparing Javascript. Typically, this will be the native value.

Returns:

Any

__init__

def __init__(label: str, value: Union['CXRGBColor', dict, list, str])

[view_source]

Initializes a new CXRGBColor object using the RGB value from an existing CXRGBColor object, or a dict, list, or string following the Javascript rgb() format.

Arguments:

The value to be accepted.  See the `is_color_*()` methods for
acceptable formats.
  • value: Union['CXRGBColor', dict, list, str]

__str__

def __str__() -> str

[view_source]

str function. Converts the object into a JSON string.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXRGBColor object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXGraphTypeOptions Objects

class CXGraphTypeOptions(Enum)

[view_source]

A set of known chart types permitted for use with CanvasXpress objects. If a chart not yet identified in this list is required then use a CXString object with the label graphType and the value set to the name of the chart to be used.

CXGraphType Objects

class CXGraphType(CXString)

[view_source]

A CXString that is aware of CanvasXpress types of graphs, such as 'Bar'.

value

@CXString.value.setter
def value(value: Union[CXGraphTypeOptions, str]) -> None

[view_source]

Sets the value using a known CanvasXpress option.

set_custom_value

def set_custom_value(value: str)

[view_source]

Permits a js value to be set, such as if a new option is recently made available that the Python framework is yet to be aware of.

Arguments:

The string value to set.
  • value: str

render

def render() -> dict

[view_source]

Renders the value in a form suitable for use in preparing Javascript. Typically, this will be the native value.

Returns:

dict

__init__

def __init__(type: Union[CXGraphTypeOptions, str] = CXGraphTypeOptions.Bar)

[view_source]

Initializes a new CXGraphType object with a value corresponding to one of the values provided by CXGraphTypeOptions.

canvasxpress.config.collection

[view_source]

CXConfigs Objects

@total_ordering
class CXConfigs(
    CXDictConvertable, 
    CXListConvertable)

[view_source]

CXConfigs provides support for addressing a collection of CXConfig values.

__init__

def __init__(*configs: Union[CXConfig, tuple, dict, list])

[view_source]

Initializes a new CXConfigs object with zero or more CXConfig objects.

Example:

configs = CXConfigs(
    CXString("colorScheme", "ColorSpectrum"),
    ("lineType", "spline"),
    { "objectColorTransparency": 0.3 }
)

Arguments:

A list of zero or more `CXConfig` objects to associate.
  • configs: Union[CXConfig, tuple, dict], ...

remove

def remove(label: str) -> Union[CXConfig, None]

[view_source]

Removes the CXConfig if found, and if found the removed config is provided.

Arguments:

The label of the CXConfig to remove.
  • label: 'str`

Returns:

Union[CXConfig, None]

add

def add(config: Union[CXConfig, tuple, dict, list]) -> 'CXConfigs'

[view_source]

Adds the specified configuration to the collection. This method supports chaining for efficient additions of CXConfig objects.

Example:

configs = CXConfigs()
configs \
    .add(CXString("colorScheme", "ColorSpectrum") \
    .add(("lineType", "spline")) \
    .add({ "objectColorTransparency": 0.3 })

Arguments:

The `CXConfig` to associate.  Cannot be `None`.  `tuple` an d`list`
config values are expected to be two elements in length, with the
first representing the label and the second representing the value.
The label portion will be converted to a string using `str`.
  • config: Union[CXConfig, tuple, dict, list]

get_param

def get_param(label: str) -> Union[CXConfig, None]

[view_source]

Provides the CXConfig with the indicated label.

Arguments:

The name of the congig to find.
  • label: str

Returns:

Union[CXConfig, None]

set_param

def set_param(label: str, value: Any) -> 'CXConfigs'

[view_source]

Adds a parameter to the configs. Attempts to infer the kind of param to add, and if a type can be deduced then an appropriate CXConfig is used. If a type cannot be inferred the a text type is assumed. This method supports chaining for efficient additions of CXConfig objects.

Example:

configs = CXConfigs()
configs \
    .set_param("1", "rgb(3, 172, 198)") \
    .set_param("2", 2) \
    .set_param("3", True)

Arguments:

The parameter to infer and associate.  Cannot be `None`.  Defaults
to `str` if the type cannot otherwise be deduced.
  • value: Any

configs

@property
def configs() -> List[CXConfig]

[view_source]

Provides access to the list of associated CXConfig objects.

Returns:

List[CXConfig]

render_to_dict

def render_to_dict() -> dict

[view_source]

Provides a dict representation of the configuration values.

Returns:

dict

render_to_list

def render_to_list(**kwargs) -> list

[view_source]

Provides a list representation of the configuration values.

Returns:

list

merge_configs

@classmethod
def merge_configs(cls, configs: List[CXConfig]) -> dict

[view_source]

Given a list of CXConfig objects, a dictionary of unique attributes is generated and provided.

Returns:

dict

__copy__

def __copy__() -> 'CXConfigs'

[view_source]

copy constructor. Returns the CXConfig objects within a new CXConfigs object.

__deepcopy__

def __deepcopy__(memo) -> 'CXConfigs'

[view_source]

deepcopy constructor. Returns a deepcopy of the CXConfig objects within a new CXConfigs object.

__lt__

def __lt__(other: 'CXConfigs') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXConfigs` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXConfigs') -> bool

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXConfigs` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the CXConfigs object into a JSON representation. :returns" str JSON form of the collection.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXConfigs object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

canvasxpress.js

[view_source]

The js package provides functionality for integrating custom Javascript with CanvasXpress charts.

canvasxpress.js.collection

[view_source]

CXEvents Objects

@total_ordering
class CXEvents(CXJavascriptConvertable)

[view_source]

CXEvents represents a Javascript script that can be associated with a CanvasXpress object.

For example, when defining a CanvasXpress object Javascript could be added for reactive feedback via:

chart_events = CXEvents(
    CXEvent(
        "click",
        '''
        var s = 'click on var ' + o.y.vars[0] + ' and smp ' + o.y.smps[0];
        t.showInfoSpan(e, s);
        '''
    )
)
chart = CanvasXpress(
    events=chart_events
)

Also see the CanvasXpress documentation or CXEvent for additional information.

events

@property
def events() -> List[CXEvent]

[view_source]

Provides a non-associated list of the associated CXEvents.

Returns:

List[CXEvent] A list of zero or more CXEvent objects.

has

def has(event: CXEvent) -> bool

[view_source]

Indicates if the CXEvent is a member.

Arguments:

  • event: The CXEvent to consider.

Returns:

bool True if event is a member.

add

def add(event: CXEvent, unique: bool = True) -> None

[view_source]

Adds the specified CXEvent. If the CXEvent must be unique then an Error is raised if an react is already presenbt with the same ID.

Arguments:

`CXEvent` The event to add to the collection.  Cannot be `None`.
`bool` True if `event` must not already be a part of the collection.
  • event:
  • unique:

remove

def remove(event: CXEvent) -> bool

[view_source]

Removes the specified object from the list.

Arguments:

already included.
  • event: The CXEvent object to remove from the list if it is

Returns:

True if the CXEvent was removed. False indicates that the

render_to_dict

def render_to_dict() -> dict

[view_source]

Provides a dict with each js properly formatted as JS within.

Returns:

dict

render_to_js

def render_to_js() -> str

[view_source]

Converts the object into HTML5 complant script.

Returns:

'str'

__init__

def __init__(*events)

[view_source]

Initializes a new CXEvents object.

Arguments:

A multiple value parameter by which zero or more `CXEvent` objects
may be provided.  Also see `add()` for how individual objects are
processed.

For example:
event1 = CXEvent("f1", "x = 0")
event2 = CXEvent("f2", "x = 1")
events = CXEvents(event1, event2)
  • events:

__copy__

def __copy__()

[view_source]

copy constructor. Returns the CXEvent objects within a new CXEvents object.

__deepcopy__

def __deepcopy__(memo)

[view_source]

deepcopy constructor. Returns a deep copy of CXEvent objects within a new CXEvents object.

__lt__

def __lt__(other: 'CXEvents')

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXEvent` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXEvents')

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXEvent` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the CXEvents object into a JSON list of CXEvent objects also converted into JSON representations. :returns" str JSON form of the collection.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXEvents object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

canvasxpress.js.function

[view_source]

CXEvent Objects

@total_ordering
class CXEvent(CXJavascriptConvertable)

[view_source]

CXEvent is a CXJavascriptConvertable that represents Javascript source to be associated with a CanvasXpress object.

CanvasXpress provides hook functions for various events that are called as those events occur for the div element containing the rendered chart. The format is:

"event-name": function(o, e, t) {
    event code
}

With the following as an example:

"mousemove": function(o, e, t) {
    t.showInfoSpan(e, '<pre>' + t.prettyJSON(o) + '</pre>');
}

CXEvent handles the function template, so the developer only needs to supply the event name and the source. Given the above example, the following creates the equivalent CXEvent:

event = CXEvent(
    id="mousemove",
    script="t.showInfoSpan(e, '<pre>' + t.prettyJSON(o) + '</pre>');"
)

No validations is performed for id or script.

Read the CanvasXpress documentation for additional information. Also see CXEvents.

id

@property
def id() -> str

[view_source]

Provides access to the react ID.

Returns:

The ID as a string.

id

@id.setter
def id(value: str) -> None

[view_source]

Sets the react ID, which is a keyword recognized by CanvasXpress.

Arguments:

The ID, which must be a string compliant object.  Cannot be `None`.
  • value: str

script

@property
def script() -> str

[view_source]

Provides access to the react script.

Returns:

str The Javascript source.

script

@script.setter
def script(value: str) -> None

[view_source]

Sets the react script, which is logic that goes inside of the react function. Functions take the form:

function(o, e, t) {
    // script logic goes here
};

The script can be assumed to have access to all DOM elements as proper, and it will be provided the parameters o, e, and t. Read the CanvasXpress documentation for additional information.

Arguments:

The ID, which must be a UTF-8 string compliant object.
  • value: str

render_to_js

def render_to_js() -> str

[view_source]

Converts the object into HTML5 complant script.

Returns:

'str'

__init__

def __init__(id: str = "", script: str = "")

[view_source]

Initializes a new CXEvent object.

Arguments:

The ID of the react, such as mousemove.  Also see property `id`.
The script logic for the react.  Also see property `script`.
  • id: str
  • script: str

__copy__

def __copy__()

[view_source]

copy constructor. Returns a new CXEvent object.

__deepcopy__

def __deepcopy__(memo)

[view_source]

deepcopy constructor. Returns a new CXEvent object.

__lt__

def __lt__(other: 'CXEvent') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXEvent` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXEvent') -> bool

[view_source]

equal comparison. Also see @total_ordering in functools.

Arguments:

`CXEvent` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the object into a Javascript statement.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXEvent object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

canvasxpress.render

[view_source]

The render package provides functionality for rendering CanvasXpress objects in containers or environments

canvasxpress.render.popup

[view_source]

CXBrowserPopup Objects

class CXBrowserPopup(CXRenderable)

[view_source]

CXBrowserPopup is a CXRenderable that renders CanvasXpress objects into a Web page that is displayed in a pop-up browser window.

__init__

def __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])

[view_source]

Initializes a new CXBrowserPopup object. :praram cx: Union[List[CanvasXpress], CanvasXpress, None], ... The CanvasXpress object(s) to be tracked. See the canvas property, except that on initialization cx can be None. Multiple CanvasXpress objects are supported provided that they have distinct render_to targets.

render

def render(**kwargs: Any)

[view_source]

Renders the associated CanvasXpress object appropriate for display in a pop-up browser window. Charts cannot have the same name, so render_to will be updated with a uuid for each conflicting chart.

Arguments:

Supports `columns` for any positive `int` of `1` or greater, with a
default value of `1`.  Values less that `1` are ignored.  `columns`
indicates how many charts should be rendered horizontally in the
browser if more than one chart is being tracked.
  • kwargs: Any

canvasxpress.render.base

[view_source]

CXRenderable Objects

class CXRenderable(ABC)

[view_source]

CXRenderable is capable of rendering a CanvasXpress object to some kind of output or display device.

canvas

@property
def canvas() -> Union[List[CanvasXpress], CanvasXpress, None]

[view_source]

Provides the tracked CanvasXpress object.

Returns:

value: Union[List[CanvasXpress], CanvasXpress, None]

canvas

@canvas.setter
def canvas(value: Union[List[CanvasXpress], CanvasXpress, None])

[view_source]

Sets the CanvasXpress object to be tracked. :praram value: value: Union[List[CanvasXpress], CanvasXpress, None] A list of CanvasXpress objects if multiple are tracked, or one CanvasXpress object, orNone` if no objects are to be tracked.

__init__

def __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])

[view_source]

Initializes a new CXRenderable object. :praram cx: Union[List[CanvasXpress], CanvasXpress, None], ... The CanvasXpress object(s) to be tracked. See the canvas property, except that on initialization cx can be None. Multiple CanvasXpress objects are supported provided that they have distinct render_to targets.

render

@abstractmethod
def render(**kwargs: Any)

[view_source]

Renders the associated CanvasXpress object appropriate to the render_to. Not implemented.

Arguments:

Parameters specific to implementations are supported.  The essential
render call should work with no extra parameters, and with
parameters that do not apply to the implementation.
  • kwargs: Any

canvasxpress.render.jupyter

[view_source]

CXNoteBook Objects

class CXNoteBook(CXRenderable)

[view_source]

CXNoteBook is a CXRenderable that renders CanvasXpress objects into IPython containers (Jupyter Notebooks).

__init__

def __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])

[view_source]

Initializes a new CXNoteBook object. :praram cx: Union[List[CanvasXpress], CanvasXpress, None], ... The CanvasXpress object(s) to be tracked. See the canvas property, except that on initialization cx can be None. Multiple CanvasXpress objects are supported provided that they have distinct render_to targets.

render

def render(**kwargs: Any)

[view_source]

Renders the associated CanvasXpress object appropriate for display in an IPython (e.g., Jupyter NoteBook/Lab) environment. Charts cannot have the same name, so render_to will be updated with a uuid for each conflicting chart.

Arguments:

* Supports `columns` for any positive `int` of `1` or greater, with a
  default value of `1`.  Values less that `1` are ignored.  `columns`
  indicates how many charts should be rendered horizontally in the
  Jupyter Notebook if more than one chart is being tracked.
* Supports `output_file` as a string for a path at which the output
  should be saved.  If a file exists at the specified path then
  it will be overwritten.  This permits Jupyter sessions to render
  output that is saved and accessible in later sessions.
  • kwargs: Any

canvasxpress.data

[view_source]

The data package provides functionality for integrating different kinds of data structures and sources into a CanvasXpress object. A balance is provided between convenience functionality and reasonable external preparation, such as what can be performed via pandas.

canvasxpress.data.matrix

[view_source]

CXDataframeData Objects

@total_ordering
class CXDataframeData(CXMatrixData)

[view_source]

A CXData class dedicated to processing Python DataFrame, matrix-structured data.

dataframe

@property
def dataframe() -> DataFrame

[view_source]

Provides the data managed by the object.

Returns:

DataFrame The managed data.

dataframe

@dataframe.setter
def dataframe(value: Union[DataFrame, None] = None) -> None

[view_source]

Sets the dataframe managed by the object.

Arguments:

`None` results in an empty `DataFrame`.  A deepcopy will be made of
`DataFrame` values.
  • value: Union[DataFrame, None]

data

@property
def data() -> dict

[view_source]

Provides the data managed by the object.

Returns:

DataFrame The managed data.

data

@data.setter
def data(value: Union['CXDataframeData', DataFrame, dict, str, None] = None) -> None

[view_source]

Sets the dataframe managed by the object.

Arguments:

`None` results in an empty `DataFrame`.  A deepcopy will be made of
`DataFrame` or equivalent values.
  • value: Union['CXDataframeData', DataFrame, dict, str, None]

get_raw_dict_form

def get_raw_dict_form() -> dict

[view_source]

" Provides a simple dict perspective of the data with no metadata or other contextual transformations performed. For example, if the data is natively in dict form then it would be passed-through with no modification or enhancement.

This implementation provides matrix data formatted in a dict object with DataFrame.to_dict('split') behaviour.

Returns:

dict

render_to_dict

def render_to_dict(**kwargs) -> dict

[view_source]

Provides a dict representation of the data.

Returns:

dict

__init__

def __init__(data: Union['CXDataframeData', DataFrame, dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None

[view_source]

Initializes the CXData object with data. Only DataFrame or compatible data types are accepted.

Arguments:

`None` to initialize with an empty `DataFrame`, or a `DataFrame`
like object to assign mapped data.
Specify the desired profile object to facilitate transformation of
data into a CanvasXpress JSON data object.  `None` to avoid use of
a profile.
  • data: Union['CXDataframeData', DataFrame, dict, str, None]
  • profile: Union[CXDataProfile, None]

__copy__

def __copy__() -> 'CXDataframeData'

[view_source]

copy constructor that returns a copy of the CXDataframeData object.

Returns:

CXDataframeData

__deepcopy__

def __deepcopy__(memo) -> 'CXDataframeData'

[view_source]

deepcopy constructor that returns a copy of the CXDataframeData object.

Returns:

CXDataframeData A copy of the wrapping object and deepcopy of

__lt__

def __lt__(other: 'CXDataframeData') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXDataframeData` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXDataframeData') -> bool

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXDataframeData` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the CXDataframeData object into a JSON representation. :returns" str JSON form of the CXDataframeData.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXDataframeData object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXCSVData Objects

class CXCSVData(CXDataframeData)

[view_source]

A CXData class dedicated to processing Python CSV-based, matrix-structured data.

csv

@property
def csv() -> str

[view_source]

Provides the data managed by the object.

Returns:

str The managed data.

csv

@csv.setter
def csv(value: str = None) -> None

[view_source]

Sets the CSV data managed by the object.

Arguments:

`None` results in an empty CSV.  A deepcopy will be made of
valid CSV `str` values.
  • value: str

__init__

def __init__(data: Union['CXCSVData', DataFrame, dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None

[view_source]

Initializes the CXData object with data. Only CSV str or compatible data types are accepted.

Arguments:

`None` to initialize with an empty CSV, or a CSV `str`
like object to assign mapped data.
Specify the desired profile object to facilitate transformation of
data into a CanvasXpress JSON data object.  `None` to avoid use of
a profile.
  • data: Union['CXCSVData', DataFrame, dict, str, None]
  • profile: Union[CXDataProfile, None]

__str__

def __str__() -> str

[view_source]

str function. Converts the CXCSVData object into a JSON representation. :returns" str JSON form of the CXCSVData.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXCSVData object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

canvasxpress.data.convert

[view_source]

CXHtmlConvertable Objects

class CXHtmlConvertable(ABC)

[view_source]

CXHtmlConvertable represents an object that can be converted into HTML.

render_to_html_parts

@abstractmethod
def render_to_html_parts() -> dict

[view_source]

Converts the object into HTML5 compliant script.

Returns:

dict

CXDictConvertable Objects

class CXDictConvertable(ABC)

[view_source]

CXDictConvertable represents an object that can be converted into a dict.

render_to_dict

@abstractmethod
def render_to_dict(**kwargs) -> dict

[view_source]

Converts the object into a dict representation.

Arguments:

Keyword arguments that can be supplied to facilitate rendering
decisions.
  • kwargs:

Returns:

dict

CXListConvertable Objects

class CXListConvertable(ABC)

[view_source]

CXListConvertable represents an object that can be converted into a list.

render_to_list

@abstractmethod
def render_to_list(**kwargs) -> list

[view_source]

Converts the object into a list representation.

Arguments:

Keyword arguments that can be supplied to facilitate rendering
decisions.
  • kwargs:

Returns:

list

CXJavascriptConvertable Objects

class CXJavascriptConvertable(ABC)

[view_source]

CXJavascriptConvertable represents an object that can be converted into JS.

render_to_js

@abstractmethod
def render_to_js() -> str

[view_source]

Converts the object into HTML5 complant script.

Returns:

str

canvasxpress.data.profile

[view_source]

CXStandardProfile Objects

class CXStandardProfile(CXDataProfile)

[view_source]

CXStandardProfile provides standard chart data profile functionality, by which the topics of y, x, and z are handled in conversions.

vars

@property
def vars() -> list

[view_source]

Provides the y["vars"] CanvasXPress JSON data topic. vars are used to describe the rows of data. For example:

"y": {
    "vars": [ "Variable1", Variable2 ],
    "smps": [ "Sample1", "Sample2", "Sample3" ],
    "data": [
        [ 10, 20, 30 ],  # <- This sub-list is what Variable1 references
        [ 40, 50, 60 ]  # <- This sub-list is what Variable2 references
    ]
},

Also see CanvasXpress documentation.

Returns:

list

vars

@vars.setter
def vars(variables: Union[list, None]) -> None

[view_source]

Sets the variable labels to be used for rows of data.

Arguments:

The list of var values.  Each must be convertable to `str`, and
the number of var elements must match the row count.  `None` will
reset the var list.
  • variables: Union[list, None]

smps

@property
def smps() -> list

[view_source]

Provides the y["smps"] CanvasXPress JSON data topic. smps are used to describe the columns of data. For example:

"y": {
    "vars": [ "Variable1", Variable2 ],
    "smps": [ "Sample1", "Sample2", "Sample3" ],
    "data": [
        [ 10, 20, 30 ],
        [ 40, 50, 60 ]
        #  ^-- This is Sample1
        #      ^-- This is Sample2
        #          ^-- This is Sample3
    ]
},

Also see CanvasXpress documentation.

Returns:

list

smps

@smps.setter
def smps(samples: Union[list, None]) -> None

[view_source]

Sets the sample labels to be used for columns of data.

Arguments:

The list of smps values.  Each must be convertable to `str`, and
the number of var elements must match the column count.  `None` will
reset the smps list.
  • samples: Union[list, None]

y

@y.setter
def y(value: Union[dict, None]) -> None

[view_source]

Sets the y attribute for the data, which is the primary data for the chart. At a minimum vars and smps should be present, and if those are not provided then defaults will be provided. A deepcopy of the provided dict is made.

Arguments:

A dict value of list attributes, for which `vars` and `smps` values
will be provided if none are specified.  Provide `None` to set
default values.
  • value: Union[dict, None]

x

@x.setter
def x(value: Union[DataFrame, dict, None]) -> None

[view_source]

Sets the x attribute for the data, which corresponds to the annotations for each smps element. Quantities should match. A deepcopy of the provided dict is made.

Arguments:

A dict value of list attributes that should each contain one
element per list for each `smps` element.  Provide `None` to
reset the `x` attributes.
  • value: Union[DataFrame, dict, None]

z

@z.setter
def z(value: Union[DataFrame, dict, None]) -> None

[view_source]

Sets the z attribute for the data, which corresponds to the annotations for each vars element. Quantities should match. A deepcopy of the provided dict is made.

Arguments:

A dict value of list attributes that should each contain one
element per list for each `vars` element.  Provide `None` to
reset the `z` attributes.
  • value: Union[DataFrame, dict, None]

match_vars_to_rows

@property
def match_vars_to_rows() -> bool

[view_source]

Indicates whether vars will be match to rows when formatting data.

Returns:

bool

match_vars_to_rows

@match_vars_to_rows.setter
def match_vars_to_rows(value: bool) -> None

[view_source]

Sets whether vars will be match to rows when formatting data.

Arguments:

True if an error shall be raised if the number of `vars` does not
match the number of `data` rows.
  • value: bool

match_smps_to_cols

@property
def match_smps_to_cols() -> bool

[view_source]

Indicates whether smps will be match to columns when formatting data.

Returns:

bool

match_smps_to_cols

@match_smps_to_cols.setter
def match_smps_to_cols(value: bool) -> None

[view_source]

Sets whether smps will be match to rows when formatting data.

Arguments:

True if an error shall be raised if the number of `smps` does not
match the number of `data` columns.
  • value: bool

match_x_to_smps

@property
def match_x_to_smps() -> bool

[view_source]

Indicates whether x member attribute elements will be matched to smps when formatting data.

Returns:

bool

match_x_to_smps

@match_x_to_smps.setter
def match_x_to_smps(value: bool) -> None

[view_source]

Sets whether x member attribute elements will be matched to smps when formatting data.

Arguments:

True if an error shall be raised if the number of `x` member 
attribute elements does not match the number of `smps` elements.
  • value: bool

match_z_to_vars

@property
def match_z_to_vars() -> bool

[view_source]

Indicates whether z member attribute elements will be matched to vars when formatting data.

Returns:

bool

match_z_to_vars

@match_z_to_vars.setter
def match_z_to_vars(value: bool) -> None

[view_source]

Sets whether z member attribute elements will be matched to vars when formatting data.

Arguments:

True if an error shall be raised if the number of `z` member
attribute elements does not match the number of `vars` elements.
  • value: bool

add_data_section

def add_data_section(section: str, source: dict, target: dict) -> None

[view_source]

Adds a source data section, such as X, to the target if such a section does not yet exist.

Arguments:

The name of the section, such as X.
The dict of lists to add.
The dict to which source should be added.
  • section: str
  • source: dict
  • target: dict

render_to_profiled_dict

def render_to_profiled_dict(data: CXData, **kwargs, ,) -> dict

[view_source]

Converts a given CXData instance into a dict suitable for use by CanvasXpress when creating data instructions for the JS object.

For matrix data:
If vars are not set then data will be inspected: - The index will be used. If smps are not set then data will be inspected: - The column headers will be used.

For key-pair data:
If vars are not set then data will be inspected: - If y is not provided then an attribute will be established. - If y[vars] is not provided then vars will be assigned numerically for each row in data.

If smps are not set then data will be inspected: - If y is not provided then an attribute will be established. - If y[smps] is not provided then smps will be assigned numerically for each row in data.

x and z values are passed-through to the rendered JSON data.

Arguments:

The data object to introspect to create an enveloping profile.

Indicates whether the number `y[vars]` must equal the number of
rows specified in `y[data]`.  If `True` then an exception will be
raised should the number of vars and rows of data not match.

Indicates whether the number `y[smps]` must equal the number of
columns specified in `y[data]`.  If `True` then an exception will be
raised should the number of smps and columns of data not match.

Indicates whether for each attribute of `x` the number of list
elements should match the number of `smps` elements.  If `True`
then an exception will be raised if the counts do not align.

Indicates whether for each attribute of `z` the number of list
elements should match the number of `vars` elements.  If `True`
then an exception will be raised if the counts do not align.
  • data: CXData
  • match_vars_to_rows: bool
  • match_smps_to_cols: bool
  • match_x_to_smps: bool
  • match_z_to_vars: bool

Returns:

dict

__init__

def __init__()

[view_source]

Initializes the CXStandardProfile object.

CXVennProfile Objects

class CXVennProfile(CXDataProfile)

[view_source]

CXVennProfile provides Venn diagram chart data profile functionality, by which the topics of venn and legend are handled in conversions.

legend

@property
def legend() -> dict

[view_source]

Returns the values to be used for the legend if such are not defined in the data.

Returns:

dict

legend

@legend.setter
def legend(value: Union[dict, None]) -> None

[view_source]

Sets the values to be used for the legend. Overrides legend values in the data if available.

"param value: Union[dict, None] The key-pair values to be used for the legend. Use None to reset the key-pair values.

render_to_profiled_dict

def render_to_profiled_dict(data: CXData, **kwargs) -> dict

[view_source]

Converts a given CXData instance into a dict suitable for use by CanvasXpress when creating data instructions for the JS object.

For matrix data:
Data must be one column with numeric values plus one index. legend values will be provided as set for the profile.

df = DataFrame.from_dict(
    {
        "A": 340,
        "B": 562,
        "C": 620,
        "AB": 639,
        "AC": 456,
        "BC": 915,
        "ABC": 552
    },
    orient="index"
)

If an index is not specified then the implicit index is used.

For key-pair data:
Data must be a dict with the attribute venn with child attributes data and legend. Or, venn can be ommitted. legend is optional, and if values are set for the profile these will override those in the JSON data.

{
    "venn": {
        "data": {
            "A": 340,
            "B": 562,
            "C": 620,
            "AB": 639,
            "AC": 456,
            "BC": 915,
            "ABC": 552
        },
        "legend": {
            "A": "List1",
            "B": "List2",
            "C": "List3"
        }
    }
}

If a legend value needs to be calculated then kwargs is examined for config, which is expected to be of type CXConfigs. If config is available then the CXConfig labelled vennGroups is sought. The value assigned to vennGroups is used to count out an index of legend labels.

Arguments:

The data object to introspect to create an enveloping profile.
  • data: CXData

CXNetworkProfile Objects

class CXNetworkProfile(CXDataProfile)

[view_source]

render_to_profiled_dict

def render_to_profiled_dict(data: CXData, **kwargs) -> dict

[view_source]

Converts a given CXData instance into a dict suitable for use by CanvasXpress when creating data instructions for the JS object.

For matrix data:
Not supported. A TypeError will be raised.

For key-pair data:
Data must be provided in key-pair form. Multiple data structures typical of network diagrams are supported by the Javascript library, so only a minimal check is performed for conformance at the Python tier. Generally, data is shaped via nodes and edges. Nodes describe points, whereas edges describe links between nodes.

Arguments:

The data object to introspect to create an enveloping profile.
  • data: CXData

CXGenomeProfile Objects

class CXGenomeProfile(CXDataProfile)

[view_source]

render_to_profiled_dict

def render_to_profiled_dict(data: CXData, **kwargs) -> dict

[view_source]

Converts a given CXData instance into a dict suitable for use by CanvasXpress when creating data instructions for the JS object.

For matrix data:
Not supported. A TypeError will be raised.

For key-pair data:
Data is provided as-is, but it is validated to ensure that a top-tier tracks attribute of type list is present, and that child elements are dict types with type attributes specified.

Arguments:

The data object to introspect to create an enveloping profile.
  • data: CXData

CXRawProfile Objects

class CXRawProfile(CXDataProfile)

[view_source]

render_to_profiled_dict

def render_to_profiled_dict(data: CXData, **kwargs) -> dict

[view_source]

Passes the raw dict form of the CXData object with no modification.

For matrix data:
Converted by the CXData object to dict form.

For key-pair data:
Converted by the CXData object to dict form.

Arguments:

The data object to introspect to create an enveloping profile.
  • data: CXData

canvasxpress.data.url

[view_source]

CXUrlData Objects

class CXUrlData(CXData)

[view_source]

CXUrlData provides the ability to accept a URL and pass it properly to the CanvasXpress object.

url

@property
def url() -> str

[view_source]

Provides the URL formatted as a string.

Returns:

str

url

@url.setter
def url(url: str) -> None

[view_source]

Tracks the specified URL. ValueError will be raised if the URL is malformed.

Arguments:

A string form of the URL, which must be in a stanard format for
files, http resources, ftp resources, etc.
  • url: str

data

@property
def data() -> dict

[view_source]

A property accessor for the data managed by the object. Regardless of the input data the returned data structure will be a dict-type for use with CanvasXpress.

Returns:

dict

data

@data.setter
def data(data: dict) -> None

[view_source]

Sets the URL using a data dict with the following attributes: scheme, netloc, path, query, fragment, username, password, hostname, port, params. ValueError will be raised if the URL is malformed.

Arguments:

The URL as broken into a dict with the above attributes set to a
valid string for the topic or an empty string.
  • data: dict

get_raw_dict_form

def get_raw_dict_form() -> dict

[view_source]

" Provides a simple dict perspective of the data with no metadata or other contextual transformations performed. For example, if the data is natively in dict form then it would be passed-through with no modification or enhancement.

Returns:

dict

render_to_dict

def render_to_dict(**kwargs) -> dict

[view_source]

Converts the object into a dict representation.

Returns:

dict

validate_url

@classmethod
def validate_url(cls, url: str, detail_errors: bool = True) -> bool

[view_source]

Validates that the URL conforms to a recognized standard. URLs must begin with a valid scheme such as file:// or http://.

Arguments:

The string form of the URL to be validated.
True (default) if an exception should be raised with information
detailing issues or errors, or `False` if the method should
return `False` upon encountering issues.
  • url: str
  • detail_errors: bool

Returns:

bool

__init__

def __init__(data: str) -> None

[view_source]

Initializes the CXUrlData object with a valid URL. URLs must begin with a valid scheme such as file:// or http://. ValueError will be raised if the URL is malformed.

Arguments:

A string form of the URL, which must be in a stanard format for
files, http resources, ftp resources, etc.
  • data: str

canvasxpress.data.keypair

[view_source]

CXDictData Objects

@total_ordering
class CXDictData(CXKeyPairData)

[view_source]

A CXData class dedicated to processing Python dict-structured data.

data

@property
def data() -> dict

[view_source]

Provides a reference to the dict tracked by the object.

Returns:

dict

data

@data.setter
def data(value: dict) -> None

[view_source]

Sets the data associated with the object.

Arguments:

The dictionary to be tracked by the object.  `None` will result in
an empty dict.  A deep copy will be made of a valid `CXDict` or
`dict` provided.
  • value: dict

get_raw_dict_form

def get_raw_dict_form() -> dict

[view_source]

" Provides a simple dict perspective of the data with no metadata or other contextual transformations performed. For example, if the data is natively in dict form then it would be passed-through with no modification or enhancement.

This implementation provides matrix data formatted in a dict object with DataFrame.to_dict('split') behaviour.

Returns:

dict

render_to_dict

def render_to_dict(**kwargs) -> dict

[view_source]

Provides a dict representation of the data.

Returns:

dict

__init__

def __init__(data: Union[dict, None] = None, profile: Union[CXDataProfile, None] = None) -> None

[view_source]

Initializes the CXData object with data. Only dict or compatible data types are accepted.

Arguments:

`None` to initialize with an empty dictionary, or a `dict`-like
object to assign mapped data.
Specify the desired profile object to facilitate transformation of
data into a CanvasXpress JSON data object.  `None` to avoid use of
a profile.
  • data: Union[dict, None]
  • profile: Union[CXDataProfile, None]

__copy__

def __copy__() -> 'CXDictData'

[view_source]

copy constructor that returns a copy of the CXDictData object.

Returns:

CXDictData A copy of the wrapping object.

__deepcopy__

def __deepcopy__(memo) -> 'CXDictData'

[view_source]

deepcopy constructor that returns a copy of the CXDictData object.

Returns:

CXDictData A copy of the wrapping object and deepcopy of

__lt__

def __lt__(other: 'CXDictData') -> bool

[view_source]

less than comparison. Also see @total_ordering in functools.

Arguments:

`CXDictData` The object to compare.
  • other:

Returns:

bool

__eq__

def __eq__(other: 'CXDictData') -> bool

[view_source]

equals comparison. Also see @total_ordering in functools.

Arguments:

`CXDictData` The object to compare.
  • other:

Returns:

bool

__str__

def __str__() -> str

[view_source]

str function. Converts the CXDictData object into a JSON representation. :returns" str JSON form of the CXDictData.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXDictData object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

CXJSONData Objects

class CXJSONData(CXDictData)

[view_source]

A CXData class dedicated to processing JSON data.

json

@property
def json() -> str

[view_source]

Provides a copy of the JSON tracked by the object.

Returns:

str

json

@json.setter
def json(value: Union[dict, str]) -> None

[view_source]

Sets the data associated with the object.

Arguments:

The JSON to be tracked by the object.  `None` will result in
an empty JSON.  If `value` is URL beginning with *http/s*
then `json` will attempt to download the data.
  • value: str

__init__

def __init__(data: Union[dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None

[view_source]

Initializes the CXData object with data. Only dict or compatible data types are accepted.

Arguments:

`None` to initialize with an empty JSON, or a JSON/`dict`-like
object to assign mapped data.
Specify the desired profile object to facilitate transformation of
data into a CanvasXpress JSON data object.  `None` to avoid use of
a profile.
  • data: Union[dict, str, None]
  • profile: Union[CXDataProfile, None]

__copy__

def __copy__() -> 'CXJSONData'

[view_source]

copy constructor that returns a copy of the CXDictData objct.

Returns:

CXDictData A copy of the wrapping object.

__deepcopy__

def __deepcopy__(memo) -> 'CXJSONData'

[view_source]

deepcopy constructor that returns a copy of the CXJSONData object.

Returns:

CXJSONData A copy of the wrapping object and deepcopy of

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CXJSONData object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.

canvasxpress.data.text

[view_source]

CXTextData Objects

class CXTextData(CXData)

[view_source]

CXTextData is a CXData class that provides plain-text data directly to the CanvasXpress for Javascript object. In this manner, the Python tier makes no assumptions about the data content and permits the Javascript tier to address any required adjustments in order to properly display the data within a chart. If the data is erroneously formatted then the only feedback will be at the Javascript tier.

text

@property
def text() -> str

[view_source]

Returns the raw text form of the data.

Returns:

str

text

@text.setter
def text(value: str) -> None

[view_source]

Sets the text to be provided to CanvasXpress.

Arguments:

The text to provide as-is to CanvasXpress.  `None` will be
converted to an empty `str`.  Values of type other than `str`
will be converted using `str()`.
  • value: str

data

@property
def data() -> dict

[view_source]

A property accessor for the data managed by the object. Regardless of the input data the returned data structure will be a dict-type for use with CanvasXpress.

Returns:

dict

get_raw_dict_form

def get_raw_dict_form() -> dict

[view_source]

" Provides a simple dict perspective of the data with no metadata or other contextual transformations performed. For example, if the data is natively in dict form then it would be passed-through with no modification or enhancement.

Returns:

dict

render_to_dict

def render_to_dict(**kwargs) -> dict

[view_source]

Converts the object into a dict representation.

Returns:

dict

__init__

def __init__(data: Union[object, None] = None) -> None

[view_source]

Initializes the CXData object with data.

Arguments:

Given an object or no data prepares a new CXData instance ready for
use by a `CanvasXpress` object.
  • data: Union[object, None]

canvasxpress.data.base

[view_source]

CXData Objects

class CXData(CXDictConvertable)

[view_source]

CXData defines an essential data class for managing data acquisiton, transformation, and introspection as required by the CanvasXPress class.

data

@property
@abstractmethod
def data() -> dict

[view_source]

A property accessor for the data managed by the object. Regardless of the input data the returned data structure will be a dict-type for use with CanvasXpress.

Returns:

dict

get_raw_dict_form

@abstractmethod
def get_raw_dict_form() -> dict

[view_source]

" Provides a simple dict perspective of the data with no metadata or other contextual transformations performed. For example, if the data is natively in dict form then it would be passed-through with no modification or enhancement.

Returns:

dict

__init__

@abstractmethod
def __init__(data: Union[object, None]) -> None

[view_source]

Initializes the CXData object with data.

Arguments:

Given an object or no data prepares a new CXData instance ready for
use by a `CanvasXpress` object.
  • data: Union[object, None]

CXDataProfileException Objects

class CXDataProfileException(ValueError)

[view_source]

CXDataProfileException is used by CXDataProfile to describe validation errors when considering CXData objects in the context of CXDataProfile objects.

CXDataProfile Objects

class CXDataProfile(ABC)

[view_source]

CXDataProfile assists with CXData translations into CanvasXpress JSON data formats, such as documented at CanvasXpress.org.

render_to_profiled_dict

@abstractmethod
def render_to_profiled_dict(data: CXData, **kwargs) -> dict

[view_source]

Converts a given CXData instance into a dict suitable for use by CanvasXpress when creating data instructions for the JS object.

CXProfiledData Objects

class CXProfiledData(CXData)

[view_source]

CXData defines an essential data class for managing data acquisiton, transformation, and introspection as required by the CanvasXPress class.

profile

@property
def profile() -> Union[None, CXDataProfile]

[view_source]

Provides the CXDataProfile associated with the CXData instance.

Returns:

Union[None, CXDataProfile]

profile

@profile.setter
def profile(profile: Union[None, CXDataProfile]) -> None

[view_source]

Sets the CXDataProfile associated with the CXData instance. The default associated profile is CXStandardProfile, which supports the most typical CanvasXpress JSON data format for plotting. To avoid the use of a profile and pass only a basic raw JSON edition of the instance to CanvasXpress set the profile to None.

Arguments:

The profile to use when transforming the `CXData` instance into a
CanvasXpress JSON data object.  Use `None` to avoid any
transformation beyond the essential conversion of the instance into
a JSON-like form.  For example, with `None` if the data tracked is
a dict then the renderer would simply pass the data through.
  • profile: Union[None, CXDataProfile]

data

@property
@abstractmethod
def data() -> dict

[view_source]

A property accessor for the data managed by the object. Regardless of the input data the returned data structure will be a dict-type for use with CanvasXpress.

Returns:

dict

__init__

def __init__(data: Union[object, None], profile: Union[CXDataProfile, None] = None) -> None

[view_source]

Initializes the CXData object with data.

Arguments:

Given an object or no data prepares a new CXData instance ready for
use by a `CanvasXpress` object.
Specify the desired profile object to facilitate transformation of
data into a CanvasXpress JSON data object.  `None` to avoid use of
a profile.
  • data: Union[object, None]
  • profile: Union[CXDataProfile, None]

CXKeyPairData Objects

class CXKeyPairData(CXProfiledData)

[view_source]

CXKeyPairData is a marker class to indicate that the data managed will be generally of the structure key-pair. A dict is an example of key-pair data.

CXMatrixData Objects

class CXMatrixData(CXProfiledData)

[view_source]

CXMatrixData is a marker class to indicate that the data management will be generally of the structure matrix or tabular. A spreadsheet is an example of matrix data.

canvasxpress.canvas

[view_source]

CanvasXpress Objects

class CanvasXpress(CXHtmlConvertable)

[view_source]

CanvasXpress acts as a proxy to the Javascript CanvasXpress object, and in general use remains similar to its Javascript counterpart.

Assuming a flask function that returns a rendered page using the data from a CanvasXpress object:

@app.route('/pythonexample')
def get_simple_chart() -> str:
    chart: CanvasXpress = CanvasXpress(
        render_to="example_chart",
        data=CXDictData(
            {
                "y": {
                "vars": ["Gene1"],
                "smps": ["Smp1", "Smp2", "Smp3"],
                "data": [[10, 35, 88]],
            }
        ),
        config=CXConfigs(
            CXGraphType(CXGraphTypeOptions.Bar)
        )
    )

    html_parts = chart.render_to_html_parts()

    return render_template(
        "bar.html",
        canvas_element=html_parts["cx_canvas"],
        bar_graph=html_parts["cx_js"]
    )

render_to

@property
def render_to() -> str

[view_source]

The ID of the CanvasXpress object's associated HTML components, such as the render canvas element. Sets the id attribute of the <canvas> element.

Returns:

str The ID

render_to

@render_to.setter
def render_to(value: str) -> None

[view_source]

Sets the render_to of the CanvasXpress instance. Sets the id attribute of the <canvas> element.

Arguments:

`str` The ID to be associated.  Cannot be `None`, and
must be alphanumeric.  Non-alphanumeric characters will
be removed, except for `_`, and if the remaining string
is empty then a UUID4 will be substituted.  This is to preserve JS
compatibility during rendering.
  • value:

license_available

@property
def license_available() -> bool

[view_source]

Indicates if a license is associated with the CanvasXpress object.

Returns:

True if a license file URL has been set.

license_url

@property
def license_url() -> str

[view_source]

Returns the location of the license file associated with the CanvasXpress object.

Returns:

str URL of the file or None if no file is associated.

license_url

@license_url.setter
def license_url(value: str) -> None

[view_source]

Sets the location of the license file to be associated with the CanvasXpress object.

Arguments:

`str` The path to the license file or `None` if a previously set URL
is no longer valid.
  • value:

CHART_WIDTH_DEFAULT

[view_source]

Default width of the chart when rendered, such as into HTML.

width

@property
def width() -> int

[view_source]

Indicates the preferred Web element width when rendered. This property is used to facilitate integration with Web containers such as Jupyter notebooks. Added to the <canvas> element, and also influences render containers for contexts such as Jupyter Notebooks.

Returns:

int The width

width

@width.setter
def width(value: int)

[view_source]

Sets the preferred Web element width when rendered. Added to the <canvas> element, and also influences render containers for contexts such as Jupyter Notebooks.

Arguments:

The pixel count.  Cannot be `None` or less than `1`.
  • value: int

CHART_HEIGHT_DEFAULT

[view_source]

Default height of the chart in pixels when rendered, such as into HTML.

height

@property
def height() -> int

[view_source]

Indicates the preferred Web element height when rendered. This property is used to facilitate integration with Web containers such as Jupyter notebooks. Added to the <canvas> element, and also influences render containers for contexts such as Jupyter Notebooks.

Returns:

int The pixel count

height

@height.setter
def height(value: int)

[view_source]

Sets the preferred Web element height when rendered. Added to the <canvas> element, and also influences render containers for contexts such as Jupyter Notebooks.

Arguments:

  • value: int

data

@property
def data() -> CXData

[view_source]

Provides access to the CXData associated with this CanvasXpress chart.

Returns:

CXData The data to be associated with the chart.

data

@data.setter
def data(value: Union[CXData, dict, DataFrame, str, None]) -> None

[view_source]

Sets the CXData associated with this CanvasXpress chart.

Arguments:

An object translatable into a CXData type. If the object is an
instance of CXData then it will be tracked by the CanvasXpress
object; otherwise, a new CXData object will be created to manage
the content.
  • value: Union[CXData, dict, DataFrame, str, None]

events

@property
def events() -> CXEvents

[view_source]

Provides access to the CXEvents associated with this CanvasXpress chart.

Returns:

CXEvents The events to be associated with the chart.

events

@events.setter
def events(events: Union[CXEvents, List[CXEvent], None]) -> None

[view_source]

Sets the CXEvents associated with this CanvasXpress chart.

Arguments:

`CXEvents, List[CXEvent], None` An object translatable into a
CXEvents type.  If the object is an instance of CXEvents then it
will be tracked by the CanvasXpress object; otherwise, a new
CXEvents object will be created to manage the content.
  • events:

config

@property
def config() -> CXConfigs

[view_source]

Provides access to the CXConfigs associated with this CanvasXpress chart.

Returns:

CXConfigs The config to be associated with the chart.

config

@config.setter
def config(value: Union[
                List[CXConfig],
                List[tuple],
                List[list],
                dict,
                CXConfigs
            ])

[view_source]

Sets the CXConfigs associated with this CanvasXpress chart.

Arguments:

    List[CXConfig],
    List[tuple],
    List[list],
    dict,
    CXConfigs
]`
An object translatable into a CXConfigs type.  If the object is an
instance of CXConfigs then it will be
tracked by the CanvasXpress object; otherwise, a new CXConfigs
object will be created to manage the content.
  • value: `Union[

after_render

@property
def after_render() -> CXConfigs

[view_source]

Provides access to the CXConfigs associated with this CanvasXpress chart's afterRender property.

Returns:

CXConfigs

after_render

@after_render.setter
def after_render(value: Union[
                List[CXConfig],
                List[tuple],
                List[list],
                dict,
                CXConfigs
            ])

[view_source]

Sets the CXConfigs associated with this CanvasXpress chart's afterRender property.

Arguments:

CXConfigs]`
An object translatable into a CXConfigs
type.  If the object is an instance of CXConfigs then it will be
tracked by the CanvasXpress object; otherwise, a new CXConfigs
object will be created to manage the content.
  • value: `Union[List[CXConfig], List[tuple], dict, CXConfigs,

canvas

@property
@deprecated(reason="Use other_init_params")
def canvas() -> CXConfigs

[view_source]

DEPRECATED. See other_init_params.

canvas

@canvas.setter
@deprecated(reason="Use other_init_params")
def canvas(value: Union[
                List[CXConfig],
                List[tuple],
                List[list],
                dict,
                CXConfigs
            ])

[view_source]

DEPRECATED. See other_init_params.

other_init_params

@property
def other_init_params() -> CXConfigs

[view_source]

Provides access to additional parameters that will be used with the CanvasXpress for Javascript constructor, such as afterRencderInit.

Returns:

CXConfigs

other_init_params

@other_init_params.setter
def other_init_params(value: Union[
                List[CXConfig],
                List[tuple],
                List[list],
                dict,
                CXConfigs
            ])

[view_source]

Set the additional parameters to be used with the CanvasXpress for Javascript constructor, such as afterRencderInit. The following parameters will be ignored and the properties for this class should be used instead due to Python tier functionality useful to the developer:

  • renderTo: Use CanvasXpress.render_to
  • data: Use CanvasXpress.data
  • config: Use CanvasXpress.config
  • afterRender: Use CanvasXpress.after_render
  • width: Use CanvasXpress.width
  • height: Use CanvasXpress.height

Arguments:

CXConfigs]`
An object translatable into a CXConfigs type.  If the object is an
instance of CXConfigs then it will be tracked by the CanvasXpress
object; otherwise, a new CXConfigs object will be created to manage
the content.
  • value: `Union[List[CXConfig], List[tuple], List[list], dict,

from_reproducible_json

@classmethod
def from_reproducible_json(cls, cx_json: str, include_factory: bool = False, include_system: bool = False) -> 'CanvasXpress'

[view_source]

Initializes a new CanvasXpress object using a reproducable research JSON saved from a CanvasXpress chart rendered in a Web browser.

Arguments:

A valid reproducable research JSON typical of those created by
CanvasXpress when running a Web browser.

Default `False`.  If `False` remove the `factory` attribute.

Default `False`.  If `False` remove the `system` attribute.
  • cx_json: str
  • include_factory: bool
  • include_system: bool

Returns:

CanvasXpress

__init__

def __init__(render_to: str = None, data: Union[CXData, dict, DataFrame, str, None] = None, events: Union[List[CXEvent], CXEvents] = None, config: Union[List[CXConfig], List[tuple], dict, CXConfigs] = None, after_render: Union[
                List[CXConfig], List[tuple], dict, CXConfigs
            ] = None, other_init_params: Union[
                List[CXConfig], List[tuple], dict, CXConfigs
            ] = None, canvas: Union[
                List[CXConfig], List[tuple], dict, CXConfigs
            ] = None, width: int = CHART_WIDTH_DEFAULT, height: int = CHART_HEIGHT_DEFAULT) -> None

[view_source]

Initializes a new CanvasXpress object. Default values are provided for all parameters if values are not specified; otherwise the arguments are treated as if an appropriate setter were used.

Arguments:

initialization the object will be assigned an UUID4 value.
  • render_to: See render_to property, except that on default
  • data: See the data property
  • events: See the events property
  • config: See the config property
  • after_render: See the after_render property
  • other_init_params: See the 'other_init_params` property
  • canvas: DEPRECATED, use other_init_params
  • width: See the width property
  • height: See the height property

update_data_profile

def update_data_profile(data: CXData, fix_missing_profile: bool, match_profile_to_graphtype: bool)

[view_source]

Inspects the CXData object to see if it is a CXProfiledData object. If so, then fix_missing_profile and match_profile_to_graphtype are evaluated to determine if profile adjustments are to be made, and then applied if/as appropriate.

Arguments:

The data to inspect.  Only `CXProfiledData` objects will be 
modified.

Defaults to `True`.  If `True` then CXData used for the chart will
be provided with a data profile appropriate to the `graphType`
(or CXStandardProfile if no graphType is provided).  If `False`
then no profile will be applied to those data objects without
profiles.

Defaults to `True`.  If `True` then the `graphType` will be
inspected and an appropriate data profile will be applied to
the data object.  If a profile of an appropriate type is already
associated then nothing is changed.  If a CXRawProfile is associated
then no change is made regardless of the paranmeter value.
Missing profiles are ignored unless fix_missing_profile is also
`True`.  If `False` then no change to the data profile will be made
if a profile is already associated with the data object.
  • data: CXData
  • fix_missing_profile: bool
  • match_profile_to_graphtype: bool

render_to_html_parts

def render_to_html_parts(fix_missing_profile: bool = True, match_profile_to_graphtype: bool = True) -> dict

[view_source]

Converts the CanvasXpress object into HTML5 complant script.

If the associated CXData is a type of CXProfiledData and a profile has yet to be assigned then a profile can be assigned according to the CXConfig labelled graphType. If a profile is assigned but is not CXRawProfile then the graphType can be reassessed, and if appropriate a new profile better aligned to the data can be provided.

Returns:

dict A map of values appropriate for use in HTML, such as

Arguments:

Defaults to `True`.  If `True` then CXData used for the chart will
be provided with a data profile appropriate to the `graphType`
(or CXStandardProfile if no graphType is provided).  If `False`
then no profile will be applied to those data objects without
profiles.

Defaults to `True`.  If `True` then the `graphType` will be
inspected and an appropriate data profile will be applied to
the data object.  If a profile of an appropriate type is already
associated then nothing is changed.  If a CXRawProfile is associated
then no change is made regardless of the paranmeter value.
Missing profiles are ignored unless fix_missing_profile is also
`True`.  If `False` then no change to the data profile will be made
if a profile is already associated with the data object.
  • fix_missing_profile: bool
  • match_profile_to_graphtype: bool

__str__

def __str__() -> str

[view_source]

str function. Converts the CanvasXpress object into a JSON representation. :returns" str JSON form of the CanvasXpress object.

__repr__

def __repr__() -> str

[view_source]

repr function. Converts the CanvasXpress object into a pickle string that can be used with eval to establish a copy of the object.

Returns:

str An evaluatable representation of the object.