Array methodsΒΆ

There are plenty of binary operations in staircase. These are ones which operate on two step functions to produce a result. There are occasions however where we want to perform an operation on several step functions. There is typically two cases that this arises:

  1. We want to perform separate operations on multiple step functions, with a common parameter. This could include sampling the collection of step functions with a common set of points, or plotting each step function in a collection to the same matplotlib.axes.Axes instance.

  2. We want to perform a single operation which acts upon a collection of step functions, such as creating an average step function, or calculating a co-variance matrix.

Currently the following array methods are defined in staircase:

Note that equivalent calculations using python built-in methods, or pandas.Series methods can sometimes be possible. For example:

In [1]: df = sc.make_test_data(groups=["a", "b", "c"])

In [2]: a = sc.Stairs(df.query("group == 'a'"), "start", "end");

In [3]: b = sc.Stairs(df.query("group == 'b'"), "start", "end");

In [4]: c = sc.Stairs(df.query("group == 'c'"), "start", "end");

In [5]: fig, axes = plt.subplots(ncols=3, figsize=(8,3), sharey=True, tight_layout=True);

In [6]: sum([a,b,c]).plot(axes[0]);

In [7]: axes[0].set_title("sum([a,b,c])");

In [8]: pd.Series([a,b,c]).sum().plot(axes[1]);

In [9]: axes[1].set_title("pd.Series([a,b,c]).sum()");

In [10]: sc.sum([a,b,c]).plot(axes[2]);

In [11]: axes[2].set_title("sc.sum([a,b,c])");

In the example above, the non-staircase methods work by leveraging the fact that the staircase.Stairs class has an add operation, which is applied iteratively. It should be not surprising that the corresponding function in staircase, which operates on the entire collection at once, is faster and more memory efficient. Also be aware that some methods, such as max([a,b,c]), may superficially appear to work since a staircase.Stairs instance is returned but the result is not what is expected.