---------------------------------------------------------
-	BYU MERS Antarctic Iceberg Database		-
-							-
---------------------------------------------------------

This readme is intended to explain what this database is, how to use it, and a few of the
attendant MATLAB scripts that can be used to update and use it. First, I'll go through
the structure of the files themselves. Then I'll give a rundown on the scripts that are
included in the database library.

FILES

Each file in the database contains information on one iceberg. The name of the iceberg is
also the name of the file. The headers of each file show the date, sensors, and sizes
associated with that iceberg. A few notes:

-Each sensor has two columns associated with it, namely 'sensor_1' and 'sensor_2'.
'sensor_1' is the latitude and 'sensor_2' is the longitudinal measurement of each
sensor on the given date.

-Some sensors have a third column (most notably, the NIC). This is a binary flag that
indicates if the measurement is interpolated for that day or not.

-Dates are shown in JD format, with the year first followed by the Julian date. They're intended
to be read in as strings.

-'size_1' and 'size_2' show the length of the major and minor axes of the iceberg on
the date, as given by the NIC, in nautical miles. To convert to km, multiply the number by 1.852.

-Each file shows only the sensors that have data available for that iceberg. This means that the
number of columns in each file is variable.

There is also a single file, called 'all_bergs.csv', that is basically all the iceberg files
mashed together into a single file.

SCRIPTS

There are a bunch of scripts contained in the lib directory that are included for ease of use
in manipulating the data. I'll go through each of these scripts, one by one, and explain how to
use them in this section.

write_db.m

[] = write_db(input_struct, path, varargin)

This doesn't output anything in MATLAB; instead, it takes the input structure and writes the struct's fields to separate files,
placing them in the directory indicated by the path variable. This is meant to take a struct formed by the build_db script and
write that struct out into CSV files for later use. However, it should work for any nx1 nested struct in MATLAB.

INPUTS
input_struct: the struct you want to write to files. This should be a multi-level struct; that is, a struct with several structs inside,
each representing an iceberg.

path: the path to the directory you want to write the files to.

OPTIONAL INPUTS:
There's only one of these at the moment.
write_db(input_struct, path, 'SingleFile', true/false) sets the script to write everything to a single file.

build_db.m

s = build_db(filePath)

Builds a MATLAB struct that takes all the CSV files in a directory and combines them into a single struct, with each iceberg contained as a nested struct
inside of that first struct. Struct struct struct.
This takes all CSV files in a single directory and adds them to the outputted struct. It will ignore anything else in the directory.

OUTPUTS:

s: the master struct. Each iceberg is contained inside of this as a smaller struct named after the iceberg, with fields for all the columns.

INPUTS:

filePath: the path to the directory where the iceberg files are stored. They must be in the right format, i.e., have been built by 
write_db.m, in order for this script to work.

build_simplified_database.m

final_data = build_simplified_database(input_struct)

Takes the input_struct and does all the higher-leve statistical stuff to it to make a derivative measurement database. Combines them all into
a single struct, like the build_db.m script, but with different fields.

This does the cubic interpolation of measurements, runs a masking algorithm to determine the surroudings of an iceberg,
calls contour_iceberg.m to find the area and rotation angles of the iceberg, and averages all the sensor positions into
a single continuous track, with a flag showing the sensors used to do so.

OUTPUTS:

final_data: master struct containing all the iceberg structs.

INPUTS:

input_struct: input struct with all the iceberg positions and sensors. This should be the struct output with build_db.m, otherwise it won't work.

contour_iceberg.m

[err, masks, F] = contour_iceberg(berg, start_date, end_date, varargin)

This horrendously complicated behemoth of a script takes iceberg positions, combines them with SIR images, and uses those to determine the area,
rotational velocity, and other random statistical things while classifying the surroundings of the iceberg.
See the file itself for a more indepth discussion of what it does. Also, read Jeff Budge's thesis.

OUTPUTS:

err: double showing mean error of high SNR estimates with an NIC value.

masks: double array giving mask numbers.

F: struct array with different statistical analyses and arrays, depending on the Return options given above.

INPUTS:

berg: the iceberg struct from build_db.m. Don't input the top-level struct, it won't work. Use one of the named iceberg structs inside of it.

start_date: string in JD format showing where to start. Must be chronologically before end_date, as is obvious. 

end_date: string in JD format showing where to end. The script will run for every day with data between the two given dates.

varargin: the many options for this script. This can get kinda confusing, so here's an example:

[~, ~, F] = contour_iceberg(data.b15b, '2005120', '2005130', 'Return', {'sizes', 'angles', 'movie'});

This will find the SIR images from 2005120 to 2005130, select the area around the locations for those dates given in the data.b15b struct,
then run the algorithm on them. It will return (in the struct F) the generated area of the iceberg, the rotational angles, and a movie 
consisting of the SIR image areas with a contour around the iceberg in red. It will also generate several plots pertaining to these things,
and run the movie.

If you don't want the plots to show up, set 'NoPlot' equal to true, as in

[~, ~, F] = contour_iceberg(data.b15b, '2005120', '2005130', 'Return', {'sizes', 'angles', 'movie'}, 'NoPlot', true);

...and you're golden.

The 'Windows' option is an interesting animal. If you want to run the same iceberg and dates over and over again, you can speed up
the process by saving the selected iceberg areas in the F.windows struct and using those, so it doesn't have to find SIR images
and run half the process again. Do this by taking a previously generated F struct and running the function like so:

[~, ~, F] = contour_iceberg(data.b15b, '2005120', '2005130', 'Return', {'sizes', 'angles', 'movie'}, 'Windows', F.windows);

This will take the windows previously generated and use them instead of whatever else you put in. Note that I say instead:
it will ignore whatever else you put into the berg, start_date, and end_date variables. If you want to generate size
estimates for a different iceberg or different dates, get rid of the 'Windows' option.

The contour_berg.m function has several little helper functions inside of the file as well. Those are explained in their
respective functions.




