canvasxpress
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
canvasxpress.util.example
canvasxpress.util.example.generator
generate_canvasxpress_code_from_json_file
generate_canvasxpress_code_from_json_file(cx_json_path: str, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str
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:strdocument_includes:booldocument_render:booldocument_jupyter_render:bool
Returns:
str
generate_canvasxpress_code_from_json
generate_canvasxpress_code_from_json(cx_json: str, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str
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:strdocument_includes:booldocument_render:booldocument_jupyter_render:bool
Returns:
str
generate_canvasxpress_code
generate_canvasxpress_code(cx: CanvasXpress, document_includes: bool = True, document_render: bool = True, document_jupyter_render=False) -> str
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:CanvasXpressdocument_includes:booldocument_render:booldocument_jupyter_render:bool
Returns:
str
canvasxpress.util.example.generate_tutorials
This file can be executed to render the reproducible JSON files located at
[project]/tutorials/reproducible_json/*.json into tutorials for general use.
get_json_file_paths
get_json_file_paths() -> List[str]
Returns a list of all reproducible JSON files tracked for tutorials.
Returns:
list[str]
get_type_from_filename
get_type_from_filename(file_name: str) -> str
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
get_index_from_filename(file_name: str) -> str
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
create_jupyer_template_text(chart_type: str, chart_index: str, chart_code: str) -> str
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:strchart_code:str
Returns:
str
canvasxpress.util.template
render_from_template
render_from_template(template: str, data: dict) -> str
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
The config package provides functionality for managing or assigning configuration values associated with CanvasXpress objects.
canvasxpress.config.type
CXConfig Objects
@total_ordering
class CXConfig(ABC)
CXConfig provides the means by which CanvasXpress objects can be configured for customized rendering and interaction.
label
| @property
| label() -> str
Provides the label for the configuration.
Returns:
str
value
| @property
| @abstractmethod
| value() -> Any
Provides the value for the configuration. Must be implemented by concrete classes.
Returns:
Any
value
| @value.setter
| @abstractmethod
| value(value: Any) -> None
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
| render() -> dict
Renders the value in a form suitable for use in preparing Javascript.
Typically, this will be the native value.
Returns:
dict
__init__
| __init__(label: str, value: Any)
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:strvalue:Any
__copy__
| __copy__() -> "CXConfig"
copy constructor that provides a new CXConfig of the same type with the data referenced.
Returns:
CXConfig of the proper type
__deepcopy__
| __deepcopy__(memo)
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__
| __hash__() -> int
Provides a hash proxy for the object as converted into its repr form.
Returns:
int
__lt__
| __lt__(other: "CXConfig") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXConfig` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXConfig") -> bool
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXConfig` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
str function. Converts the object into a JSON string.
__repr__
| __repr__() -> str
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)
A CXConfig object that manages str values.
value
| @property
| value() -> str
Provides the value for the configuration.
Returns:
str
value
| @value.setter
| value(value: Union[object, str]) -> None
Sets the value of the configuration.
Arguments:
If `None` then an empty `str` will be used.
value:str
__init__
| __init__(label: str, value: str)
Initializes the configuration with a str value.
CXBool Objects
class CXBool(CXConfig)
A CXConfig object that manages bool values.
value
| @property
| value() -> bool
Provides the value for the configuration.
Returns:
bool
value
| @value.setter
| value(value: Union[object, bool]) -> None
Sets the value of the configuration.
Arguments:
If `None` then `False` will be used.
value:bool
__init__
| __init__(label: str, value: bool)
Initializes the configuration with a bool value.
__str__
| __str__() -> str
str function. Converts the object into a Javascript statement.
__repr__
| __repr__() -> str
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)
A CXConfig object that manages float values.
value
| @property
| value() -> float
Provides the value for the configuration.
Returns:
float
value
| @value.setter
| value(value: Union[object, float]) -> None
Sets the value of the configuration.
Arguments:
If `None` then `float(0.0)` will be used.
value:float
__init__
| __init__(label: str, value: float)
Initializes the configuration with a float value.
CXInt Objects
class CXInt(CXConfig)
A CXConfig object that manages int values.
value
| @property
| value() -> int
Provides the value for the configuration.
Returns:
int
value
| @value.setter
| value(value: Union[object, int]) -> None
Sets the value of the configuration.
Arguments:
If `None` then `int(0)` will be used.
value:int
__init__
| __init__(label: str, value: int)
Initializes the configuration with an int value.
CXDict Objects
class CXDict(CXConfig)
A CXConfig object that manages dict values.
value
| @property
| value() -> dict
Provides the value for the configuration.
Returns:
dict
value
| @value.setter
| value(value: Union[dict, str, None]) -> None
Sets the value of the configuration.
Arguments:
If `None` then `dict()` will be used.
value:dict
__init__
| __init__(label: str, value: Union[dict, str, None]) -> None
Initializes the CXData object with data. Only dict or compatible data types are accepted.
__lt__
| __lt__(other: "CXDict") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXDict` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXDict") -> bool
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXDict` The object to compare.
other:
Returns:
bool
__repr__
| __repr__() -> str
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)
A CXConfig object that manages list values.
value
| @property
| value() -> list
Provides the value for the configuration.
Returns:
list
value
| @value.setter
| value(value: Union[object, list]) -> None
Sets the value of the configuration.
Arguments:
If `None` then `list()` will be used.
value:list
__init__
| __init__(label: str, value: list)
Initializes the configuration with a list value.
CXRGBAColor Objects
class CXRGBAColor(CXDict)
A CXConfig object that manages str Javascript rgba() values.
is_color_str
| @staticmethod
| is_color_str(value: str)
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
| is_color_list(value: list)
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
| is_color_dict(value: dict)
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
| value(value: Union["CXRGBAColor", dict, list, str]) -> None
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
| render() -> Any
Renders the value in a form suitable for use in preparing Javascript.
Typically, this will be the native value.
Returns:
Any
__init__
| __init__(label: str, value: Union["CXRGBAColor", dict, list, str])
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__
| __str__() -> str
str function. Converts the object into a JSON string.
__repr__
| __repr__() -> str
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)
A CXConfig object that manages str Javascript rgb() values.
is_color_str
| @staticmethod
| is_color_str(value: str)
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
| is_color_list(value: list)
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
| is_color_dict(value: dict)
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
| value(value: Union["CXRGBColor", dict, list, str]) -> None
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
| render() -> dict
Renders the value in a form suitable for use in preparing Javascript.
Typically, this will be the native value.
Returns:
Any
__init__
| __init__(label: str, value: Union["CXRGBColor", dict, list, str])
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__
| __str__() -> str
str function. Converts the object into a JSON string.
__repr__
| __repr__() -> str
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)
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)
A CXString that is aware of CanvasXpress types of graphs, such as 'Bar'.
value
| @CXString.value.setter
| value(value: Union[CXGraphTypeOptions, str]) -> None
Sets the value using a known CanvasXpress option.
set_custom_value
| set_custom_value(value: str)
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
| render() -> dict
Renders the value in a form suitable for use in preparing Javascript.
Typically, this will be the native value.
Returns:
dict
__init__
| __init__(type: Union[CXGraphTypeOptions, str] = CXGraphTypeOptions.Bar)
Initializes a new CXGraphType object with a value corresponding to one
of the values provided by CXGraphTypeOptions.
canvasxpress.config.collection
CXConfigs Objects
@total_ordering
class CXConfigs(CXDictConvertable, CXListConvertable)
CXConfigs provides support for addressing a collection of CXConfig values.
__init__
| __init__(*configs: Union[CXConfig, tuple, dict, list])
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
| remove(label: str) -> Union[CXConfig, None]
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
| add(config: Union[CXConfig, tuple, dict, list]) -> "CXConfigs"
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
| get_param(label: str) -> Union[CXConfig, None]
Provides the CXConfig with the indicated label.
Arguments:
The name of the congig to find.
label:str
Returns:
Union[CXConfig, None]
set_param
| set_param(label: str, value: Any) -> "CXConfigs"
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
| configs() -> List[CXConfig]
Provides access to the list of associated CXConfig objects.
Returns:
List[CXConfig]
render_to_dict
| render_to_dict() -> dict
Provides a dict representation of the configuration values.
Returns:
dict
render_to_list
| render_to_list(**kwargs) -> list
Provides a list representation of the configuration values.
Returns:
list
merge_configs
| @classmethod
| merge_configs(cls, configs: List[CXConfig]) -> dict
Given a list of CXConfig objects, a dictionary of unique attributes is generated and provided.
Returns:
dict
__copy__
| __copy__() -> "CXConfigs"
copy constructor. Returns the CXConfig objects within a new
CXConfigs object.
__deepcopy__
| __deepcopy__(memo) -> "CXConfigs"
deepcopy constructor. Returns a deepcopy of the CXConfig objects
within a new CXConfigs object.
__lt__
| __lt__(other: "CXConfigs") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXConfigs` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXConfigs") -> bool
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXConfigs` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
str function. Converts the CXConfigs object into a JSON
representation.
:returns" str
JSON form of the collection.
__repr__
| __repr__() -> str
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
The js package provides functionality for integrating custom Javascript with CanvasXpress charts.
canvasxpress.js.collection
CXEvents Objects
@total_ordering
class CXEvents(CXJavascriptConvertable)
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
| events() -> List[CXEvent]
Provides a non-associated list of the associated CXEvents.
Returns:
List[CXEvent] A list of zero or more CXEvent objects.
has
| has(event: CXEvent) -> bool
Indicates if the CXEvent is a member.
Arguments:
event: TheCXEventto consider.
Returns:
bool True if event is a member.
add
| add(event: CXEvent, unique: bool = True) -> None
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
| remove(event: CXEvent) -> bool
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
| render_to_dict() -> dict
Provides a dict with each js properly formatted as JS within.
Returns:
dict
render_to_js
| render_to_js() -> str
Converts the object into HTML5 complant script.
Returns:
'str'
__init__
| __init__(*events)
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__
| __copy__()
copy constructor. Returns the CXEvent objects within a new CXEvents
object.
__deepcopy__
| __deepcopy__(memo)
deepcopy constructor. Returns a deep copy of CXEvent objects within
a new CXEvents object.
__lt__
| __lt__(other: "CXEvents")
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXEvent` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXEvents")
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXEvent` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
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__
| __repr__() -> str
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
CXEvent Objects
@total_ordering
class CXEvent(CXJavascriptConvertable)
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
| id() -> str
Provides access to the react ID.
Returns:
The ID as a string.
id
| @id.setter
| id(value: str) -> None
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
| script() -> str
Provides access to the react script.
Returns:
str The Javascript source.
script
| @script.setter
| script(value: str) -> None
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
| render_to_js() -> str
Converts the object into HTML5 complant script.
Returns:
'str'
__init__
| __init__(id: str = "", script: str = "")
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:strscript:str
__copy__
| __copy__()
copy constructor. Returns a new CXEvent object.
__deepcopy__
| __deepcopy__(memo)
deepcopy constructor. Returns a new CXEvent object.
__lt__
| __lt__(other: "CXEvent") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXEvent` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXEvent") -> bool
equal comparison. Also see @total_ordering in functools.
Arguments:
`CXEvent` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
str function. Converts the object into a Javascript statement.
__repr__
| __repr__() -> str
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
The render package provides functionality for rendering CanvasXpress objects in containers or environments
canvasxpress.render.popup
CXBrowserPopup Objects
class CXBrowserPopup(CXRenderable)
CXBrowserPopup is a CXRenderable that renders CanvasXpress objects into
a Web page that is displayed in a pop-up browser window.
__init__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
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
| render(**kwargs: Any)
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.dash
This module provides an integration solution for the CanvasXpress class and the base dash component for a feature- rich integration with Plotly's Dash framework.
CXElementFactory Objects
class CXElementFactory(CXRenderFactory)
CXDashElementFactory converts CanvasXpress objects into PlotlyDash elements that will render CanvasXpress charts into the Dash UI.
__init__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
Initializes a new CXDashRenderFactory object.
Arguments:
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.
cx:Union[List[CanvasXpress], CanvasXpress, None], ...
render
| @classmethod
| render(cls, cx: CanvasXpress) -> CXDashElement
Converts the provided CanvasXpress object into a CXDashElement object that is primed by the configuration represented by the CanvasXpress object.
Arguments:
raised if cx is `None`.
cx:CanvasXpressThe CanvasXpress object to render. An exception is
Returns:
CXDashElement A CXDashElement with the configuration as represented
render_all
| render_all(**kwargs: Any) -> List[CXDashElement]
Provides a list of objects that can be used by the target domain or container to create CanvasXpress illustrations or instantiations. Not implemented.
Arguments:
Parameters specific to implementations are supported. The essential
create_element call should work with no extra parameters, and with
parameters that do not apply to the implementation.
kwargs:Any
canvasxpress.render.base
CXRenderAssociation Objects
class CXRenderAssociation(ABC)
CXRenderAssociation tracks A set of CanvasXpress objects that will be used to produce a domain- or container-specific rendering (e.g., for display in a Jupyter notebook).
canvas
| @property
| canvas() -> Union[List[CanvasXpress], CanvasXpress, None]
Provides the tracked CanvasXpress object.
Returns:
value: Union[List[CanvasXpress], CanvasXpress, None]
canvas
| @canvas.setter
| canvas(value: Union[List[CanvasXpress], CanvasXpress, None])
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__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
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.
CXRenderable Objects
class CXRenderable(CXRenderAssociation)
CXRenderable is capable of rendering a CanvasXpress object to some kind of output or display device.
__init__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
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
| render(**kwargs: Any)
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
CXRenderFactory Objects
class CXRenderFactory(CXRenderAssociation)
CXRenderFactory produces objects for use in a container or framework that understand how to cooperate with the framework to produce CanvasXpress illustrations.
__init__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
Initializes a new CXRenderFactory 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_all
| @abstractmethod
| render_all(**kwargs: Any) -> List[object]
Provides a list of objects that can be used by the target domain or container to create CanvasXpress illustrations or instantiations. 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
CXNoteBook Objects
class CXNoteBook(CXRenderable)
CXNoteBook is a CXRenderable that renders CanvasXpress objects into
IPython containers (Jupyter Notebooks).
__init__
| __init__(*cx: Union[List[CanvasXpress], CanvasXpress, None])
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
| render(**kwargs: Any)
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
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
CXDataframeData Objects
@total_ordering
class CXDataframeData(CXMatrixData)
A CXData class dedicated to processing Python DataFrame, matrix-structured data.
dataframe
| @property
| dataframe() -> DataFrame
Provides the data managed by the object.
Returns:
DataFrame The managed data.
dataframe
| @dataframe.setter
| dataframe(value: Union[DataFrame, None] = None) -> None
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
| data() -> dict
Provides the data managed by the object.
Returns:
DataFrame The managed data.
data
| @data.setter
| data(value: Union["CXDataframeData", DataFrame, dict, str, None] = None) -> None
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
| get_raw_dict_form() -> dict
"
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
| render_to_dict(**kwargs) -> dict
Provides a dict representation of the data.
Returns:
dict
__init__
| __init__(data: Union["CXDataframeData", DataFrame, dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None
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` will default to
the CXStandardProfile.
data:Union['CXDataframeData', DataFrame, dict, str, None]profile:Union[CXDataProfile, None]
__copy__
| __copy__() -> "CXDataframeData"
copy constructor that returns a copy of the CXDataframeData object.
Returns:
CXDataframeData
__deepcopy__
| __deepcopy__(memo) -> "CXDataframeData"
deepcopy constructor that returns a copy of the CXDataframeData object.
Returns:
CXDataframeData A copy of the wrapping object and deepcopy of
__lt__
| __lt__(other: "CXDataframeData") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXDataframeData` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXDataframeData") -> bool
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXDataframeData` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
str function. Converts the CXDataframeData object into a JSON
representation.
:returns" str JSON form of the CXDataframeData.
__repr__
| __repr__() -> str
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)
A CXData class dedicated to processing Python CSV-based, matrix-structured data.
csv
| @property
| csv() -> str
Provides the data managed by the object.
Returns:
str The managed data.
csv
| @csv.setter
| csv(value: str = None) -> None
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__
| __init__(data: Union["CXCSVData", DataFrame, dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None
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__
| __str__() -> str
str function. Converts the CXCSVData object into a JSON
representation.
:returns" str JSON form of the CXCSVData.
__repr__
| __repr__() -> str
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
CXHtmlConvertable Objects
class CXHtmlConvertable(ABC)
CXHtmlConvertable represents an object that can be converted into HTML.
render_to_html_parts
| @abstractmethod
| render_to_html_parts() -> dict
Converts the object into HTML5 compliant script.
Returns:
dict
CXDictConvertable Objects
class CXDictConvertable(ABC)
CXDictConvertable represents an object that can be converted into a dict.
render_to_dict
| @abstractmethod
| render_to_dict(**kwargs) -> dict
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)
CXListConvertable represents an object that can be converted into a list.
render_to_list
| @abstractmethod
| render_to_list(**kwargs) -> list
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)
CXJavascriptConvertable represents an object that can be converted into JS.
render_to_js
| @abstractmethod
| render_to_js() -> str
Converts the object into HTML5 complant script.
Returns:
str
canvasxpress.data.profile
CXStandardProfile Objects
class CXStandardProfile(CXDataProfile)
CXStandardProfile provides standard chart data profile functionality,
by which the topics of y, x, and z are handled in conversions.
vars
| @property
| vars() -> list
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
| vars(variables: Union[list, None]) -> None
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
| smps() -> list
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
| smps(samples: Union[list, None]) -> None
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
| y(value: Union[dict, None]) -> None
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
| x(value: Union[DataFrame, dict, None]) -> None
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
| z(value: Union[DataFrame, dict, None]) -> None
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
| match_vars_to_rows() -> bool
Indicates whether vars will be match to rows when formatting data.
Returns:
bool
match_vars_to_rows
| @match_vars_to_rows.setter
| match_vars_to_rows(value: bool) -> None
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
| match_smps_to_cols() -> bool
Indicates whether smps will be match to columns when formatting data.
Returns:
bool
match_smps_to_cols
| @match_smps_to_cols.setter
| match_smps_to_cols(value: bool) -> None
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
| match_x_to_smps() -> bool
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
| match_x_to_smps(value: bool) -> None
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
| match_z_to_vars() -> bool
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
| match_z_to_vars(value: bool) -> None
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
| add_data_section(section: str, source: dict, target: dict) -> None
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:strsource:dicttarget:dict
render_to_profiled_dict
| render_to_profiled_dict(data: CXData, **kwargs, ,) -> dict
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:CXDatamatch_vars_to_rows:boolmatch_smps_to_cols:boolmatch_x_to_smps:boolmatch_z_to_vars:bool
Returns:
dict
__init__
| __init__()
Initializes the CXStandardProfile object.
CXVennProfile Objects
class CXVennProfile(CXDataProfile)
CXVennProfile provides Venn diagram chart data profile functionality,
by which the topics of venn and legend are handled in conversions.
legend
| @property
| legend() -> dict
Returns the values to be used for the legend if such are not defined in the data.
Returns:
dict
legend
| @legend.setter
| legend(value: Union[dict, None]) -> None
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
| render_to_profiled_dict(data: CXData, **kwargs) -> dict
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)
render_to_profiled_dict
| render_to_profiled_dict(data: CXData, **kwargs) -> dict
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)
render_to_profiled_dict
| render_to_profiled_dict(data: CXData, **kwargs) -> dict
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)
render_to_profiled_dict
| render_to_profiled_dict(data: CXData, **kwargs) -> dict
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
CXUrlData Objects
class CXUrlData(CXData)
CXUrlData provides the ability to accept a URL and pass it properly to the CanvasXpress object.
url
| @property
| url() -> str
Provides the URL formatted as a string.
Returns:
str
url
| @url.setter
| url(url: str) -> None
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
| data() -> dict
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
| data(data: dict) -> None
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
| get_raw_dict_form() -> dict
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
| render_to_dict(**kwargs) -> dict
Converts the object into a dict representation.
Returns:
dict
validate_url
| @classmethod
| validate_url(cls, url: str, detail_errors: bool = True) -> bool
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:strdetail_errors:bool
Returns:
bool
__init__
| __init__(data: str) -> None
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
CXDictData Objects
@total_ordering
class CXDictData(CXKeyPairData)
A CXData class dedicated to processing Python dict-structured data.
data
| @property
| data() -> dict
Provides a reference to the dict tracked by the object.
Returns:
dict
data
| @data.setter
| data(value: dict) -> None
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
| get_raw_dict_form() -> dict
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
| render_to_dict(**kwargs) -> dict
Provides a dict representation of the data.
Returns:
dict
__init__
| __init__(data: Union[dict, None] = None, profile: Union[CXDataProfile, None] = None) -> None
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__
| __copy__() -> "CXDictData"
copy constructor that returns a copy of the CXDictData object.
Returns:
CXDictData A copy of the wrapping object.
__deepcopy__
| __deepcopy__(memo) -> "CXDictData"
deepcopy constructor that returns a copy of the CXDictData object.
Returns:
CXDictData A copy of the wrapping object and deepcopy of
__lt__
| __lt__(other: "CXDictData") -> bool
less than comparison. Also see @total_ordering in functools.
Arguments:
`CXDictData` The object to compare.
other:
Returns:
bool
__eq__
| __eq__(other: "CXDictData") -> bool
equals comparison. Also see @total_ordering in functools.
Arguments:
`CXDictData` The object to compare.
other:
Returns:
bool
__str__
| __str__() -> str
str function. Converts the CXDictData object into a JSON
representation.
:returns" str JSON form of the CXDictData.
__repr__
| __repr__() -> str
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)
A CXData class dedicated to processing JSON data.
json
| @property
| json() -> str
Provides a copy of the JSON tracked by the object.
Returns:
str
json
| @json.setter
| json(value: Union[dict, str]) -> None
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__
| __init__(data: Union[dict, str, None] = None, profile: Union[CXDataProfile, None] = None) -> None
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__
| __copy__() -> "CXJSONData"
copy constructor that returns a copy of the CXDictData objct.
Returns:
CXDictData A copy of the wrapping object.
__deepcopy__
| __deepcopy__(memo) -> "CXJSONData"
deepcopy constructor that returns a copy of the CXJSONData object.
Returns:
CXJSONData A copy of the wrapping object and deepcopy of
__repr__
| __repr__() -> str
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
CXTextData Objects
class CXTextData(CXData)
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
| text() -> str
Returns the raw text form of the data.
Returns:
str
text
| @text.setter
| text(value: str) -> None
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
| data() -> dict
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
| get_raw_dict_form() -> dict
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
| render_to_dict(**kwargs) -> dict
Converts the object into a dict representation.
Returns:
dict
__init__
| __init__(data: Union[object, None] = None) -> None
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
CXData Objects
class CXData(CXDictConvertable)
CXData defines an essential data class for managing data acquisiton,
transformation, and introspection as required by the CanvasXPress class.
data
| @property
| @abstractmethod
| data() -> dict
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
| get_raw_dict_form() -> dict
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
| __init__(data: Union[object, None]) -> None
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)
CXDataProfileException is used by CXDataProfile to describe validation errors when considering CXData objects in the context of CXDataProfile objects.
CXDataProfile Objects
class CXDataProfile(ABC)
CXDataProfile assists with CXData translations into CanvasXpress JSON data formats, such as documented at CanvasXpress.org.
render_to_profiled_dict
| @abstractmethod
| render_to_profiled_dict(data: CXData, **kwargs) -> dict
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)
CXData defines an essential data class for managing data acquisiton,
transformation, and introspection as required by the CanvasXPress class.
profile
| @property
| profile() -> Union[None, CXDataProfile]
Provides the CXDataProfile associated with the CXData instance.
Returns:
Union[None, CXDataProfile]
profile
| @profile.setter
| profile(profile: Union[None, CXDataProfile]) -> None
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
| data() -> dict
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__
| __init__(data: Union[object, None], profile: Union[CXDataProfile, None] = None) -> None
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)
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)
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
CanvasXpress Objects
class CanvasXpress(CXHtmlConvertable)
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"]
)
anonymous
| @property
| anonymous() -> bool
Indicates whether the object is anonymous. If True, then render_to() will result in a one-time random
ID string being returned for use in contexts such as rapidly changing React environments. If False, then
the ID string returned is the one set for the object by the developer.
Returns:
bool True if the object is anonymous; otherwise False.
render_to
| @property
| render_to() -> Union[str, None]
The ID of the CanvasXpress object's associated HTML components, such as
the create_element canvas element. Sets the id attribute of the <canvas>
element.
Returns:
str The ID, if configured; None if anonymous.
render_to
| @render_to.setter
| render_to(value: Union[str, None]) -> None
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. `None` can also be provided to
indicate that this object should be anonymous, such as for use
in rapidly changing React interfaces.
value:
license_available
| @property
| license_available() -> bool
Indicates if a license is associated with the CanvasXpress object.
Returns:
True if a license file URL has been set.
license_url
| @property
| license_url() -> str
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
| license_url(value: str) -> None
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:
cdn_edition
| @classmethod
| cdn_edition(cls) -> Union[str, None]
Indicates the version of CanvasXpress being used.
Returns:
Union[str, None]: The Javascript CDN version used or None if the latest.
set_cdn_edition
| @classmethod
| set_cdn_edition(cls, value) -> None
Sets the version of the Javascript CDN to use when generating HTML or React components. See thr CDN page for CanvasXpress to identify the versions available: https://cdnjs.com/libraries/canvasXpress.
Arguments:
`Union[str, None]` The CDN version, such as `38.1`, or None if the latest version is preferred.
value:
CHART_WIDTH_DEFAULT
Default width of the chart when rendered, such as into HTML.
width
| @property
| width() -> int
Indicates the preferred
Returns:
int The width
width
| @width.setter
| width(value: int)
Sets the preferred Web element width when rendered. Added to the
<canvas> element, and also influences create_element containers for contexts
such as Jupyter Notebooks.
Arguments:
The pixel count. Cannot be `None` or less than `1`.
value:int
CHART_HEIGHT_DEFAULT
Default height of the chart in pixels when rendered, such as into HTML.
height
| @property
| height() -> int
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 create_element containers for contexts such as Jupyter Notebooks.
Returns:
int The pixel count
height
| @height.setter
| height(value: int)
Sets the preferred Web element height when rendered. Added to the
<canvas> element, and also influences create_element containers for contexts
such as Jupyter Notebooks.
Arguments:
value:int
data
| @property
| data() -> CXData
Provides access to the CXData associated with this CanvasXpress chart.
Returns:
CXData The data to be associated with the chart.
data
| @data.setter
| data(value: Union[CXData, dict, DataFrame, str, None]) -> None
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
| events() -> CXEvents
Provides access to the CXEvents associated with this CanvasXpress chart.
Returns:
CXEvents The events to be associated with the chart.
events
| @events.setter
| events(events: Union[CXEvents, List[CXEvent], None]) -> None
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
| config() -> CXConfigs
Provides access to the CXConfigs associated with this CanvasXpress chart.
Returns:
CXConfigs The config to be associated with the chart.
config
| @config.setter
| config(value: Union[List[CXConfig], List[tuple], List[list], dict, CXConfigs])
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
| after_render() -> CXConfigs
Provides access to the CXConfigs associated with this CanvasXpress chart's afterRender property.
Returns:
CXConfigs
after_render
| @after_render.setter
| after_render(value: Union[List[CXConfig], List[tuple], List[list], dict, CXConfigs])
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,
other_init_params
| @property
| other_init_params() -> CXConfigs
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
| other_init_params(value: Union[List[CXConfig], List[tuple], List[list], dict, CXConfigs])
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: UseCanvasXpress.render_todata: UseCanvasXpress.dataconfig: UseCanvasXpress.configafterRender: UseCanvasXpress.after_renderwidth: UseCanvasXpress.widthheight: UseCanvasXpress.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
| from_reproducible_json(cls, cx_json: str, include_factory: bool = False, include_system: bool = False) -> "CanvasXpress"
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:strinclude_factory:boolinclude_system:bool
Returns:
CanvasXpress
__init__
| __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, width: int = CHART_WIDTH_DEFAULT, height: int = CHART_HEIGHT_DEFAULT) -> None
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: Seerender_toproperty, except that on defaultdata: See thedatapropertyevents: See theeventspropertyconfig: See theconfigpropertyafter_render: See theafter_renderpropertyother_init_params: See the 'other_init_params` propertywidth: See thewidthpropertyheight: See theheightproperty
update_data_profile
| update_data_profile(data: CXData, fix_missing_profile: bool, match_profile_to_graphtype: bool)
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:CXDatafix_missing_profile:boolmatch_profile_to_graphtype:bool
prepare_html_element_parts
| prepare_html_element_parts(fix_missing_profile: bool = True, match_profile_to_graphtype: bool = True) -> dict
Converts the CanvasXpress object into CanvasXpress element components in anticipation of further use in renderable objects or conversion into HTML.
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.
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:boolmatch_profile_to_graphtype:bool
Returns:
dict A map of values in anticipation of further conversion
render_to_html_parts
| render_to_html_parts(fix_missing_profile: bool = True, match_profile_to_graphtype: bool = True) -> dict
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:boolmatch_profile_to_graphtype:bool
__str__
| __str__() -> str
str function. Converts the CanvasXpress object into a JSON
representation.
:returns" str
JSON form of the CanvasXpress object.
__repr__
| __repr__() -> str
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.
