Import MiteMapTools data

This function import data from zip files generated by MiteMap software. It unzips all zip files in a folder, read the csv files and merge them with metadata if provided. It also compute some metrics such as speed and turning angle. By default, it also clean the data using filter_mitemap() with default parameters. See ?filter_mitemap() for other parameters or set clean to FALSE if you want raw data. By default the center of the arena is located at (0,0) with a diameter of 40mm and the source of the odor is located at c(-20 , 0).

If your zip files or metadata files have parenthesis and space in the name, you may want to use rename_files_with_number() function before using this function. The file name in the metadata must match the zip file name, but import_mitemap() integrate some options to handle parenthesis and space in the name of the files in the metadata.

Usage

import_mitemap(
  path_to_folder,
  path_to_metadata = NULL,
  format_metadata = "csv",
  clean = TRUE,
  delete_parenthesis = FALSE,
  replace_parenthesis = TRUE,
  delete_space = TRUE,
  csv_with_correction = FALSE,
  remove_csv_folder = TRUE,
  dec = ",",
  sep = ";",
  na_readxl = "NA",
  n_lag = 1,
  center_x = 0,
  center_y = 0,
  x_odor = -20,
  y_odor = 0,
  force = FALSE,
  return_with_logs = FALSE,
  compute_metrics = TRUE,
  file_name_column = "File_name",
  raw_data_name = "donnees_brutes",
  radius_CH = 23.175,
  verbose = TRUE,
  ...
)

Arguments

path_to_folder

Path to the folder with zip files containing csv and with one metadata files in the .xlsx format

path_to_metadata

Path to the csv file (or xlsx if format_metadata="xlsx"). If there is only one csv file set path_to_metadata="csv" (or "xlsx"). Need to be set using a complete path to csv file if this file is not in the folder or if their is multiple xlsx/csv files in the folder.

format_metadata

Either csv or xlsx. If set to NULL, no metadata is used.

clean

(logical, default TRUE) Do we clean the MiteMap result using filter_mitemap() function? See filter_mitemap() for additional parameters.

delete_parenthesis

(Logical, default FALSE) Do we delete parenthesis with a number inside in the name of the files in the metadata. Note that the name of the csv inside a zip file with a parenthesis do not have parenthesis into this name. Thus, we recommended to set TRUE at least in one of delete_parenthesis or replace_parenthesis parameter.

replace_parenthesis

(Logical, default TRUE) Replace abc_name(1) by abc_name_1 in the name of the files in the metadata.

delete_space

(Logical, default TRUE) Delete_space in the name of the files in the metadata.

csv_with_correction

(Logical, default FALSE) If TRUE an if present in the zip files, position files with correction (center and reduce to 0) are used.

remove_csv_folder

(Logical, default TRUE) If FALSE, the csv_folder is kept. May be useful for debugging.

dec

decimal for the csv metadata files.

sep

separator for the csv metadata files.

n_lag

(int, default 1) Number of time step to compute speed and turning angle. If n_lag=1 (default), speed and turning angle are computed between two consecutive time step (0.2s). If n_lag=2 speed and turning angle are computed between two time step before and two time step after.

center_x

(int, default 0) Center the value of x by additioning center_x mm to x.mm.

center_y

(int, default 0) Center the value of y by additioning center_y mm to y.mm.

x_odor

(int, default -20) The x position of the odor source.

y_odor

(int, default 0) The y position of the odor source.

force

Force overwriting the path to csv_folder

return_with_logs

(Logical, default FALSE). If TRUE, the returning object is a list of 4 elements containing useful information to explore unmatching name between file_names and metadata

compute_metrics

(Logical, default TRUE). Are metrics such as time_immobile, speed and turning angles are computed for each time step ?

file_name_column

Name for the column corresponding to the File_name.

raw_data_name

Name of the raw data file in the zip file. Default is "donnees_brutes" (sorry for the french name). If using code from https://github.com/LR69/MiteMap/tree/MiteMap.v6 no need to change this.

radius_CH

the radius of the circular half arena (in mm). Default is 23.175 to fit with the area of HH shape.

verbose

(logical, default TRUE). If TRUE, print additional information.

...

Other params for be passed on to filter_mitemap().

Value

If return_with_logs is FALSE (default), the return object is only the tibble called resulting_data. If return_with_logs is TRUE, it return a list of 4 elements:

• resulting_data: a (possibly huge) tibble with metadata information and position in x, y and time.

• files_not_in_csv: a list of files not present in csv filenames from zip files.

• files_not_in_metada: a list of files not funded in metadata.

• duplicate_file_name_in_metadata: a list of duplicated file names in metadata.

By default, the resulting_data slot is structured in 4 obligated columns + columns from the metadata file + the computed metrics if compute_metrics is TRUE.

• File_name

• X..t.s. - The time in second (position is recorded every 0.2s)

• x.mm. - The position in x (in mm)

• y.mm. - The position in y (in mm)

• Metadata columns

• Computed metrics

  • distance - distance between two consecutive time step (in mm)

  • speed_mm_s - speed between two consecutive time step (in mm/s)

Author

Adrien Taudière

Examples

mm_csv <- import_mitemap(
  system.file("extdata", "mitemap_example", package = "MiteMapTools"),
  file_name_column = "File (mite ID)", verbose = FALSE
)
dim(mm_csv)
#> [1] 70828    35
mm_csv$File_name |>
  unique() |>
  length()
#> [1] 50

mm_csv2 <- import_mitemap(
  system.file("extdata", "mitemap_example", package = "MiteMapTools"),
  file_name_column = "File (mite ID)", verbose = FALSE, return_with_logs = TRUE
)
mm_csv2$files_not_in_csv[1]
#> [1] "MM032020_10_24_22h23m12s"
length(mm_csv2$files_not_in_csv)
#> [1] 1390

mm_csv_unfiltered <- import_mitemap(
  system.file("extdata", "mitemap_example", package = "MiteMapTools"),
  file_name_column = "File (mite ID)", verbose = FALSE, clean = FALSE
)
dim(mm_csv_unfiltered)
#> [1] 76032    35
mm_csv_unfiltered$File_name |>
  unique() |>
  length()
#> [1] 53

mm_xlsx <- import_mitemap(
  system.file("extdata", "mitemap_example", package = "MiteMapTools"),
  format_metadata = "xlsx", verbose = FALSE
)

dim(mm_xlsx)
#> [1] 70828    35

mm_wo_metadata <- import_mitemap(
  system.file("extdata", "mitemap_example", package = "MiteMapTools"),
  format_metadata = NULL, verbose = FALSE
)

dim(mm_wo_metadata)
#> [1] 72257    16