Skip to content

Latest commit

 

History

History
146 lines (105 loc) · 5.02 KB

reference.md

File metadata and controls

146 lines (105 loc) · 5.02 KB
Raw

Croquis API

Since it's currently very simple, there's not much to document. Every graph is created by running the following commands:

# Create the figure object.
fig = croquis.plot(...)

# Add one or more data sets.
fig.add(x1, y1, ...)
fig.add(x2, y2, ...)

# Generate the figure.
fig.show()

croquis.plot()

This function currently has only two optional arguments:

  • x_axis='linear' (default) interprets the x axis as ordinary numbers.
  • x_axis='timestamp' interprets it as POSIX timestamps. Timestamps are interpreted as UTC but displayed using the local timezone.
  • y_axis behaves similarly.

fig.add(X, Y, colors=None, **kwargs)

Each call may add a set of lines - scatter plots can be generated by adding "lines" with a single point each, or by setting line_width to zero. You can call this function as many times as you want, but for best performance, it's better to batch multiple lines into a single call to fig.add().

  • X, Y: Data points.

    Can be a Numpy array or something that can be transformed into a Numpy array. Data types can be any of: 8/16/32/64-bit signed/unsigned integer, float (i.e., numpy.float32), double (i.e., numpy.float64), or np.datetime64 (which is converted to POSIX timestamps - specify x_axis='linear' to view them as time).

    If dimension is N or (1, N) (for some N), then it is considered N points of a single line. If dimension is (M, N) then it is considered M different lines, each with N data points.

    Broadcasting is supported, that is, one of X or Y can have dimension N or (1, N) and the other can have dimension (M, N) (where M > 1).

For example, the following are supported combinations.

fig.add([1, 2, 3], [4, 5, 6])  # Adds a single line with three points.

X = np.linespace(0, 10, 0.1)
fig.add(X, np.sin(X))  # Adds a single line.

X = np.array([[1, 2, 3, 4, 5], [2, 4, 6, 8, 10])
fig.add(X, np.sin(X))  # Adds two lines, each with five points.

# Broadcasting: adds 100 lines, each with 200 points.
# All lines share the same 200 x-coordinates.
X = np.linspace(0, 2 * np.pi, 200)
freqs = np.linspace(0, 1, 100).reshape(100, 1)
Y = np.sin(freqs * X)  # matrix of size 100 x 200
fig.add(X, Y)

  • colors (optional)

    If specified, must have dimension (M, 3), where M is the number of lines. Can be either integer (range [0, 255]), or float (range [0.0, 1.0]).

    Currently, markers (if present) must have the same color as lines.

  • marker_size, line_width, highlight_line_width (optional)

    Specifies the size of the marker, line width, and line width when a line is highlighted (by hovering). Note that only circles are supported so far.

  • copy_data (optional: default is True)

    If False, then croquis does not copy the arguments and instead holds a reference to the data. Can reduce memory usage for huge data, but if the underlying data is modified while the graph is being used, bad things may happen.

  • start_idxs (optional)

    Used for adding a batch of lines with an irregular number of points. If specified, changes how we interpret X and Y: X and Y must be 1-D arrays with the same length, and start_idxs must be a monotonically increasing integer array indicating where each line starts. For example:

# Contains three lines, with 3, 5, and 4 points each.
X =        [0, 1, 2, 0, 1, 2, 3, 4, 0, 1, 2, 3]
Y =        [1, 1, 1, 2, 2, 2, 2, 2, 3, 3, 3, 3]
#           |        |              |
# line #0:  0  1  2  |              |
#      #1:           3  4  5  6  7  |
#      #2:                          8  9 10 11
start_idxs = [0, 3, 8]

fig.add(X, Y, start_idxs=start_idxs)

  • groupby (optional)

    (Not included in 0.1.0 release.)

    An alternative for start_idxs: when given, X, Y, and groupby must be 1-D arrays with the same size. The elements of groupby can be of any type, including string. Each line is made of points that share the same value of groupby - lines are arranged in the order of the first occurrence of the point.

    In addition, if label/labels are not given, the values of groupby are also used as labels.

    For example:

# Contains four lines, appearing in this order:
#   'ICN' (3 points)
#   'SFO' (1 point)
#   'GMP' (2 points)
#   'RDU' (3 points)
X       = [    0,     1,     2,     3,     4,     5,     6,     7,     8]
Y       = [   10,    11,    20,    12,    30,    40,    41,    31,    42]
airport = ['ICN', 'ICN', 'SFO', 'ICN', 'GMP', 'RDU', 'RDU', 'GMP', 'RDU']

fig.add(X, Y, groupby=airport, marker_size=10)

NOTE: groupby internally works by calling numpy.unique() and re-arranging the data, so it is less efficient than calling start_idxs.

  • labels (optional)

    If given, specifies the name of each line. Must be a list of strings (or something convertible to that) and have the same number of strings as lines.

  • label (optional)

    Shorthand for the case when there's only one line: must be a string. (Obviously, cannot be used together with labels.)