read.mmm: Read in and convert linear multivariate morphometric data

In aphanotus/borealis: Tools for reproducible geometric morphometric analysis

Read in and convert linear multivariate morphometric data

Description

Reads in linear multivariate morphometric (MMM) data from a csv or xlsx file. (Only the first sheet will be used from xlsx input files.) The input spread sheet is assumed to be "long," in the sense that one column includes a list measurements made either by hand or in grpahics software such as ImageJ. This organization is typically a convenient for rapid data entry. The function reformats the multiple measurements into a traditional tabular format, with each measurement in a seperate column.

Usage

read.mmm(
  input.filename = NULL,
  output.filename = NULL,
  measurement.names = NULL,
  metadata.cols = NULL,
  measurement.col = NULL,
  apply.scale = FALSE,
  invert.scale = FALSE
)

Arguments

input.filename	The file name to import.
output.filename	The file name to export. Or if output.filename = TRUE, then it will be input.filename.YYMMDD.csv, where YYMMDD is the date.
metadata.cols	Metadata column names or numbers to be retained in the output table.
measurement.col	A string naming the column containing measurements. The function can make an educated guess at this, recognizing names like "Measurement", "distance" or "pixels".
apply.scale	A string naming the column containing scale values to multiple measurement values.
invert.scale	A logical value indicating whether to invert the scale value before applying it.

Details

There must be a column giving specimen IDs, using a name like "ID" or "specimen_IDs". Any other columns are optional and may be used to encode metadata. Columns named by metadata.cols will be retained, others will be ignored. All columns in the input file will be retained if metadata.cols = "all" .

If a column name is supplied to apply.scale, then it will be used to adjust measurement values. This is done by multiplyng the scaling factor by the measurement values. Typically this is appropriate when scale is recorded as unit distance (e.g. mm) per pixel. However, if scale is recorded in pixels per unit distance (e.g. pixels/mm) it will be appropriate to set invert.scale = TRUE, if which case, the scaling factor will be inverted before applyng it. (In other words, the scale value will be used to divide the measurement value.) This is anologous to the treatment of scale in readland.tps, which applies scale values by multiplication, and in create.tps, which allows the user to specify how to apply the scaling factor.

Each specimen should appear with a consequtive block of rows, with measurements in the same order. Each measurements must appear in a consistent order for all specimens. The number of measurements must be consistent for all specimens. Specimen metadata must appear on the first row for each specimen. (That is, on the row for measurement 1.)

By default, the number of specimens and measurements will be determined by the function. This will be done by using the number of cells in the specimen ID column with non-whitespace characters. It will be assumed that all other metadata appears in the same rows, and that any information in other rows will be ignored.

Value

Returns a list with several elements. x is a data frame with the measurements and metadata, each row correwsaponding to a specimen. measurement.number and specimen.number containing integer values. scaled is a logical flag for whether scaling has been applied to measurement values. If any specimens were missing a scale value, the the element specimens.missing.scale will be an ID-named index of those specimens. (These may want to be removed!) The element provenance is a list recording data provenance. If an output.filename is specified, then the data frame in x will be written to the file in csv or tsv format.

Source

Dave Angelini [e-mail] [aut, cre]

Examples

mmm.data <- read.mmm(
  input.filename = "raw.measurements.csv",
  output.filename = TRUE,
  metadata.cols = "all",
  apply.scale = TRUE,
  invert.scale = TRUE
)

names(mmm.data)

dim(mmm.data$x)
head(mmm.data$x)

mmm.data$scaled

mmm.data$missing.scale

cat(unlist(mmm.data$provenance))

aphanotus/borealis documentation built on Nov. 4, 2022, 8:44 p.m.