from abc import ABCMeta, abstractmethod

class Disaggregator(object):
    """Abstract Base Class for all Disaggregators.  This class
    defines the common interface to all Disaggregators.
    """

    __metaclass__ = ABCMeta

    @abstractmethod
    def train(self, mains=None, appliances=None):
        """Train the disaggregation algorithm.

        There are three training modes.  The mode will be selected based
        on which arguments are provided.  The modes are:

        * Supervised training on appliance data
        * Supervised training on mains data, using simultaneously recorded
          appliance data as the labels
        * Unsupervised training on mains data only

        The parameters are designed to accept the standard mains and 
        appliance data structure used in nilmtk's `Electricity` class.

        `train` can be called more than once during the lifetime of
        the object to train on new data.

        Some subclasses of Disaggregator will be trainable using more
        than training mode.  In this case, call `train` multiple times
        using different combinations of arguments.

        Parameters
        ----------
        mains : pandas.DataFrame or pandas.Series, optional
            Whole-house, aggregate power data in Watts.
            index is a DataTimeIndex
            column names use the nilmtk standard for mains data

        appliances : dict of list of DataFrames, optional
            Keys are appliance names, using nilmtk standards
            Values are lists of DataFrames, one DataFrame per appliance, using
            standard nilmtk names in columns for recorded parameters.

        """
        return

    @abstractmethod
    def disaggregate(self, building):
        """Runs non-intrusive load monitoring on the aggregate data from 
        the building.

        We pass in an entire Building object because some Disaggregators
        can take advantage of building metadata such a geo location to 
        improve the estimates.

        Parameters
        ----------
        building : Building

        Returns
        -------
        appliance_estimates: Panel, shape (n_samples, n_appliances, [1,3])
            Returns a 3D matrix (Panel). The third dimension represents 
            some combination of:
            * estimated power
            * estimated state
            * confidence [0,1]
        """
        return

@@ -260,20 +260,24 @@
 n(self, 
-ma
+build
 in
+g
 s=None, 
@@ -291,16 +291,54 @@
 ces=None
+, %0A              external_sensors=None
 ):%0A     
@@ -422,98 +422,8 @@
 odes
-.  The mode will be selected based%0A        on which arguments are provided.  The modes are
 :%0A%0A 
@@ -647,442 +647,338 @@
     
-The parameters are designed to accept the standard mains and %0A        appliance data structure used in nilmtk's %60Electricity%60 class.%0A%0A        %60train%60 can be called more than once during the lifetime of%0A        the object to train on new data.%0A%0A        Some subclasses of Disaggregator will be trainable using more%0A        than training mode.  In this case, call %60train%60 multiple times%0A        using different combinations of arguments
+Some subclasses of Disaggregator will be trainable using more%0A        than training mode.  In this case, %60train%60 will attempt to use%0A        all training modes available, in order to produce the best models.%0A%0A        %60train%60 can be called more than once during the lifetime of%0A        the disaggregator object to train on new data
 .%0A%0A 
@@ -1026,216 +1026,241 @@
     
-ma
+build
 in
+g
 s : 
-pandas.DataFrame or pandas.Series, optional%0A            Whole-house, aggregate power data in Watts.%0A            index is a DataTimeIndex%0A            column names use the nilmtk standard for mains
+a list of nilmtk Building objects, optional%0A            These objects must contain aggregate whole-house data and can %0A            optionally contain simultaneously recorded appliance data and/or%0A            ambient
  data
+.
 %0A%0A  
@@ -1282,253 +1282,434 @@
 s : 
-dict of list of DataFrames, optional%0A            Keys are appliance names, using nilmtk standards%0A            Values are lists of DataFrames, one DataFrame per appliance, using%0A            standard nilmtk names in columns for recorded parameters
+nilmtk Electricity object, optional%0A            Use this for training the disaggrgator using appliance data recorded%0A            without simultaneous aggregate data, for example from tracebase.%0A            The %60appliances%60 attribute in the %60Electricity%60 object must be %0A            populated.%0A%0A        external_sensors :%0A            External sensor data, e.g. weather data from the local %0A            metoffice weather station
 .%0A%0A 
@@ -2437,16 +2437,126 @@
 ce %5B0,1%5D
+%0A%0A        %60disaggregate%60 also sets the %60appliance_estimates%60 attribute of%0A        %60building.utility.electric%60.
 %0A       

allow users to train on Buildings. #36