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
:str
document_includes
:bool
document_render
:bool
document_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
:str
document_includes
:bool
document_render
:bool
document_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
:CanvasXpress
document_includes
:bool
document_render
:bool
document_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
:str
chart_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
:str
value
: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
: TheCXEvent
to 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
:str
script
: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
:CanvasXpress
The 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, or
None` 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
:str
source
:dict
target
: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
:CXData
match_vars_to_rows
:bool
match_smps_to_cols
:bool
match_x_to_smps
:bool
match_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
:str
detail_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_to
data
: UseCanvasXpress.data
config
: UseCanvasXpress.config
afterRender
: UseCanvasXpress.after_render
width
: UseCanvasXpress.width
height
: 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
:str
include_factory
:bool
include_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_to
property, except that on defaultdata
: See thedata
propertyevents
: See theevents
propertyconfig
: See theconfig
propertyafter_render
: See theafter_render
propertyother_init_params
: See the 'other_init_params` propertywidth
: See thewidth
propertyheight
: See theheight
property
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
:CXData
fix_missing_profile
:bool
match_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
:bool
match_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
:bool
match_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.