writeFam: Export data to .fam

In pedFamilias: Import and Export 'Familias' Files

Export data to .fam

Description

This function produces a .fam file readable by the Familias software (Egeland et al., 2000), containing all input pedigrees, their marker data and mutation models. The option openFam = TRUE calls openFamilias() to open a fresh Familias session with the produced file loaded.

Usage

writeFam(
  ...,
  famfile = "ped.fam",
  params = NULL,
  dbOnly = FALSE,
  openFam = FALSE,
  FamiliasPath = NULL,
  verbose = TRUE
)

openFamilias(famfile = NULL, FamiliasPath = NULL, verbose = TRUE)

Arguments

...	For ordinary files, one or several pedigrees. Each argument should be either a single ped object or a list of such. If the pedigrees are unnamed, they are assigned names "Ped 1", "Ped 2", etc. For DVI files, a single list with entries pm, am and missing.
famfile	The name or path to the output file to be written. The extension ".fam" is added if missing.
params	A list of Familias parameters controlling database settings, dropout and other options. See Details.
dbOnly	A logical. If TRUE, no pedigree information is included; only the frequency database.
openFam	A logical. If TRUE, an attempt is made to open the produced .fam file in an external Familias session. Only available on Windows systems with a working Familias installation.
FamiliasPath	The path to the Familias executable. If empty, the following are tried in order: "Familias3.exe", "C:/Program Files (x86)/Familias3/Familias3.exe".
verbose	A logical, by default TRUE.

Details

Parameters

The params argument controls various Familias settings. Most entries below may be omitted, in which case suitable defaults are used. Single values are recycled over markers or individuals as appropriate. The params argument is broadly compatible with the params component produced by readFam() with includeParams = TRUE.

General parameters

• version: Familias version written to the file. Default: "3.4.1".

• dvi: Logical indicating whether to write a file for the Familias DVI module. Default: FALSE.

Database parameters

• dbName: Name of the marker database. Default: "unknown".

• dbSize: Database size for each marker. Default: 1000.

• maf: Minor allele frequency for each marker. Default: 0.

• theta: Theta/kinship/Fst correction. Default: 0.

• dropoutValue: Dropout probability for each marker. Default: 0.

• dropoutConsider: Logical vector indicating which pedigree members should be subject to dropout.

• dropout: Convenience alternative to dropoutConsider and dropoutValue; either a single dropout probability or a named vector identifying individuals with dropout. For DVI files dropout has a different meaning (see below).

DVI parameters

The following probabilities pertain only to Direct/Identity matching in the DVI module:

• dropout: Dropout probability. Default: 0.

• dropin: Dropin probability. Default: 0.

• typingError: Typing error probability. Default: 0.

DVI data

For DVI files, set params$dvi = TRUE and supply a single list with the following entries:

• pm: A list of singletons; the victim samples.

• am: A named list of reference families. Each must be a connected ped object, and have exactly one missing person.

• missing: A vector naming the missing persons.

To ensure that the input data has the correct format, we recommend writing DVI files through the wrapper dvir::writeFamDVI().

Value

The file name is returned invisibly.

References

Egeland et al. (2000). Beyond traditional paternity and identification cases. Selecting the most probable pedigree. Forensic Sci Int 110(1): 47-59.

See Also

readFam().

Examples

# Create pedigree with 2 markers
x = nuclearPed() |>
  addMarker(geno = c("2/2", "1/3", "2/3"), alleles = 1:3,
            afreq = c(.3,.3,.4), name = "M1")

# Write to .fam
tmp = writeFam(x, famfile = tempfile())

# Read back in
y = readFam(tmp)

stopifnot(identical(x, y))


### With stepwise mutation model
x2 = setMutmod(x, model = "stepwise",
               rate = list(male = 0.001, female = 0.002),
               range = 0.1, rate2 = 0.0001)

# Write and read
y2 = x2 |>
  writeFam(famfile = tempfile()) |>
  readFam()

stopifnot(identical(x2, y2))


### Read/write including detailed parameters
params = list(theta = 0.1, dbName = "myDB", dropout = c("3" = 0.01))
fam = writeFam(x2, famfile = tempfile(), params = params)

dat = readFam(fam, includeParams = TRUE)

# Pedigree is now in the `main` slot
stopifnot(identical(x2, dat$main))

# The `dropout` parameter is converted to (and is equivalent to):
dat$params$dropoutConsider
dat$params$dropoutValue


### Read/write frequency database

# Write database as fam file
dbfam = writeFam(x2, famfile = tempfile(), dbOnly = TRUE)

# Read back in: The result is a list of marker attributes
a = readFam(dbfam)

# Attach to a pedigree and write to a new file
z = singleton(1) |> setMarkers(locusAttributes = a)
dbfam2 = writeFam(z, famfile = tempfile(), dbOnly = TRUE)

stopifnot(identical(readLines(dbfam), readLines(dbfam2)))


### DVI file

pm = singleton("V1") |> addMarker(geno = "1/2", name = "M")

am = nuclearPed(children = "MP") |>
  addMarker(geno = c("1/1", "1/2", NA), name = "M")

x = list(pm = list(V1 = pm), am = list(F1 = am), missing = "MP")
writeFam(x, famfile = tempfile(fileext = ".fam"), params = list(dvi = TRUE))

pedFamilias documentation built on Nov. 12, 2026, 5:11 p.m.