README.txt

README File for Programs Submitted for Comprehensive Exams
Paul Cottle  -  January 31, 2013
------------------------------------------------------------
Essentially, I'm submitting this stuff just to show that although
I perhaps haven't made nearly enough progress on the inversion of 
lidar data, I haven't been completely idle either.  The programs
that follow are my attempt at achieving the follwing tasks focused
on an analysis of the dust transport event of 2010.  Some of the programs
were used to generate data that were
included in the paper I submitted to ACP on the topic, the rest are to
be included in a later paper on the development of the aerosols
in transit.

I think that these programs, with a little polishing, will be useful in analysing
the data I collect from my upcoming trip to China as well.

Goals:

1) To generate plots of CORALNET lidar backscatter and depolarization
ratios

2) To generate HYSPLIT back trajectories for a range of times, locations
and durations that can be turned into HYSPLIT frequency plots

3) To determine which of these back trajectories pass over the Taklamakan
and Gobi Desert regions (roughly approximated as ellipses) and calculate 
the total time in transit and distance travelled

4) To collect AERONET inversion data - most importantly fine and coarse
mode mean diameters and standard deviations for a variety of stations and filter
results to include only those resulting from days where HYSPLIT trajectories
passed over Asian deserts

5) (not complete) Plot AERONET inversion data against travel distance and time
based on HYSLPIT results

6) Collect, organize, and plot (not complete) data from IMPROVE sites to try to 
track the elementaal composition of the dust

Modules:

LNC_tools_v2: This is a set of tools used to take an ASCII file generated by LNC (the
custom processing tool for CORALNet lidars), resample it at regular time and altitude
intervals, and convert it into a pandas dataframe.  Ther eis also a tool to use a 
ackscatter ratio datafram and mask another dataframe (in this case de-polarization ratios)
by removing data everywhere the backscatter ratio is within a defined boundary of the 
value for pure molecular scttering(BR=1)

LNC_fileproc_v1: takes a group of folders containing ASCII files from LNC and resamples them
into a single dataframe with a uniform altitude and time step for plotting  saves the results
as a .pickle file

LNC_plot_v2: allows the user to select two .pickle files containing dataframes generated
by LNC_tools and plots them together into a figure

hysplit_tools_v3: This is a miscelaneous selection of tools used to perform various
tasks associated with generating and processing aeronet and hysplit data files

dustrun2010_v6: This program takes a list of AERONET stations (or really any places
with lat-lon co-ordinates) and generates a set of HYSPLIT trajectories of designated
starting time, altitude, and duration.  The results are saved in a directory of the
user's choosing in subfolders setinn in tuples with the co-ordinates
This program requires a working copy of HYSPLIT as well as the necessary meteorological
files to operate

hysplit_traceback_v2: This program takes a folder filled with hysplit trajectory files
and filters them to determine which ones contain trajectories that fall at some point
within the defined desert ellipses.  it also determines the total distance and time
spent in transit

file_process_tools_v3: takes a group of aeronet and hysplit files and processes them
into one large combined data file

hysplit_aeronet_fullproc_v3 - a master program that uses the above processing and traceback 
programs to take a set of folders containing hysplit and aeronet files and processes them
into a single, filtered and processed file with dataframes ready for analysis

IMPROVE_tools_v1 - similar to the above tools, but for IMPROVE data sets downloaded
as ASCII files.  Saves the results into dataframes in two files, one for April, 2010
and the other for all of 2010