Sargassum.jl

Appearance

AFAI API ​

These are the full docstrings for the AFAI subsection of Sargassum.jl.

Index ​

Downloading AFAI Data ​

Sargassum.AFAI_DOWNLOADED_PATHS Constant
julia
const AFAI_DOWNLOADED_PATHS

A Dict mapping (year, month) pairs to the path of the downloaded data.

Examples

Obtain a list of all AFAI data that has ever been downloaded.

julia
julia> keys(AFAI_DOWNLOADED_PATHS)

Read the metadata of the .nc file.

julia
julia> using NetCDF # install this if you haven't already
julia> ncinfo(AFAI_DOWNLOADED_PATHS[(2018, 4)])

source

Sargassum.download_raw_afai Method
julia
download_raw_afai(year::Integer, month_spec; force = false)

Download raw AFAI data from

https://cwcgom.aoml.noaa.gov/erddap/griddap/noaa_aoml_atlantic_oceanwatch_AFAI_7D.html

Four files are downloaded, one on the 7th, 14th, 21nd and 28th of each month, each of which are 7-day aggregates.

Refer to [AFAI_DOWNLOADED_PATHS] for the current status of downloaded data.

Arguments

  • year should be an integer equal to at least 2017 (the first full year available).

  • month_spec can be one of the following

    • an integer between 1 and 12: download the data from the corresponding month

    • a vector of integers each between 1 and 12: download the data from all of the corresponding months

    • omitted: download the data for every month in the given year

Optional Arguments

  • force: If true, download the data even if it has already been downloaded. Default false.

source

Sargassum.remove_raw_afai Method
julia
remove_raw_afai(year, month)

Remove the raw data file corresponding to (year, month) and update AFAI_DOWNLOADED_PATHS.

Does not throw an error if the data has not been downloaded.

source

Sargassum.remove_raw_afai Method
julia
remove_raw_afai(; force = false)

Remove all raw data file corresponding to (year, month) and update AFAI_DOWNLOADED_PATHS.

Requires passing force = true to work.

source

Sargassum.update_afai_downloaded_paths! Method
julia
update_afai_downloaded_paths!()

Update AFAI_DOWNLOADED_PATHS by reading _AFAI_RAW_SCRATCH.

source

AFAI ​

Sargassum.AFAI Type
julia
mutable struct AFAI{U, T, R}

A container for the AFAI data.

Fields

  • lon: A Vector of longitudes.

  • lat: A Vector of latitudes.

  • time: A Vector of DateTimes.

  • afai: An Array of AFAI/Sargassum values of the form afai[lon, lat, time].

  • coast: A BitMatrix of size size(afai)[1:2] such that coast[i, j] = 1 when the point (lon[i], lat[j]) is on a coastline.

  • clouds: A BitArray of size size(afai) such that clouds[i, j, t] = 1 when there is a cloud at (lon[i], lat[j]) and week t.

  • classification: A BitArray of size size(afai) such that clouds[i, j, t] = 1 when there Sargassum at (lon[i], lat[j]) and week t.

  • params: A AFAIParameters.

Constructor

AFAI(filename::String, params::AFAIParameters)

filename is a NetCDF of the form name.nc

It is assumed that the file is obtained from the NOAA database:

https://cwcgom.aoml.noaa.gov/erddap/griddap/noaa_aoml_atlantic_oceanwatch_AFAI_7D.html

The fields coast, clouds and classification are initialized with 0's by default. Use coast_and_clouds! and pixel_classify! to construct them fully.

Plotting

This object can be [viz](@ref).

source

Sargassum.AFAIParameters Type
julia
struct AFAIParameters{U, T}

A container for the parameters required to process the AFAI data.

Fields

  • window_size_coast_mask: An Integer giving the distance, in gridpoints, such that all gridpoints within that distance of the coastline are masked (removed.) Default: 20.

  • window_size_median_filter: An Integer giving the size, in gridpoints of the median filter applied to the data. Default: 51.

  • threshold_median: A Real such that all median-filtered afai values below it are considered to not contain Sargassum. Default: 1.79e-4.

  • afai_U0: A Real giving the global upper limit on afai values for Sargassum-containing pixels. Default: 4.41e-2.

  • afai_L0: A Real giving the global lower limit on afai values for Sargassum-containing pixels. Default: -8.77e-4.

  • lon_lat_bins_coverage: A Tuple{Integer, Integer} of the form (lon_bins, lat_bins) where the final coverage distribution is binned with lon_bins horizontally and lat_bins gridpoints vertically. Default (134, 64).

  • distribution_quant: A Real giving the quantile below which bins are discarded in the final coverage distribution calculation. Default: 0.85.

Constructors

AFAIParameters(; params...)

Each field has a named kwarg.

source

SargassumDistribution ​

Sargassum.SargassumDistribution Type
julia
struct SargassumDistribution{T, R}

A container for a gridded distribution of Sargassum.

Fields

  • lon: A vector of longitudes.

  • lat: A vector of latitudes.

  • time: A DateTime giving the month and year when the distribution was computed.

  • coast: A BitMatrix of size size(sargassum)[1:2] such that coast[i, j] = 1 when the point (lon[i], lat[j]) is on a coastline.

  • clouds: A BitArray of size size(sargassum) such that clouds[i, j, t] = 1 when there is a cloud at (lon[i], lat[j]) and week t.

  • sargassum: An Array with dimensions (lon x lat x 4) whose entries give the fractional coverage of Sargassum at each gridpoint and week of the month. Each value is expressed as a percentage of the total coverage in the entire grid in that month, that is, sargassum is a probability distribution on the grid of longitudes, latitudes and weeks. Or, more simply put, we have sum(sargassum) == 1.

Constructing from AFAI

SargassumDistribution(afai::AFAI)

In general, afai should be processed with clean_pacific!, coast_and_clouds!, pixel_classify! and pixel_unmix!.

The data in afai are binned according to the bin size defined by afai.params.lon_lat_bins_coverage. For the clouds and coast, a bin is true if its mean over all pixels is greater than 0.5.

Constructing from a NetCDF file

SargassumDistribution(infile::String)

A dictionary with entries of the form (year, month) => distribution is returned.

Constructing manually

SargassumDistribution(; kwargs...)

Each field has a named kwarg. If coast and clouds are not provided, they are initialized using falses.

Plotting

This object can be viz and viz!.

source

Sargassum.sargassum_distribution Function
julia
sargassum_distribution(year, month_spec, outfile; params)

Write the SargassumDistribution at year year to the NetCDF file outfile.

  • month_spec can be one of the following

    • an integer between 1 and 12: download the data from the corresponding month

    • a vector of integers each between 1 and 12: download the data from all of the corresponding months

    • omitted: download the data for every month in the given year

This is the highest level function available and attempts to download the data automatically if it hasn't already been downloaded and run the full calculation.

Optional Arguments

source

Sargassum.distribution_to_nc Function
julia
distribution_to_nc(distributions::Vector{<:SargassumDistribution}, outfile::String)

Write the vector of SargassumDistributions in distributions to the NetCDF file named in outfile. That is, outfile should be of the form name.nc.

distribution_to_nc(distribution::SargassumDistribution, outfile::String)

Write a single distribution as above.

source

Precomputed Sargassum distributions ​

Sargassum.SARGASSUM_DISTRIBUTION_PRECOMPUTED Constant
julia
const SARGASSUM_DISTRIBUTION_PRECOMPUTED

A dictionary mapping years to SargassumDistribution precomputed for that year using default AFAIParameters.

Use download_precomputed() to populate this dictionary.

Examples

Populate the dictionary

julia
julia> download_precomputed()

Access the SargassumDistribution from April, 2018.

julia
julia> SARGASSUM_DISTRIBUTION_PRECOMPUTED[(2018, 4)]

See all available (year, month) pairs.

julia
julia> keys(SARGASSUM_DISTRIBUTION_PRECOMPUTED)

source

Sargassum._SARGASSUM_DISTRIBUTION_PRECOMPUTED_LINKS Constant
julia
const _SARGASSUM_DISTRIBUTION_PRECOMPUTED_LINKS

A dictionary mapping years to the link where the precomputed SargassumDistributions can be downloaded for that year.

source

Sargassum.download_precomputed Method
julia
download_precomputed()

Download SargassumDistribution precomputed using default AFAIParameters.

This overwrites all precomputed distributions.

source

Sargassum.update_sargassum_distribution_precomputed! Method
julia
update_sargassum_distribution_precomputed!()

Update SARGASSUM_DISTRIBUTION_PRECOMPUTED by reading _SARGASSUM_DISTRIBUTION_PRECOMPUTED_SCRATCH.

source

Earth Polygons ​

Sargassum.VERTICES_NORTH_ATLANTIC Constant
julia
const VERTICES_NORTH_ATLANTIC

An matrix of (x, y) coordinates (each row is a new coordinate) such that the polygon defined by these coordinates contains the North Atlantic with longitudes in ~[-100, -30] and latitudes in ~[5, 35].

source

Sargassum.VERTICES_PACIFIC_PANAMA Constant
julia
const VERTICES_PACIFIC_PANAMA

An matrix of (x, y) coordinates (each row is a new coordinate) such that the polygon defined by these coordinates contain the Pacific side of the Panama Canal. Used to remove Sargassum in this region.

source

Internal SargassumDistribution Calculations ​

Sargassum.clean_pacific! Function
julia
clean_pacific!(afai; vertices)

Remove any Sargassum pixels that have crossed the Panama canal from afai.afai; by default this is done by removing Sargassum from pixels whose centers are inside VERTICES_PACIFIC_PANAMA.

source

Sargassum.coast_and_clouds! Function
julia
coast_and_clouds!(afai; apply_coast)

Compute afai.coast and afai.clouds and update afai in place.

Optional Arguments

  • apply_coast: A Bool such that, if true, afai.afai is also updated to remove data on the coast. Default true.

source

Sargassum.pixel_classify! Function
julia
pixel_classify!(afai::AFAI; verbose::Bool = true)

Compute afai.classification and update afai in place.

This is accomplished in two steps. First, an Array of the same size and eltype of afai.afai is computed such that the value at each gridpoint is the median of all afai.afai values in a window of size afai.params.window_size_median_filter centered on that gridpoint. NaNs are ignored when calculating the median. If every value in the window is NaN, the value of afai_median is also NaN.

Then, the Sargassum-containing pixels are the entries of afai.afai - afai_median that are at least as large as afai.params.threshold_median.

Computing the median filter is parallelized but can take several minutes, hence the status is printed for each week. This can be turned off using the optional argument verbose.

source

Sargassum.pixel_unmix! Function
julia
pixel_unmix!(afai)

Update afai.afai in place such that the value at each gridpoint is the percentage coverage of Sargassum in that pixel. The coverage is only computed at the pixels given by afai.classification, and set to 0.0 elsewhere.

The coverage is computed as a linear interpolation between global maximum and minimum afai values provided by afai.params.afai_U0 and afai.params.afai_L0.

source

Sargassum.afai_to_distribution Function
julia
afai_to_distribution(file::String, params::AFAIParameters)

Compute a SargassumDistribution using the parameters params from the raw data file file.

source