#  - record all downloads to a log file?

def list_contents(ftp):

def download_mod11a1(destdir, tile, start_doy, end_doy, year, ver=5):

    """Download into destination directory the MODIS 11A1 HDF files

    matching a given tile, year, and day range. If for some unexpected

    reason there are multiple matches for a given day, only the first is

    used. If no matches, the day is skipped with a warning message.

    Arguments:

    destdir -- path to local destination directory

    tile -- tile identifier (e.g., 'h08v04')

    start_doy -- integer start of day range (0-366)

    end_doy -- integer end of day range (0-366)

    year -- integer year (>=2000)

    ver -- MODIS version (4 or 5)

    Returns list of absolute paths to the downloaded HDF files.

    """

    # connect to data pool and change to the right directory

    ftp = ftplib.FTP('e4ftl01.cr.usgs.gov')

    ftp.login('anonymous', '')

    ftp.cwd('MOLT/MOD11A1.%03d' % ver)

    # make list of daily directories to traverse

    available_days = list_contents(ftp)

    desired_days = [yj_to_ymd(year, x) for x in range(start_doy, end_doy+1)]

    days_to_get = filter(lambda day: day in desired_days, available_days)

    if len(days_to_get) < len(desired_days):

        missing_days = [day for day in desired_days if day not in days_to_get]

        print 'skipping %d day(s) not found on server:' % len(missing_days)

        print '\n'.join(missing_days)

    # get each tile in turn

    hdfs = list()

    for day in days_to_get:

        ftp.cwd(day)

        files_to_get = [file for file in list_contents(ftp)

            if tile in file and file[-3:]=='hdf']

        if len(files_to_get)==0:

            # no file found -- print message and move on

            print 'no hdf found on server for tile', tile, 'on', day

            continue

        elif 1<len(files_to_get):

            # multiple files found! -- just use the first...

            print 'multiple hdfs found on server for tile', tile, 'on', day

        file = files_to_get[0]

        local_file = os.path.join(destdir, file)

        ftp.retrbinary('RETR %s' % file, open(local_file, 'wb').write)

        hdfs.append(os.path.abspath(local_file))

        ftp.cwd('..')

    # politely disconnect

    ftp.quit()

    # return list of downloaded paths

    return hdfs

        hdfs.append(os.path.abspath(files[0]))

# create raster of pixelwise N for a list of input rasters

def calc_nobs(maplist, name, overwrite=False):

    denominator = '(%s)' % '+'.join(['if(!isnull(%s))' % m

        for m in maplist])

    gs.mapcalc('nobs_%s = %s' % (name, denominator), overwrite=overwrite)

#---------------------------------------------

# test: download then aggregate for one month

#---------------------------------------------

# TODO: set up a (temporary?) GRASS database to use for processing? code

# currently assumes it's being run within an existing GRASS session

# using an appropriately configured LOCATION...

# note the following trick to fix datum for modis sinu;

# TODO: check that this works properly...compare to MRT output?

# gs.run_command('g.proj', flags='c',

#     proj4='+proj=sinu +a=6371007.181 +b=6371007.181 +ellps=sphere')

##    proj4='+proj=sinu +R=6371007.181 +nadgrids=@null +wktext')

tile = 'h09v04'

start_doy = 1

end_doy = 31

hdfdir = '.'

# download data

### [atlas 17-May-2012] Wall time: 111.62 s

hdfs = download_mod11a1(hdfdir, tile, start_doy, end_doy, year)

# note: now that we've downloaded the files into local directory

# 'hdfdir', this should yield the same list...

#hdfs = get_hdf_paths(hdfdir, tile, start_doy, end_doy, year)

# generate monthly pixelwise mean & count of high-quality daytime LST

# values

### [atlas 17-May-2012] Wall time: 51.18 s