wrapper to run external programs

    :command:           list containing command and parameters
                        (formatted the same as subprocess; must contain only strings)
    :products:          string or list of files that are the products of this command
                        if all products exist, the command will not be run, and False returned
    :working_directory: will chdir to this directory
    :force_local:       when used with `neural.scheduler`, setting to ``True`` will disable
                        all job distribution functions
    :stderr:            forward ``stderr`` into the output
                        ``True`` will combine ``stderr`` and ``stdout``
                        ``False`` will return ``stdout`` and let ``stderr`` print to the console
                        ``None`` will return ``stdout`` and suppress ``stderr``
    :quiet:             ``False`` (default) will print friendly messages
                        ``True`` will suppress everything but errors
                        ``None`` will suppress all output

    Returns result in form of :class:`RunResult`

def run(command,products=None,working_directory='.',force_local=False,stderr=True,quiet=False):
    '''wrapper to run external programs

    :command:           list containing command and parameters
                        (formatted the same as subprocess; must contain only strings)
    :products:          string or list of files that are the products of this command
                        if all products exist, the command will not be run, and False returned
    :working_directory: will chdir to this directory
    :force_local:       when used with `neural.scheduler`, setting to ``True`` will disable
                        all job distribution functions
    :stderr:            forward ``stderr`` into the output
                        ``True`` will combine ``stderr`` and ``stdout``
                        ``False`` will return ``stdout`` and let ``stderr`` print to the console
                        ``None`` will return ``stdout`` and suppress ``stderr``
    :quiet:             ``False`` (default) will print friendly messages
                        ``True`` will suppress everything but errors
                        ``None`` will suppress all output

    Returns result in form of :class:`RunResult`
    '''
    with run_in(working_directory):
        if products:
            if isinstance(products,basestring):
                products = [products]
            if all([os.path.exists(x) for x in products]):
                return False

        command = flatten(command)
        command = [str(x) for x in command]
        quiet_option = False if quiet==False else True
        with nl.notify('Running %s...' % command[0],level=nl.level.debug,quiet=quiet_option):
            out = None
            returncode = 0
            try:
                if stderr:
                    # include STDERR in STDOUT output
                    out = subprocess.check_output(command,stderr=subprocess.STDOUT)
                elif stderr==None:
                    # dump STDERR into nothing
                    out = subprocess.check_output(command,stderr=subprocess.PIPE)
                else:
                    # let STDERR show through to the console
                    out = subprocess.check_output(command)
            except subprocess.CalledProcessError, e:
                if quiet!=None:
                    nl.notify('''ERROR: %s returned a non-zero status

    ----COMMAND------------
    %s
    -----------------------


    ----OUTPUT-------------
    %s
    -----------------------
    Return code: %d
    ''' % (command[0],' '.join(command),e.output,e.returncode),level=nl.level.error)
                out = e.output
                returncode = e.returncode
            result = RunResult(out,returncode)
            if products and returncode==0:
                result.output_filename = products[0]
            return result