# encoding: latin2
"""Max-P-regions
"""
__author__ = "Juan C. Duque"
__credits__ = "Copyright (c) 2009-11 Juan C. Duque"
__license__ = "New BSD License"
__version__ = "1.0.0"
__maintainer__ = "RiSE Group"
__email__ = "contacto@rise-group.org"

import copy
import numpy
import time as tm
from componentsAlg import AreaManager
from componentsAlg import BasicMemory
from componentsAlg import RegionMaker

__all__ = ['execMaxpTabu']

def execMaxpTabu(y, w, threshold=100.0, maxit=2, tabuLength=5, typeTabu="exact"):
    """Max-p-regions model (Tabu) 

    The max-p-regions model, devised by [Duque_Anselin_Rey2010]_ ,
    clusters a set of geographic areas into the maximum number of homogeneous
    regions such that the value of a spatially extensive regional attribute is
    above a predefined threshold value. In clusterPy we measure heterogeneity as
    the within-cluster sum of squares from each area to the attribute centroid
    of its cluster.

    The max-p-regions algorithm is composed of two main blocks: 
    
    - construction of a initial feasible solution. 
    - local improvement.
    
    There are three methods for local improvement: Greedy (execMaxpGreedy),
    Tabu (execMaxpTabu), and Simulated Annealing (execMaxpSa). A detailed
    explanation of each method can be found in Duque, Anselin and Rey (2010) [Duque_Anselin_Rey2010]_.

    For this version, the tabu search algorithm will stop after
    max(10,N/maxP) nonimproving moves. ::

        layer.cluster('maxpTabu',vars,<threshold>,<wType>,<std>,<maxit>,<tabuLength>,<typeTabu>,<dissolve>,<dataOperations>)

    :keyword vars: Area attribute(s). Important: the last variable in vars correspond to the spatially extensive attribute that will be constrained to be above the predefined threshold value (e.g. ['SAR1','SAR2','POP'])  
    :type vars: list
    :keyword threshold: Minimum value of the constrained variable at regional level. Default value threshold = 100.
    :type threshold: integer
    :keyword wType: Type of first-order contiguity-based spatial matrix: 'rook' or 'queen'. Default value wType = 'rook'. 
    :type wType: string
    :keyword std: If = 1, then the variables will be standardized.
    :type std: binary
    :keyword maxit: Number of times that the construction phase is repeated. The larger the value the higher the possibility of getting a large number of regions. Default value maxit = 2.
    :type maxit: integer
    :keyword tabuLength: Number of times a reverse move is prohibited. Default value tabuLength = 85. 
    :type tabuLength: integer
    :keyword typeTabu: Type of tabu search: (a) exact: chooses the best neighbouring solution for evaluation (it implies the enumeration of all the neighbouring solution at each iteration); (b) "random": evaluates a neighbouring solution selected at random and (See Ricca, F.  and Simeone (2008) for more on the difference between exact and random tabu). Default value typeTabu = "exact". 
    :type typeTabu: string 
    :keyword dissolve: If = 1, then you will get a "child" instance of the layer that contains the new regions. Default value = 0. Note: Each child layer is saved in the attribute layer.results. The first algorithm that you run with dissolve=1 will have a child layer in layer.results[0]; the second algorithm that you run with dissolve=1 will be in layer.results[1], and so on. You can export a child as a shapefile with layer.result[<1,2,3..>].exportArcData('filename')
    :type dissolve: binary
    :keyword dataOperations: Dictionary which maps a variable to a list of operations to run on it. The dissolved layer will contains in it's data all the variables specified in this dictionary. Be sure to check the input layer's fieldNames before use this utility.
    :type dataOperations: dictionary

    The dictionary structure must be as showed bellow.

    >>> X = {}
    >>> X[variableName1] = [function1, function2,....]
    >>> X[variableName2] = [function1, function2,....]

    Where functions are strings which represents the name of the
    functions to be used on the given variableName. Functions
    could be,'sum','mean','min','max','meanDesv','stdDesv','med',
    'mode','range','first','last','numberOfAreas. By deffault just
    ID variable is added to the dissolved map.
    """
    print "Running max-p-regions model (Duque, Anselin and Rey, 2010)"
    print "Local search method: Tabu Search"
    print "Number of areas: ", len(y)