rs_IDs {rabi}

Polynomial color coding scheme generator

Description

Creates color (or symbol) coding schemes used to mark and identify individual animals using polynomial oversampling based on Reed-Solomon error-correction codes. The codes are robust to an arbitrary number of color-slot erasures.

Usage

rs_IDs(total.length, redundancy, alphabet, available.colors = NULL)

Arguments

total.length

the number of unique positions to be marked on the animal. (This can be thought of as the total number of positions on which color bands or paint marks will be applied.) Note: Reed-Solomon coding requires the total length of the ID to be less than or equal to the value of alphabet.

redundancy

the number of erasures that can occur without disrupting surety of unique identification. This value determines how robust the scheme is to erasures.

alphabet

an integer representing the 'alphabet size.' This is the number of unique markings (think different paint colors, symbols, or varieties of bands) at your disposal. Note: Reed-Solomon coding requires this value to be a prime number. If a non-prime is entered, the function will automatically adjust it to the nearest previous prime.

available.colors

an optional list of strings that contains the names of the unique markings which compose the given 'alphabet' (e.g. "blue", "red", "yellow", etc.). If left blank, the mapping can be done at any later time using codes_to_colors. Additionally, the length of this list must match the 'alphabet size' given above.

Value

a list containing the maximum possible number of unique ID codes that fit the provided parameters.

Author(s)

Andrew Burchill, [e-mail]

References

For information on Reed-Solomon error correction. For information on polynomial oversampling.

Burchill, A. T., & Pavlic, T. P. (2019). Dude, where's my mark? Creating robust animal identification schemes informed by communication theory. Animal Behaviour, 154, 203-208. doi:10.1016/j.anbehav.2019.05.013

See Also

brute_IDs, tweaked_IDs, simple_IDs. See the vignette loosebirdtag for demonstrations and additional uses. Run exampleGUI for a more user-friendly Shiny GUI version of the function.

If an appropriate argument for available.colors is provided, each code will be a sequence of strings, otherwise, each code will be a sequence of numeric values.

Examples

total.length <- 6  #we have six positions to mark,
redundancy <- 2    #we want surety even with two erasures,
alphabet <- 5      #and we currently have five types of paint in stock

 #This gives a warning because rs_IDs() doesn't
 #allow 'total.length' to be larger than 'alphabet'
codes <- rs_IDs(total.length, redundancy, alphabet)
length(codes)

 #Now the output should be the same as above, but no warning is issued.
codes <- rs_IDs(total.length = 5, redundancy, alphabet)
length(codes)

 #Let's make those into human-readable color sequences
color.names <- c("blue","red","pink-striped-orange", "yellow", "green")
codes_to_colors(codes, color.names)