This packages deploys contextually supervised source separation (CSSS) techniques in python. CSSS was originally described by Wytock and Kolter in P1 and we follow their original notation in this documentation. We also include updates and extensions of the original CSSS method as part of our applied work (P2,P3).
CSSS is the disaggregation of a time series of source signals from observations of their sum. For more detailed information on the methodology and the relevant equations see the ipython notebooks.
The CSSS package is built upon the CSSS object class, which allows users to fully specify and fit a problem.
A CSSS object is initialized with only a source signal for disaggregation, in this case the numpy array, Y.
import CSSSpy
CSSSobject = CSSSpy.CSSS(Y)
models
is a dictionary of models for each component sources. Adding sources and their properties are addressed below.constraints
is a list of additional constraints. Adding constraints is addressed below.aggregateSignal
is the aggregate signalN
is the number of observations in the aggregate signal.modelcounter
is the total number of source models included.The method CSSS.addSource adds a model for a source signal. By default, the model cost function is the sum of square errors, $\left|\left| y_i - X_i \theta_i \right|\right|2^2$, and there is no regularization of the source signal or the parameters. Alternate options for this form (i.e. other norms) will be included in future versions of this package.
CSSSobject.addSource(X1, name = 'y1') ## Add a model for source signal y1
CSSSobject.addSource(X2, name = 'y2') ## Add a model for source signal y2
The optional parameter alpha
is a scalar that weights the cost of the signal in the objective function. In the following example, costs associated with the errors in the model for y1
will be weighted twice that of those for y2
.
The regularizeTheta
input to addSource
defines the $h_i()$ term for the source and takes either a string or a function. Strings define standard regularizations and can take "ss" for sum of squares, 'l1' for l1-norms, and 'l2' for l2-norms. beta
is a parameter for linearly scaling the regularization term in the overall objective function. beta
may take a scalar or a vector value, if a vector there must be one element for element of $theta_i$.
CSSSobject.addSource(X1, name = 'y1', regularizeTheta='L2', beta = 2) ## Add a model for source signal y1
If inputing a custom function to regularize theta, the function must input a vector of cvxpy variables, and output a scalar that goes into the objective function, and must be convex. The beta
term can still be used to scale this function.
import cvxpy
def customReg(x):
cvxpy.sum_entries(cvxpy.power((x-2),2))
CSSSobject.addSource(X1, name = 'y1', regularizeTheta=customReg) ## Add a model for source signal y1
The regularizeSource
input to addSource
defines the $g_i()$ term for the source and takes either a string or a function. Strings define standard regularizations and currently only take "diff1_ss" for sum of the squared differenced source signal. gamma
is a parameter for linearly scaling the regularization term in the overall objective function.
CSSSobject.addSource(X1, name = 'y1', regularizeSource='diff1_ss', beta = .1) ## Add a model for source signal y1
If inputing a custom function to regularize the source, the function must input a vector of cvxpy variables and output a scalar that goes into the objective function, and must be convex. The gamma
term can still be used to scale this function.
import cvxpy
def customReg(x):
## Custom regularization function for a source signal with a biased increase
cvxpy.norm(cvxpy.Diff(x)-.01,1)
CSSSobject.addSource(X1, name = 'y1', regularizeSource=customReg) ## Add a model for source signal y1
The model
attribute of the CSSS
object, includes the following fields:
name
: Name of the model, can be set, or defaults to the source count
source
: The disaggregated source
alpha
: Scaling parameter for the $\ell_i()$ function to weight the cost function of residuals.
lb
: Signifies a lower bound for a box constraint on the source. Default is None
ub
: Signifies an upper bound for a box constraint on the source. Default is None
theta
: Model parameters for the individual source, constructed by addSource
costFunction
: Model cost function as inputted to addSource
. Currently supports sse
, l2
and l1
TODO. Inlcude all attributes of a source, how to acceess the cvxpy variables to add constraints etc.