iota.graph

Description

This module provides functionalities to generate, edit, display and export graphs.

Generating graphs

• plot_xy

• plot_histogram

Accessing, adding and deleting data from the graph

• Graph

  • get_data

  • set_data

  • delete_data

  • add_data

  • add_histogram

  • add_trace

Displaying and exporting graphs

• Graph

  • display

  • export_html

  • export_csv

Getting and setting graph layout

• Graph

  • get_layout
  • set_layout

iota.graph.plot_xy(x, y, name, title, x_label, y_label, layout)

Generate a graph with a scatter plot of trace given its x and y values

Parameters

• x : (list of floats or numpy.ndarray of floats) x-values of the trace

• y : (list of floats or numpy.ndarray of floats) y-values of the trace

• name: (str) name for the trace

• title : (str) title of the graph (default: None)

• x_label : (str) title for the x-axis (Default: None)

• y_label : (str) title for the y-axis (Default: None)

• layout: (plotly.go_objs.Layout) a plotly layout object with the settings for the layout of the graph (Default: None)

Output

• A Graph object that contains a collection of data represented as a trace

Example

Generating graph with a scatter 2D plot called 'Maximum Pressure' and given the array of x values and the array of y values

x_values = numpy.array([0.5,1.5,2.5,3.5])
y_values = numpy.array([10.2,11.2,12.2,13.2])
my_graph = iota.graph.plot_xy( name='Maximum Pressure', x=x_values, y=y_values, x_label='time (s)', y_label='Pressure (KPa)')
my_graph.display()

iota.graph.plot_histogram(name, values, nbins, sizebins, normalize, title, x_label, y_label, layout)

Generate a graph with a scatter plot of trace given its x and y values

Parameters

• name : (str) name for the histogram

• values : (list of floats or numpy.ndarray of floats) list of values to build the histogram

• nbins : (int) maximum number of bins for the histogram (ignored if sizebins is provided)

• sizebins: (float) size for the bins of the histogram

• normalize: (str) method to normalize the values of the height of the bins (Default: '')

  • '': number of occurrences

  • 'percent': percentage of occurrences with respect to the total number of values in value (sum of the height of all bins is equal to 100%)

  • 'probability': fraction of occurrences with respect to the total number of values in value (sum of the height of all bins is equal to 1)

  • 'density': number of occurrences in a bin is divided by the of the bin (sum of all bin areas is equal to total number of values in value)

  • 'probability density': the area of each bin corresponds to the probability that an event falls within the corresponding bin (sum of all bin areas is equal to 1)

• title : (str) title for graph (Default: None)

• x_label : (str) title for the x-axis (Default: None)

• y_label : (str) title for the y-axis (Default: None)

• layout: (plotly.go_objs.Layout) a plotly layout object with the settings for the layout of the graph (Default: None)

Output

• A Graph object that contains a collection of data represented as a histogram

Examples

Generating a new graph with a histogram called 'Pressure' given an array with the values and a maximum number of bins equal to 4

values = numpy.asarray([0.5,1.15,1.25,0.8,0.5,0.6])
my_graph = iota.graph.plot_histogram(name='Pressure', values=values, nbins=4, title='Pressure Histogram', x_label='Pressure (kPa)', y_label='Number of nodes')
my_graph.display()

Generating a new graph with a histogram called 'Pressure' given an array with the values, a bin size equal to 0.5 and normalizing the height of the bin based on percentage

values = numpy.asarray([0.5,1.15,1.25,0.8,0.5,0.6])
my_graph = iota.graph.plot_histogram(name='Pressure', values=values, sizebins=0.5, normalize='percent', title='Pressure Histogram', x_label='Pressure (kPa)', y_label='Number of nodes')
my_graph.display()

class Graph

iota.graph.Graph()

Graph class object. This object is returned when generating a plot using one of the plot methods in the iota.graph (see for example iota.graph.plot_xy or iota.graph.plot_histogram)

Methods

Graph.add_data(data)

Add a plotly.go_objs.Data object to the graph. The Data objects contains a list of data collections objects.

Parameters

• name : name of the data

• data : (plotly.go_objs.Data) Data object containing a list of data collections

Example

Adding a Data object that contains a list of two traces

import plotly as plt
trace1 =  plt.graph_objs.Scatter(x=[8,9,10], y=[11,12,13], name='trace 1')
trace2 =  plt.graph_objs.Scatter(x=[8,9,10], y=[14,15,16], name='trace 2')
Data = plt.graph_objs.Data([trace1, trace2]) 
my_graph = iota.graph.Graph()
my_graph.add_data("traces", Data)

Graph.add_histogram(name, values, nbins, sizebins, normalize)

Add a new data collection as a histogram to the graph

Parameters

• name : (str) name for the histogram

• values : (list of floats or numpy.ndarray of floats) list of values to build the histogram

• nbins : (int) maximum number of bins for the histogram (ignored if sizebins is provided)

• sizebins: (float) size for the bins of the histogram

• normalize: (str) method to normalize the values of the height of the bins (Default: '')

  • '': number of occurrences

  • 'percent': percentage of occurrences with respect to the total number of values in value (sum of the height of all bins is equal to 100%)

  • 'probability': fraction of occurrences with respect to the total number of values in value (sum of the height of all bins is equal to 1)

  • 'density': number of occurrences in a bin is divided by the of the bin (sum of all bin areas is equal to total number of values in value)

  • 'probability density': the area of each bin corresponds to the probability that an event falls within the corresponding bin (sum of all bin areas is equal to 1)

Examples

Adding a new histogram called 'histogram 1' with maximum number of bins equal to 4

my_graph.add_histogram(name='histogram 1', values=[0.5,1.15,1.25,0.8,0.5,0.6], nbins=4)

Adding a new histogram called 'histogram 1' with bin size equal to 0.5 and normalizing the height of the bin based on percentage

my_graph.add_histogram(name='histogram 1', values=[0.1,1.15,1.25,0.8,0.2,0.6], sizebins=0.5, normalize='percent')

Graph.add_trace(name, x, y)

Add a new data collection as a trace (scatter) to the graph

Parameters

• name : (str) name of the trace

• x : (list of floats or numpy.ndarray of floats) x-values of the trace

• y : (list of floats or numpy.ndarray of floats) y-values of the trace

Examples

Adding a new trace to an existing graph given the x and y values as a list of floats

my_graph.add_trace(name='my new trace', x=[0.5,1.5,2.5,3.5], y=[10.2,11.2,12.2,13.2])

Adding a new trace to an existing graph given the x and y values as numpy array of floats

x_values = numpy.array([0.5,1.5,2.5,3.5])
y_values = numpy.array([10.2,11.2,12.2,13.2])
my_graph.add_trace(name='my new trace', x=x_values, y=y_values)

Graph.display(width, height)

Display the graph in the working notebook

Parameters

• width : (int) width for the display of the graph in pixels (Default: 800)

• height : (int) height for the display of the graph in pixels (Default: 600)

Examples

Displaying the graph with the default height and width

my_graph.display()

Displaying the graph and setting its width to 1000 pixels and height to 800 pixels

my_graph.display(width=1000, height=800)

Graph.delete_data(name)

Delete an existing collection of data (e.g. a trace data or a histogram data) from the graph given the name of the data collection

Parameters

• name : (str) name of the collection of data to be deleted from the graph

Example

Deleting the existing trace called 'my new trace' from the graph

my_graph.delte_data(name='my new trace')

Graph.export_csv(file)

Export the data values of the traces and histograms in the graph to csv file

Parameters

• file : (str) path for the csv file

Example

Exporting the data values of a graph to a csv file called 'my_graph_data.csv'

my_graph.export_csv(file='C:/Users/Stephen/MyGraphs/my_graph_data.csv')

Graph.export_html(file, auto_open, width, height)

Export the graph to html file

Parameters

• sfile : (str) path for the csv file

• auto_open : (bool) If True, the exported html file is automatically opened in your web browser (Default: False)

• width : (int) width for th graph in pixels (Default: 800)

• height : (int) height for the graph in pixels (Default: 600)

Examples

Exporting a graph to a html file called 'my_graph.html'

my_graph.export_html(file='C:/Users/Stephen/MyGraphs/my_graph.html')

Exporting the graph to a html file call 'my_graph.html' and setting its width to 1000 pixels and height to 800 pixels

my_graph.export_html(file='C:/Users/Stephen/MyGraphs/my_graph.html', width=1000, height=800)

Graph.get_data(name)

Get the plotly graph object that represents a data collection in the graph

Parameters

• name : (str) name of the data collection

Output

• A plotly graph object representing the data collection:

  • plotly.graph_objs.Scatter
  • plotly.graph_objs.Histogram
  • plotly.graph_objs.Surface

Example

Getting the plolty graph object of the existing trace called 'Trace 1' in the graph

my_graph.get_data(name='Trace 1')

Graph.set_data(name, data)

Set the a new plotly graph object to an existing data collection in the graph

Parameters

• name : (str) name of the existing data collection

• data: (plotly.graph_objs) a plotly graph object with the new setting for the data collection:

  • plotly.graph_objs.Scatter
  • plotly.graph_objs.Histogram
  • plotly.graph_objs.Surface

Examples

Creating a new graph with a trace called 'Trace 1' ands setting afterwards the x-values of the trace to a new list of values

my_graph = iota.graph.Graph()
my_graph.add_trace(name='Trace 1', x=[0.5,1.5,2.5,3.5], y=[10.2,11.2,12.2,13.2])
my_trace = my_graph.get_data(name='Trace 1')
my_trace['x'] = [1.5,2.5,3.5,4.5]
my_graph.set(name='Trace 1', data=my_trace)

Graph.get_layout()

Get a layout object that contains the settings of the layout of the graph

Output

• A plotly layout object that contains the settings of the layout

Example

Getting the layout settings of a graph

layout_settings = my_graph.get_layout()
print(layout_settings)

Graph.set_layout()

Set the settings of the layout of graph

Parameters

• title : (str) title for the graph (Default: None)

• x_label: (str) title for the x-axis (Default: None)

• y_label: (str) title for the y-axis (Default: None)

• x_range: (list of two floats): Min and Max values defining the range of the x-axis (Default: None)

• y_range: (list of two floats): Min and Max values defining the range of the y-axis (Default: None)

• width: (int) width of the graph in pixels (Default: None)

• height: (int) width of the graph in pixels (Default: None)

Example

Setting the title of the graph, x-axis and y-axis

my_graph.set_layout(title='My new graph', 
                    x_label='time (s)', 
                    y_label='Pressure (kPa)')

Setting the range of the x-axis and y-axis to [0, 100] and [50, 600] respectively

my_graph.set_layout(x_range=[0, 100], 
                    y_range=[50, 600])