create.tps: Convert landmark data from xlsx or csv to tps format

In aphanotus/borealis: Tools for reproducible geometric morphometric analysis

Convert landmark data from xlsx or csv to tps format

Description

Reformats coordinate positions from a csv or xlsx spreadsheet into the tps ("thin-plate spline") file format defined by Rohlf (2015).

Usage

create.tps(
  input.filename = NULL,
  output.filename = NULL,
  id.factors = NULL,
  separator = "__",
  include.scale = FALSE,
  invert.scale = FALSE,
  export.metadata = FALSE,
  specimen.number = NULL,
  landmark.number = NULL,
  include.header = TRUE
)

Arguments

input.filename	The file name to import.
output.filename	The file name to export.
id.factors	Metadata column names to be encoded in the specimen IDs.
separator	A character string to separate the terms used in the ID line.
include.scale	A logical value indicating whether or not the imported data includes a column with scale values.
invert.scale	A logical value indicating whether to invert the scale value.
export.metadata	A logical value indicating whether or not metadata should be exported to a separate file.
include.header	A logical value indicating whether to include a header in the TPS file containing data provenance. Setting the value to FALSE will produce a TPS file suitable for MorphoJ.

Details

The first row of the input file must provide column names. There must be columns headed "x" and "y", although these are not case-sensitive and can occur in any order. 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 id.factors will be added to the ID= line in the resulting tps file, separated by the character string in the separator parameter. create.tps is also compatible with 3D data (recognized by a column named "z"). However other borealis functions, including read.tps are not currently prepared to handle 3D coordinates.

If include.scale = TRUE, then you must have a column headed "scale" to be included as a SCALE= line for each specimen in the tps file.

The scale value can also be inverted, by setting invert.scale = TRUE. This may be useful, because readland.tps applies scale values by multiplication. 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 first invert the scaling factor before importing coordinate data. Replicate scale measurements for each specimen can be included in the scale column and will be averaged (mean). (The number of scale measurements must not exceed the number of landmarks.)

Each row must include X and Y coordinates for landmarks, in order. Each specimen should appear with a consecutive block of rows, with landmarks in the same order. The number of landmarks must be consistent for all specimens. Specimen metadata must appear on the first row for each specimen. (That is, on the row for landmark 1.)

By default, the number of specimens and landmarks 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 any information in other rows will be ignored.

The output.filename may be specified, or by default it will be the input filename with the addition of .YYMMDD.tps, where YYMMDD is the date.

If export.metadata = TRUE then a seperate output file will be created that contains only the metadata. All metadata will be included in this file.

Only the first sheet will be used from xlsx input files.

Source

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

References

Rohlf, FJ. 2015. The tps series of software. Hystrix 26, 9–12. (Link)

Klingenberg, CP. 2011. MorphoJ: an integrated software package for geometric morphometrics.. Molecular Ecology Resources 11, 353-357. (Link)

Examples

# As an example, an input CSV file might looks like this:
#
# specimen.ID , digitizer , treatment , stage , scale , sex , x   , y
# T330.5      , DRA       , control   , adult , 1.23  , f   , 320 , 453
#             ,           ,           ,       ,       ,     , 303 , 468
#             ,           ,           ,       ,       ,     , 289 , 447
# T330.6      , DRA       , control   , adult , 1.24  , m   , 319 , 490
#             ,           ,           ,       ,       ,     , 300 , 501
#             ,           ,           ,       ,       ,     , 294 , 480

create.tps(
  input.filename = "rawdata.csv",
  output.filename = "output.tps",
  id.factors = c('digitizer','treatment','stage','sex'),
  include.scale = TRUE )

# The file, output.tps, would be created below
#
# LM=3
# 320 453
# 303 468
# 289 447
# ID=T330_5__DRA__control__adult__f
# SCALE=1.23
#
# LM=3
# 319 490
# 300 501
# 294 480
# ID=T330_6__DRA__control__adult__m
# SCALE=1.24

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