Set or return list of registered file formats that we can read

fileformats returns format names, a format definition list or a table of information about the formats that match the given filter conditions.

registerformat registers a format in the io registry

getformatreader gets the function to read a file

getformatwriter gets the function to write a file

fileformats(
  format = NULL,
  ext = NULL,
  read = NULL,
  write = NULL,
  class = NULL,
  rval = c("names", "info", "all")
)

registerformat(
  format = NULL,
  ext = format,
  read = NULL,
  write = NULL,
  magic = NULL,
  magiclen = NA_integer_,
  class = NULL
)

getformatreader(file, class = NULL)

getformatwriter(format = NULL, file = NULL, ext = NULL, class = NULL)

Arguments

format

Character vector naming the format

ext

Character vector of file extensions (including periods)

read, write

Functions to read and write this format

class

The S3 class for the format (character vector e.g. 'neuron')

rval

Character vector choosing what kind of return value fileformats will give.

magic

Function to test whether a file is of this format

magiclen

Optional integer specifying maximum number of bytes required from file header to determine file's type.

file

Path to a file

Value

• fileformats returns a character vector, matrix or list according to the value of rval.

• getformatreader returns a list. The reader can be accessed with $read and the format can be accessed by $format.

• getformatwriter returns a list. The writer can be accessed with $write.

Details

if a format argument is passed to fileformats it will be matched with partial string matching and iif a unique match exists that will be returned.

getformatreader starts by reading a set number of bytes from the start off the current file and then checks using file extension and magic functions to see if it can identify the file. Presently formats are in a queue in alphabetical order, dispatching on the first match.

getformatwriter output file

If getformatwriter is passed a file argument, it will be processed based on the registered fileformats information and the ext argument to give a final output path in the $file element of the returned list.

If ext='.someext' getformatwriter will use the specified extension to overwrite the default value returned by fileformats.

If ext=NULL, the default, and file='somefilename.someext' then file will be untouched and ext will be set to 'someext' (overriding the value returned by fileformats).

If file='somefile_without_extension' then the supplied or calculated extension will be appended to file.

If ext=NA then the input file name will not be touched (even if it has no extension at all).

Note that if ext=NULL or ext=NA, then only the specified format or, failing that, the file extension will be used to query the fileformats database for a match.

See write.neuron for code to make this discussion more concrete.

See also

write.neuron

Examples

# information about the currently registered file formats
fileformats(rval='info')
#>            format     class            ext  read write magic
#> 1  amiralandmarks landmarks .landmarkAscii  TRUE  TRUE  TRUE
#> 2  amiralandmarks landmarks   .landmarkBin  TRUE  TRUE  TRUE
#> 3  amiralandmarks landmarks            .am  TRUE  TRUE  TRUE
#> 4  amiralandmarks landmarks     .amiramesh  TRUE  TRUE  TRUE
#> 5       amiramesh      im3d            .am  TRUE  TRUE  TRUE
#> 6       amiramesh      im3d     .amiramesh  TRUE  TRUE  TRUE
#> 7   cmtklandmarks landmarks     .landmarks  TRUE  TRUE  TRUE
#> 8   fijilandmarks landmarks        .points  TRUE  TRUE  TRUE
#> 9      fijitraces    neuron        .traces  TRUE FALSE  TRUE
#> 10     fijitraces    neuron           .xml  TRUE FALSE  TRUE
#> 11      hxlineset    neuron            .am  TRUE  TRUE  TRUE
#> 12         hxskel    neuron            .am  TRUE  TRUE  TRUE
#> 13         hxsurf    hxsurf          .surf  TRUE  TRUE  TRUE
#> 14         hxsurf    hxsurf            .am  TRUE  TRUE  TRUE
#> 15         hxsurf    hxsurf     .amiramesh  TRUE  TRUE  TRUE
#> 16        neuroml    neuron           .xml  TRUE FALSE  TRUE
#> 17        neuroml    neuron           .nml  TRUE FALSE  TRUE
#> 18     neuron.obj    neuron           .obj  TRUE  TRUE FALSE
#> 19     neuron.ply    neuron           .ply  TRUE  TRUE  TRUE
#> 20           nrrd      im3d          .nrrd  TRUE  TRUE  TRUE
#> 21           nrrd      im3d          .nhdr  TRUE  TRUE  TRUE
#> 22             qs    neuron            .qs  TRUE  TRUE FALSE
#> 23            rds    neuron           .rds  TRUE  TRUE FALSE
#> 24           rdsb    neuron          .rdsb  TRUE  TRUE FALSE
#> 25            swc    neuron           .swc  TRUE  TRUE FALSE
#> 26          swcng    ngraph           .swc  TRUE FALSE FALSE
#> 27       vaa3draw      im3d           .v3d  TRUE FALSE  TRUE
#> 28       vaa3draw      im3d        .v3draw  TRUE FALSE  TRUE
#> 29            vtk    neuron           .vtk FALSE  TRUE FALSE
if (FALSE) {
registerformat("swc",read=read.swc,write=read.swc,magic=is.swc,magiclen=10,
  class='neuron')
}
swc=tempfile(fileext = '.swc')
write.neuron(Cell07PNs[[1]], swc)
stopifnot(isTRUE(getformatreader(swc)$format=='swc'))
unlink(swc)