def vector_by_step(vstart,vstop,vstep):

    """
    @summary: generates a list by using start, stop, and step values

    @param vstart: Initial value 
    @type vstart: A number
    @param vstop: Max value
    @type vstop: A number
    @param vstep: Step
    @type vstep: A number
   
    @return: A list generated
    @rtype: ListType

    @author: Vladimir Likic
    """

    if not is_number(vstart) or not is_number(vstop) or not is_number(vstep):
        error("parameters start, stop, step must be numbers")

    v = []

    p = vstart 
    while p < vstop:
        v.append(p)
        p = p + vstep

    return v

def median(v):

    """
    @summary: Returns a median of a list or numpy array

    @param v: Input list or array
    @type v: ListType or numpy.core.ndarray
    @return: The median of the input list
    @rtype: FloatType

    @author: Vladimir Likic
    """

    if not is_list(v):
        error("argument neither list nor array")

    local_data = copy.deepcopy(v)
    local_data.sort()
    N = len(local_data)

    if (N % 2) == 0:
        # even number of points
        K = N/2 - 1 
        median = (local_data[K] + local_data[K+1])/2.0
    else:
	    # odd number of points
        K = (N - 1)/2 - 1
        median = local_data[K+1]

    return median

def rmsd(list1, list2):

    """
    @summary: Calculates RMSD for the 2 lists

    @param list1: First data set
    @type list1: ListType, TupleType, or numpy.core.ndarray 
    @param list2: Second data set
    @type list2: ListType, TupleType, or numpy.core.ndarray 
    @return: RMSD value
    @rtype: FloatType

    @author: Qiao Wang
    @author: Andrew Isaac
    @author: Vladimir Likic
    """

    if not is_list(list1):
        error("argument neither list nor array")

    if not is_list(list2):
        error("argument neither list nor array")

    sum = 0.0
    for i in range(len(list1)):
        sum = sum + (list1[i] - list2[i]) ** 2
    rmsd = math.sqrt(sum / len(list1))
    return rmsd

def std(v):

    """
    @summary: Calculates standard deviation

    @param v: A list or array
    @type v: ListType, TupleType, or numpy.core.ndarray

    @return: Mean
    @rtype: FloatType

    @author: Vladimir Likic
    """

    if not is_list(v):
        error("argument neither list nor array")

    v_mean = mean(v)

    s = 0.0 
    for e in v:
        d = e - v_mean
        s = s + d*d
    s_mean = s/float(len(v)-1)
    v_std = math.sqrt(s_mean)

    return v_std

def MAD(v):

    """
    @summary: median absolute deviation

    @param v: A list or array
    @type v: ListType, TupleType, or numpy.core.ndarray

    @return: median absolute deviation
    @rtype: FloatType

    @author: Vladimir Likic
    """

    if not is_list(v):
        error("argument neither list nor array")

    m = median(v)
    m_list = []

    for xi in v:
        d = math.fabs(xi - m)
        m_list.append(d)

    mad = median(m_list)/0.6745

    return mad

    def write(self, file_name, minutes=False):

        """
        @summary: Writes the ion chromatogram to the specified file

        @param file_name: Output file name
        @type file_name: StringType
        @param minutes: A boolean value indicating whether to write
            time in minutes
        @type minutes: BooleanType

        @return: none
        @rtype: NoneType

        @author: Lewis Lee
        @author: Vladimir Likic
        """

        if not is_str(file_name):
            error("'file_name' must be a string")

        fp = open_for_writing(file_name)

        time_list = copy.deepcopy(self.__time_list)

        if minutes:
            for ii in range(len(time_list)):
                time_list[ii] = time_list[ii]/60.0

        for ii in range(len(time_list)):
            fp.write("%8.4f %#.6e\n" % (time_list[ii], self.__ia[ii]))

        close_for_writing(fp)

def exprl2alignment(exprl):

    """
    @summary: Converts experiments into alignments

    @param exprl: The list of experiments to be converted into an alignment
        objects
    @type exprl: ListType

    @author: Vladimir Likic
    """

    if not is_list(exprl):
        error("the argument is not a list")

    algts = []

    for item in exprl:
        if not isinstance(item, Experiment):
            error("list items must be 'Experiment' instances")
        else:
            algt = Class.Alignment(item)
        algts.append(algt)

    return algts

def load_expr(file_name):

    """
    @summary: Loads an experiment saved with 'store_expr'

    @param file_name: Experiment file name
    @type file_name: StringType

    @return: The experiment intensity matrix and peak list
    @rtype: pyms.Experiment.Class.Experiment

    @author: Vladimir Likic
    @author: Andrew Isaac
    """

    if not is_str(file_name):
        error("'file_name' not a string")

    fp = open(file_name,'rb')
    expr = cPickle.load(fp)
    fp.close()

    if not isinstance(expr, Experiment):
        error("'file_name' is not an Experiment object")

    return expr

    def __init__(self, mass_list, intensity_list):

        """
        @summary: Initialize the Scan data

        @param mass_list: mass values
        @type mass_list: ListType

        @param intensity_list: intensity values
        @type intensity_list: ListType

        @author: Qiao Wang
        @author: Andrew Isaac
        @author: Vladimir Likic
        """

        if not is_list(mass_list) or not is_number(mass_list[0]):
            error("'mass_list' must be a list of numbers")
        if not is_list(intensity_list) or \
           not is_number(intensity_list[0]):
            error("'intensity_list' must be a list of numbers")

        self.__mass_list = mass_list
        self.__intensity_list = intensity_list
        self.__min_mass = min(mass_list)
        self.__max_mass = max(mass_list)

    def get_ic_at_mass(self, mass = None):

        """
        @summary: Returns the ion chromatogram for the specified mass.
            The nearest binned mass to mass is used.

            If no mass value is given, the function returns the total
            ion chromatogram.

        @param mass: Mass value of an ion chromatogram
        @type mass: IntType

        @return: Ion chromatogram for given mass
        @rtype: IonChromatogram

        @author: Andrew Isaac
        @author: Vladimir Likic
        """

        if mass == None:
            return self.get_tic()

        if mass < self.__min_mass or mass > self.__max_mass:
            print "min mass: ", self.__min_mass, "max mass:", self.__max_mass
            error("mass is out of range")

        ix = self.get_index_of_mass(mass)

        return self.get_ic_at_index(ix)

    def write_intensities_stream(self, file_name):

        """
        @summary: Writes all intensities to a file

        @param file_name: Output file name
        @type file_name: StringType

        This function loop over all scans, and for each scan
        writes intensities to the file, one intenisity per
        line. Intensities from different scans are joined
        without any delimiters.

        @author: Vladimir Likic
        """

        if not is_str(file_name):
            error("'file_name' must be a string")

        N = len(self.__scan_list)

        print" -> Writing scans to a file"

        fp = open_for_writing(file_name)

        for ii in range(len(self.__scan_list)):
            scan = self.__scan_list[ii]
            intensities = scan.get_intensity_list()
            for I in intensities:
                fp.write("%8.4f\n" % ( I ) )

        close_for_writing(fp)

    def __set_time(self, time_list):

        """
        @summary: Sets time-related properties of the data

        @param time_list: List of retention times
        @type time_list: ListType

        @author: Vladimir Likic
        """

        # calculate the time step, its spreak, and along the way
        # check that retention times are increasing
        time_diff_list = []

        for ii in range(len(time_list)-1):
            t1 = time_list[ii]
            t2 = time_list[ii+1]
            if not t2 > t1:
                error("problem with retention times detected")
            time_diff = t2 - t1
            time_diff_list.append(time_diff)

        time_step = mean(time_diff_list)
        time_step_std = std(time_diff_list)

        self.__time_list = time_list
        self.__time_step = time_step
        self.__time_step_std = time_step_std
        self.__min_rt = min(time_list)
        self.__max_rt = max(time_list)

def amin(v):

    """
    @summary: Finds the minimum element in a list or array

    @param v: A list or array
    @type v: ListType, TupleType, or numpy.core.ndarray

    @return: Tuple (maxi, maxv), where maxv is the minimum 
        element in the list and maxi is its index
    @rtype: TupleType

    @author: Vladimir Likic
    """

    if not is_list(v):
        error("argument neither list nor array")

    minv = max(v) # built-in max() function
    mini = None

    for ii in range(len(v)):
        if v[ii] < minv:
            minv = v[ii]
            mini = ii

    if mini == None:
        error("finding maximum failed")

    return mini, minv

def rel_threshold(pl, percent=2):

    """
    @summary: Remove ions with relative intensities less than the given
        relative percentage of the maximum intensity.

    @param pl: A list of Peak objects
    @type pl: ListType
    @param percent: Threshold for relative percentage of intensity (Default 2%)
    @type percent: FloatType

    @return: A new list of Peak objects with threshold ions
    @rtype: ListType

    @author: Andrew Isaac
    """

    if not is_number(percent) or percent <= 0:
        error("'percent' must be a number > 0")

    pl_copy = copy.deepcopy(pl)
    new_pl = []
    for p in pl_copy:
        ms = p.get_mass_spectrum()
        ia = ms.mass_spec
        # assume max(ia) big so /100 1st
        cutoff = (max(ia)/100.0)*float(percent)
        for i in range(len(ia)):
            if ia[i] < cutoff:
                ia[i] = 0
        ms.mass_spec = ia
        p.set_mass_spectrum(ms)
        new_pl.append(p)
    return new_pl

    def plot_peaks(self, peak_list, label = "Peaks"):
	
        """
        @summary: Plots the locations of peaks as found
		  by PyMS.
		
	@param peak_list: List of peaks
	@type peak_list: list of pyms.Peak.Class.Peak
		
	@param label: label for plot legend
	@type label: StringType
        """
        
        if not isinstance(peak_list, list):
            error("peak_list is not a list")
		
	time_list = []
	height_list=[]
        
        # Copy to self.__peak_list for onclick event handling
        self.__peak_list = peak_list
	
	for peak in peak_list:
	    time_list.append(peak.get_rt())
	    height_list.append(sum(peak.get_mass_spectrum().mass_spec))
		
	self.__tic_ic_plots.append(plt.plot(time_list, height_list, 'o',\
	    label = label))

    def __init__(self, expr):

        """
        @param expr: The experiment to be converted into an alignment object
        @type expr: pyms.Experiment.Class.Experiment

        @author: Woon Wai Keen
        @author: Qiao Wang
        @author: Vladimir Likic
        """
        if expr == None:
            self.peakpos = []
            self.peakalgt = []
            self.expr_code =  []
            self.similarity = None
        else:
            if not isinstance(expr, Experiment):
                error("'expr' must be an Experiment object")
            #for peak in expr.get_peak_list():
            #    if peak.get_area() == None or peak.get_area() <= 0:
            #        error("All peaks must have an area for alignment")
            self.peakpos = [ copy.deepcopy(expr.get_peak_list()) ]
            self.peakalgt = numpy.transpose(self.peakpos)
            self.expr_code =  [ expr.get_expr_code() ]
            self.similarity = None

def window_analyzer(ic, window=_DEFAULT_WINDOW, n_windows=_DEFAULT_N_WINDOWS, rand_seed=None ):

    """
    @summary: A simple estimator of the signal noise based on randomly
        placed windows and median absolute deviation

        The noise value is estimated by repeatedly and picking random
        windows (of a specified width) and calculating median absolute
        deviation (MAD). The noise estimate is given by the minimum MAD.

    @param ic: An IonChromatogram object
    @type ic: pyms.IO.Class.IonCromatogram
    @param window: Window width selection
    @type window: IntType or StringType
    @param n_windows: The number of windows to calculate
    @type n_windows: IntType
    @param rand_seed: Random seed generator
    @type rand_seed: IntType

    @return: The noise estimate
    @rtype: FloatType

    @author: Vladimir Likic
    """

    if not is_ionchromatogram(ic):
        error("argument must be an IonChromatogram object")

    ia = ic.get_intensity_array() # fetch the intensities

    # create an instance of the Random class
    if rand_seed != None:
        generator = random.Random(rand_seed)
    else:
        generator = random.Random()

    window_pts = window_sele_points(ic, window)

    maxi = ia.size - window_pts
    noise_level = math.fabs(ia.max()-ia.min())
    best_window_pos = None
    seen_positions = []

    cntr = 0

    while cntr < n_windows:
        # generator.randrange(): last point not included in range
        try_pos = generator.randrange(0, maxi+1)
        # only process the window if not analyzed previously
        if try_pos not in seen_positions:
            end_slice = try_pos + window_pts
            slice = ia[try_pos:end_slice]
            crnt_mad = MAD(slice)
            if crnt_mad < noise_level:
                noise_level = crnt_mad
                best_window_pos = try_pos
        cntr = cntr + 1
        seen_positions.append(try_pos)

    return noise_level

def store_expr(file_name, expr):

    """
    @summary: stores an expriment to a file

    @param file_name: The name of the file
    @type file_name: StringType
    @param expr: An experiment object
    @type expr: pyms.Experiment.Class.Experiment

    @return: none
    @rtype: NoneType

    @author: Vladimir Likic
    @author: Andrew Isaac
    """

    if not isinstance(expr, Experiment):
        error("argument not an instance of the class 'Experiment'")

    if not is_str(file_name):
        error("'file_name' not a string")

    fp = open(file_name,'wb')
    cPickle.dump(expr, fp, 1)
    fp.close()

    def get_ic_at_index(self, ix):

        """
        @summary: Returns the ion chromatogram at the specified index

        @param ix: Index of an ion chromatogram in the intensity data
            matrix
        @type ix: IntType

        @return: Ion chromatogram at given index
        @rtype: IonChromatogram

        @author: Qiao Wang
        @author: Andrew Isaac
        @author: Vladimir Likic
        """

        if not is_int(ix):
            error("index not an integer")
        try:
            ia = []
            for i in range(len(self.__intensity_matrix)):
                ia.append(self.__intensity_matrix[i][ix])
        except IndexError:
            error("index out of bounds.")

        ic_ia = numpy.array(ia)
        mass = self.get_mass_at_index(ix)
        rt = copy.deepcopy(self.__time_list)

        return IonChromatogram(ic_ia, rt, mass)

    def plot_ics(self, ics, labels = None):
		
	"""
        @summary: Adds an Ion Chromatogram or a 
	list of Ion Chromatograms to plot list
	
	@param ics: List of Ion Chromatograms m/z channels
		for plotting
	@type ics: list of pyms.GCMS.Class.IonChromatogram 
	
	@param labels: Labels for plot legend
	@type labels: list of StringType
        """
	
        if not isinstance(ics, list):
	    if isinstance(ics, IonChromatogram):
		ics = [ics]
	    else:
		error("ics argument must be an IonChromatogram\
		or a list of Ion Chromatograms")
	
        if not isinstance(labels, list) and labels != None:
            labels = [labels]
        # TODO: take care of case where one element of ics is
	# not an IonChromatogram
		
	
	intensity_list = []
	time_list = ics[0].get_time_list()
			
	
	for i in range(len(ics)):
	    intensity_list.append(ics[i].get_intensity_array())
		
	
        # Case for labels not present
        if labels == None:
            for i in range(len(ics)):
                self.__tic_ic_plots.append(plt.plot(time_list, \
	            intensity_list[i], self.__col_ic[self.__col_count]))
	        if self.__col_count == 5:
                    self.__col_count = 0
                else:
                    self.__col_count += 1
        
        # Case for labels present
        else:
            for i in range(len(ics)):	
		
	        self.__tic_ic_plots.append(plt.plot(time_list, \
	            intensity_list[i], self.__col_ic[self.__col_count]\
	                , label = labels[i]))
	        if self.__col_count == 5:
                    self.__col_count = 0
                else:
                    self.__col_count += 1