Requirements

This should be completed before the start of the lab.

Install Sea, earth, atmosphere Data Analysis System (SeaDAS) version 8.3 and up.

Once up and running, install OCSSW data processing components for Moderate Resolution Imaging Spectroradiometer (MODIS)-Aqua (see instructions below the SeaDAS download instructions). Take particular note of the system and software requirements for installation. One issue that has recurred is the absence of a requests library in Python. One example way to resolve this is running the following from a terminal window:

/usr/bin/python3  -m pip install --user requests 

You will also need to set up an Earthdata login. Your login credentials then need to be stored in a file in your home directory. In your home directory, create a file called .netrc (note the leading period) using the terminal:

echo "machine urs.earthdata.nasa.gov login USERNAME password  PASSWD" > ~/.netrc ; > ~/.urs_cookies

chmod  0600 ~/.netrc 

For USERNAME and PASSWD use your Earthdata Login credentials.

1. The Command Line Environment

All SeaDAS data processing functions are available through a graphical user interface (GUI) and a command line executable. Using the latter requires setting up the proper command line environment.

Open a terminal window. Locate your OCSSW software installation (path).

By default, this should be a subdirectory within your SeaDAS installation. For example: /Applications/seadas/occsw.

Define an environmental variable called OCSSWROOT that points to your OCSSW software installation. The language for doing so depends on your shell. On Apple computers, the default is bash:

export OCSSWROOT=/[Path to SeaDAS OCSSW folder] 

e.g.

export OCSSWROOT=/Applications/seadas/ocssw 

Confirm the installation via the command:

printenv OCSSWROOT 

This should print the [path to SeaDAS] that you entered to your terminal screen.

Finish setting up the command line environment by sourcing the data processing environmental variable file. This file defines the locations of all files required by OCSSW. In bash:

source $OCSSWROOT/OCSSW_bash.env 

Confirm the environment has been set via the command:

which l2gen 

This should print the full path to the file l2gen to your terminal screen (e.g., /Applications/seadas/ocssw/bin/l2gen ).

If you experienced an OCSSW install error in Section 0, you may also need to run the following from a terminal window to complete installation of required satellite data files:

update_luts [sensor name] 

e.g.

update_luts modisa

update_luts viirsj1 

See the SeaDAS web site for identification of recognizable instrument names.

2. Data Acquisition

Next, let's locate, download, and identify the file type of Level 1A and Level 2 satellite data. We will use these files over the course of this lab.

Acquire the following MODIS-Aqua files from the OceanColorWeb Level-1/2 browser. They encompass three successive days in the Gulf of Maine, 29 Sep 2018 to 1 Oct 2018:

The above provides everything you need to know to find these files.

The files come in different file formats. What are they?

Level 1A download as bunzip2 files, which extract to an hdf4 file

Level 2 files are netCDF / hdf5

It's time to open SeaDAS.

3. Level 1 and Level 2 Data Extraction

Full granules can be large. Images with lots of water can take a significant amount of time to process from Level-1 to -2. Let's extract our region of interest, the Gulf of Maine, defined here as:

• 40° to 46° N, and
• -75° to -60° W

You will need to open the full files in SeaDAS first either by going into File > Open Product or by dragging and dropping the files into the SeaDAS file manager.

Use the OCSSW Extractor (GUI) to Create Subsetted Level 1A and Level 2 Files

Go to SeaDAS-Toolbox > SeaDAS Processors > extractors

Do the Level-2 files first, using the above latitude and longitude boundaries to define the extract. Do not run the extractor yet. You'll notice that the start and end pixel and line number fields get populated after you've added the latitude and longitude boundaries. Write these down. You will need them to run the Level-1A extracts.

Boundary Values

File	spixl	epixl	sline	eline
A2018272172500.L1A_LAC	270	1278	1	774
A2018273180500.L1A_LAC	1	675	1109	1890
A2018274171000.L1A_LAC	450	1345	976	1924

Another way of extracting with SeaDAS is to make a subset using Raster > Subset and to enter the boundaries like you would with the extractor. That also allows you to choose the bands that you want to keep in your subset. The created file then needs to be saved.

Why can you use latitude and longitude to define extractions for Level 2, but not for Level 1A?
 

• Level 2 files have been geolocated and, thus, include latitude and longitude information.
• Level 1A files have not been geolocated and, thus, latitudes and longitudes are not yet assigned to each pixel.

Once you've created the six extracts, you can close the full files for the remainder of this lab.

4. Geolocation

MODIS-Aqua Level 1A files need to be geolocated before Level-2 files can be generated. Note: This is not true for all ocean color satellites. SeaWiFS, for example, does not require this step. This doesn't mean that SeaWiFS files aren't geolocated, only that this process is consolidated elsewhere in the SeaWiFS data processing architecture.

Use the OCSSW MODIS GEO processor to geolocate one or two of the three Level 1A extracts using default options.

5. Command Line Processing

All SeaDAS data processing GUIs list the name of their corresponding command line executable on the top bar of the GUI window.

What is the name of the executable for the MODIS GEO processor?

modis_GEO.py

Where is this script located?

$OCSSWROOT/scripts/

What language is it written in?

Python

Run the MODIS GEO script from your terminal window without any inputs:

modis_GEO 

Help and usage information will scroll in your terminal window. All SeaDAS command line executables do this when you run the command without input variables. If you've set up the terminal environment correctly, you do not need to provide the full paths to the executables to run them.

Use the command line to geolocate the remaining one or two L1A extracts.

First, cd into your folder so that your files save in the right place:

cd [path to your folder] 

e.g.

cd /accounts/cpoulin/SeaDAS 

Then create de GEO file:

modis_GEO [L1Afile (path+L1A filename)] 

e.g.

modis_GEO  /Applications/seadas/data/A2018272172500.L1A_LAC 

6. Level 1B Processing

MODIS-Aqua Level-1A files need to be processed to Level-1B before Level-2 files can be generated. Again, not all ocean color satellites require this independent processing step.

Use the OCSSW MODIS L1B processor to generate Level-1B files. Consider using both the GUI and the command line. Do not provide any inputs other than the Level-1A and GEO file names:

modis_L1B [L1Afile] [GEOFILE] 

How many files were created per run?

3

How do these files differ? (Hint: open them in SeaDAS and have a look.)

LAC file has the 1 km data products

HKM files have the 500-m bands (469, 555, 1240, 1640, 2130 nm)

QKM files have the 250-m bands (645, 859 nm)

We will not be using the HKM or QKM files the remainder of this lab.

7. Standard Level 2 Processing

The "l2gen" executable in SeaDAS provides Level-2 processing capabilities for all ocean color instruments under the auspices of the GSFC Ocean Biology Processing Group. When you run l2gen without any inputs (other than the input file names and ancillary data file names), you will exactly recreate the Level-2 files distributed on the OceanColorWeb.

Open the OCSSW l2gen processor GUI.

Select the extracted AQUA_MODIS.20180929T172500* L1B as ifile. If you have a Level-1B file highlighted in the File Manager window, the geofile and ofile fields will self-populate.

Rename the ofile - otherwise, you may overwrite the Level-2 extract you previously created.

Acquire the ancillary data associated with this data file (hint: there is a GUI button). Run l2gen.

Open the Level-2 extract you created previously and the Level-2 file that you just produced.

View the chlor_a product for each. How do they compare?

There may be an offset in the geographic boundaries of the imagery, but the geophysical data and its spatial patterns should be identical.

Repeat for the other 2 Level-1B extracts. Continue until you are convinced that the Level-2 files you generate are identical to the Level-2 extracts you created previously. This is also a good way to verify that you ran the extractor properly.

8. l2gen Parameterizations and Command Line Usage

Without exaggeration, l2gen can produce hundreds of geophysical data products and be configured in thousands of different combinations.

Open the l2gen GUI and explore the tabs.

Note several highlights: The "Processing Options" and "Ancillary Inputs" tabs, the "IOP Options" tab, and the band-ratio chlorophyll algorithms can be tuned in the "Miscellaneous" tab.

To run l2gen from the command line:

l2gen par=[parameter file] 

where the parameter file includes a list of keyword=value pairs (one per line).

Note that you can also run l2gen from the command lines as:

l2gen header1=keyword1 header2=keyword2 header3=keyword3 

… and so on.

l2gen 

Revert to using the correct ancillary data for the remainder of this exercise.

9.2 Generate a Level-2 file with the vicarious gains all set to 1.0.

Revert to using the correct vicarious gains for the remainder of this exercise.

9.3 Generate a Level-2 file using short-wave infrared (SWIR) bands instead of near-infrared (NIR) bands in the atmospheric correction (set aer_wave_short=1240 and aer_wave_long=2130).

Revert to using the Level 2 files you created in Section 7 for the remainder of this lab.

10. Spatially Compositing Data

Someday, you may find yourself wanting or needing to re-grid (re-project) your Level 2 data onto a standard map grid. Here are examples of two common grids:

Note the differences in bin size as a function of latitude. Examine, e.g., Greenland.

One quick way to visualize the transformation from the satellite swath coordinate system to a standard map grid is to use OCSSW mapgen (formerly l2mapgen). This utility reprojects a Level-2 file onto a Plate Carree grid (panel B above) and generates a PNG or PNM image.

The NASA processing cadence for producing Level-3 maps is:

(1) generate a Level-3 bin file, which is always in a sinusoidal map projection (panel A above) that retains equal distance in latitude and longitude space from north to south; then,

(2) generate the Level-3 map file in the projection of your choice (standard is Plate Carree). *SeaDAS cannot open Level-3 bin files.*

Let's next explore the effects of spatially re-gridding Level-2 data on geophysical values.

Use OCSSW l2bin to generate a series of chlor_a Level-3 bin files for AQUA_MODIS.20180929T172500. Always set "l3bprod" to chlor_a. Always set "prodtype" to regional. Run four times with "resolution" set to 1, 2, 4, and 9 km. Rename the ofile each time to avoid overwriting existing files.

Next, use OCSSW l3mapgen to convert these Level 3 bin files into Level 3 map files. Manually type "chlor_a" as the "product", leave the projection at "platecarree", and set the resolution to 1 km, 2 km, 4 km, and 9 km based on the resolution of the Level-3 bin file you are mapping.

This is a good time to revisit the help/usage information provided when running an OCSSW program without any input values. It is recommended that you do this for any program you plan to use to best understand the operation and options of that program.

Type in a terminal window:

l3mapgen

Focus on usage for the "product" input. Note that you can modify an input product to report alternate statistics, such as standard deviations and the number of observations that filled each Level-3 grid-bin. Such information on capabilities is not always intuitive within a GUI environment. Best practices involve studying command line options.

Open the original Level 2 and the four Level 3 mapped chlor_a products.

To explore how geophysical values change with re-gridding, let's focus on a specific high chlorophyll area to the east of Cape Cod:

Quantify if/how this feature distorts relative to the Level-2 data when re-gridded at different spatial resolutions. You can do this through analysis of samples sizes, histograms or cumulative distributions, metrics of central tendency, or by other means of your choice. SeaDAS provides many options for such image analysis.

Now imagine that you're studying a small or filamentous feature, say a thin bloom of Trichodesmium offshore of Australia or Noctiluca in the Gulf of Oman.

11. Temporally Compositing Data

Someday, you may find yourself wanting or needing to temporally composite your data into a longer term average (say, weekly, monthly or seasonally).

Use OCSSW l2bin to create regional 2-km chlor_a Level-3 bin files for the other two Level 2 files you generated in Section 7 (AQUA_MODIS.20180930T180500 and AQUA_MODIS.20181001T171000). When done, you should have three Level 3 2-km chlor_a bin files (one for each day).

We now want to create a single, temporal composite of these three files. We'll use OCSSW l3bin to do this, which will involve a different process than that for l2bin.

First, create a plain text file that lists the full name of all three Level 3 bin files to be composited, with one file name per line. For example:

A2018272.L3b_DAY_OC_2.sub

A2018273.L3b_DAY_OC_2.sub

A2018274.L3b_DAY_OC_2.sub 

Select this text file as the ifile in the l3bin GUI. Next, type chlor_a as the prod and change the latitude and longitude boundaries to those we've been using in this lab (otherwise, you will create a global map … worth trying, though!).

After your 3-day Level 3 bin file has been created, use l3mapgen again to create a 2-km Level 3 map, as you did in Section 10.

12. Level 3 Data Processing

Perhaps not widely known, OCSSW software within SeaDAS allows generation of geophysical data products from Level 3 Rrs bin files.

To explore this, we need to generate a Level 3 bin file that includes Rrs. Run l2bin on AQUA_MODIS.20180929T172500, but this time do not set assign a "l3bprod" in the GUI. Leaving this field blank will bin all products in the Level-2 file (if you ran l2bin from the command line without any inputs you should already know this). Do set prodtype to "regional" and resolution to "2."

Run l3mapgen to convert this Level 3 bin file into a Level 3 map. Leaving the "product" field blank will create a map file containing all three IOP data products (again, you know this already if you ran l3mapgen from the command line to see its usage).

This is a good place to explore how different configurations of an IOP model influence the derived adg, aph, and bbp. Repeat this exercise, but use the "IOP Options" tab in the l3gen GUI to reparametrize GIOP.

End of laboratory. Nice work.