From 1377a3209434e735844fc7c32dd95a85fc682a22 Mon Sep 17 00:00:00 2001 From: James Manton Date: Thu, 15 May 2014 11:27:37 +0100 Subject: [PATCH] Minor documentation improvements --- R/ReadIgorBinary.R | 64 +++++++++++++++++++---------------- R/ReadNclamp.R | 53 +++++++++++++++-------------- man/ReadAllNclampLogTables.Rd | 17 +++++----- man/ReadNclampLogTable.Rd | 8 ++--- man/SummariseSweepFile.Rd | 16 ++++----- man/SweepFilesToDataFrame.Rd | 8 ++--- man/UpdateSweepDataFrame.Rd | 20 +++++------ man/read.ibw.Rd | 26 +++++++------- man/read.pxp.Rd | 44 ++++++++++++------------ 9 files changed, 134 insertions(+), 122 deletions(-) diff --git a/R/ReadIgorBinary.R b/R/ReadIgorBinary.R index 8dc11e7..f370c80 100644 --- a/R/ReadIgorBinary.R +++ b/R/ReadIgorBinary.R @@ -54,14 +54,20 @@ # 2009-07-09 # Fixed handling of dates in ReadNclampLogTable -#' Read binary files in the Igor Binary Wave format (IBW) -#' @param wavefile Either a character vector containing the path to a file or an R \link{connection} -#' @param Verbose Whether to print status information while reading the file -#' @param ReturnTimeSeries Return as an R time series (package \code{\link{ts}}) -#' @param MakeWave Assign wave to a list in the global user environment -#' @param HeaderOnly Only return the header of the Igor Wave -#' @return returns a vector containing the wave data OR returns the name of a -#' new R vector containing the data which has been made in the user environment +#' Read binary files in the Igor Binary Wave format (IBW) +#' +#' @param wavefile either a character vector containing the path to a file or an +#' R \link{connection}. +#' @param Verbose if \code{TRUE}, print status information while reading the +#' file. +#' @param ReturnTimeSeries if \code{TRUE}, return as an R time series (package +#' \code{\link{ts}}). +#' @param MakeWave if \code{TRUE}, assign wave to a list in the global user +#' environment. +#' @param HeaderOnly if \code{TRUE}, only return the header of the Igor Wave. +#' @return A vector containing the wave data or, if \code{MakeWave == TRUE}, +#' returns the name of a new R vector containing the data which has been made +#' in the user environment #' @author jefferis #' @export #' @examples @@ -72,7 +78,6 @@ #' # make a list containing the wave's data in the users's environment #' wavename=read.ibw(system.file("igor","version5.ibw",package="IgorR"),MakeWave=TRUE) #' sum(get(wavename)) -#' read.ibw<-function(wavefile,Verbose=FALSE,ReturnTimeSeries=FALSE, MakeWave=FALSE,HeaderOnly=FALSE){ if (is.character(wavefile)) { @@ -117,32 +122,33 @@ read.ibw<-function(wavefile,Verbose=FALSE,ReturnTimeSeries=FALSE, #' Reads an Igor Pro Packed Experiment (.pxp) file #' -#' Note that pxp files are only partially documented so some contents cannot be +#' Note that PXP files are only partially documented so some contents cannot be #' parsed (e.g. image data). This function currently reads data records (Igor -#' waves and variables), history, procedures, recreation macros and plain text +#' waves and variables), history, procedures, recreation macros and plain text #' notebooks. Formatted notebooks cannot be read. #' #' \code{IgorPlatform} will determine in which encoding text is read #' (WINDOWS-1252 for windows and macintosh for macintosh). Unique abbreviations -#' are acceptable. Defaults to "windows" on windows, "macintosh" otherwise. Note -#' that Igor Pro 5.5 added a PlatformRecord to the pxp file format which is used -#' to determine the file's platform of origin when available. Since this is -#' informatino straight from the horse's mouth it will override the -#' \code{IgorPlatform} argument. -#' @param pxpfile Character vector naming a PXP file or an R \link{connection} -#' @param regex only read records (e.g. waves) in the pxp file whose names match -#' a \link{regex} -#' @param ReturnTimeSeries Igor waves are returned as a ts object with sensible -#' x scaling (FALSE by default) +#' are acceptable. Defaults to \code{"windows"} on Windows, \code{"macintosh"} +#' otherwise. Note that Igor Pro 5.5 added a PlatformRecord to the PXP file +#' format which is used to determine the file's platform of origin when +#' available. Since this is information straight from the horse's mouth it will +#' override the \code{IgorPlatform} argument. +#' @param pxpfile character vector naming a PXP file or an R \link{connection}. +#' @param regex if \code{TRUE}, only read records (e.g. waves) in the PXP file +#' whose names match a \link{regex}. +#' @param ReturnTimeSeries if \code{TRUE}, Igor waves are returned as a +#' \code{link{ts}} object with sensible x scaling (\code{FALSE} by default). #' @param Verbose whether to print information to console during loading -#' (numeric values are also allowed 0=none, 1=basic, 2=all) -#' @param StructureOnly TODO Only the structure of the pxp file for inspection -#' @param ExtractText Whether to extract procedures, recreation macros, history -#' and plain text notebooks (FALSE by default) -#' @param IgorPlatform OS on which Igor file was saved (windows or macintosh) -#' @param ... Optional parameters passed to \link{read.ibw} -#' @return A list containing all the individual waves or variables in the pxp -#' file +#' (numeric values are also allowed 0=none, 1=basic, 2=all). +#' @param StructureOnly (TODO) if \code{TRUE}, only the structure of the PXP +#' file for inspection. +#' @param ExtractText whether to extract procedures, recreation macros, history +#' and plain text notebooks (\code{FALSE} by default). +#' @param IgorPlatform OS on which Igor file was saved (windows or macintosh). +#' @param ... optional parameters passed to \link{read.ibw}. +#' @return A list containing all the individual waves or variables in the PXP +#' file. #' @author jefferis #' @export #' @import bitops diff --git a/R/ReadNclamp.R b/R/ReadNclamp.R index f1d2894..38f5120 100644 --- a/R/ReadNclamp.R +++ b/R/ReadNclamp.R @@ -6,9 +6,9 @@ #' log tables are special Igor .pxp files that contain only variables. #' Each entry corresponds to a single run of an Nclamp protocol, #' storing information like protocol name, run time etc. -#' @param f Path to the log file -#' @param Verbose Whether to print status information while reading the file -#' @return A dataframe containing a row for each acquisition protocol run +#' @param f path to the log file. +#' @param Verbose whether to print status information while reading the file. +#' @return A dataframe containing a row for each acquisition protocol run. #' @author jefferis #' @export ReadNclampLogTable<-function(f,Verbose=FALSE){ @@ -44,16 +44,17 @@ ReadNclampLogTable<-function(f,Verbose=FALSE){ d } -#' Read all Nclamp log tables from a directory into a list -#' @param logfiledir Path to directory containing log files (pxp files) -#' @param pattern Optional regular expression - see \code{\link{list.files}} -#' @param ... additional parameters for ReadNclampLogTable -#' @return named list containing one dataframe for each parsed log file +#' Read all Nclamp log tables from a directory into a list +#' +#' @param logfiledir path to directory containing log files (pxp files). +#' @param pattern optional regular expression -- see \code{\link{list.files}}. +#' @param ... additional parameters for \code{\link{ReadNclampLogTable}}. +#' @return A named list containing one dataframe for each parsed log file. #' @author jefferis #' @export #' @examples #' \dontrun{ -#' ReadAllNclampLogTables("/GD/projects/PhysiologyData/logs") +#' logfiles <- ReadAllNclampLogTables("/GD/projects/PhysiologyData/logs") #' str(logfiles) #' } ReadAllNclampLogTables<-function(logfiledir,pattern="_log[0-9]+[.]pxp$",...){ @@ -81,17 +82,18 @@ ReadAllNclampLogTables<-function(logfiledir,pattern="_log[0-9]+[.]pxp$",...){ #' Extract summary information from an Nclamp/Igor Sweep File #' #' e.g. for import into Physiology database -#' @param f path to an Nclamp/Igor pxp format sweep file -#' @param Verbose print details while parsing underlying pxp file -#' @return a list of about 25 fields summarising the sweep file +#' @param f path to an Nclamp/Igor PXP format sweep file. +#' @param Verbose if \code{TRUE}, print details while parsing underlying PXP +#' file. +#' @return A list of about 25 fields summarising the sweep file. #' @author jefferis #' @export #' @import tools #' @examples -#' l=SummariseSweepFile(system.file("igor","WedJul407c2_001.pxp",package="IgorR")) -#' cat("There are",l$NumWaves,"waves in the file each of total duration",l$StimWaveLength, -#' "ms and sample duration",l$StimSampleInterval,"ms \n") -SummariseSweepFile<-function(f,Verbose=F){ +#' l <- SummariseSweepFile(system.file("igor", "WedJul407c2_001.pxp", package="IgorR")) +#' cat("There are", l$NumWaves, "waves in the file each of total duration", l$StimWaveLength, +#' "ms and sample duration", l$StimSampleInterval, "ms \n") +SummariseSweepFile<-function(f,Verbose=FALSE){ s=read.pxp(f,Verbose=Verbose) fileinfo=file.info(f) @@ -120,9 +122,9 @@ SummariseSweepFile<-function(f,Verbose=F){ #' Summarise multiple sweep files into a single dataframe #' #' Note that this is still a little fragile if the lists produced by -#' SummariseSweepFile do not have consistent field names -#' @param ff paths to a set of sweep files -#' @return dataframe with rows for each sweep file +#' \code{\link{SummariseSweepFile}} do not have consistent field names. +#' @param ff paths to a set of sweep files. +#' @return A dataframe with rows for each sweep file. #' @author jefferis #' @seealso SummariseSweepFile #' @export @@ -137,13 +139,14 @@ SweepFilesToDataFrame<-function(ff){ do.call(rbind,lapply(ll,as.data.frame,stringsAsFactors=FALSE)) } -#' Update the csv file summarising the sweeps in an Nclamp data folder +#' Update the CSV file summarising the sweeps in an Nclamp data folder #' -#' @param folder Path to the folder -#' @param outfile Path to outfile (default: /path/to/datafolder/datafolder.csv) -#' @param action TODO update newer (default) or force update (not implemented) -#' @param DryRun Report which files would be processed, but do nothing -#' @return TRUE if something happened, FALSE otherwise +#' @param folder path to the folder. +#' @param outfile path to outfile (default: \code{/path/to/datafolder/datafolder.csv}). +#' @param action update newer (default) or force update (not yet implemented). +#' @param DryRun if \code{TRUE}, report which files would be processed, but do +#' nothing. +#' @return \code{TRUE} if something happened, \code{FALSE} otherwise. #' @author jefferis #' @export UpdateSweepDataFrame<-function(folder,outfile=NULL,action=c("update","force"),DryRun=FALSE){ diff --git a/man/ReadAllNclampLogTables.Rd b/man/ReadAllNclampLogTables.Rd index 5527aa7..07d1342 100644 --- a/man/ReadAllNclampLogTables.Rd +++ b/man/ReadAllNclampLogTables.Rd @@ -5,24 +5,25 @@ ReadAllNclampLogTables(logfiledir, pattern = "_log[0-9]+[.]pxp$", ...) } \arguments{ - \item{logfiledir}{Path to directory containing log files - (pxp files)} + \item{logfiledir}{path to directory containing log files + (pxp files).} - \item{pattern}{Optional regular expression - see - \code{\link{list.files}}} + \item{pattern}{optional regular expression -- see + \code{\link{list.files}}.} - \item{...}{additional parameters for ReadNclampLogTable} + \item{...}{additional parameters for + \code{\link{ReadNclampLogTable}}.} } \value{ -named list containing one dataframe for each parsed log -file +A named list containing one dataframe for each parsed log +file. } \description{ Read all Nclamp log tables from a directory into a list } \examples{ \dontrun{ -ReadAllNclampLogTables("/GD/projects/PhysiologyData/logs") +logfiles <- ReadAllNclampLogTables("/GD/projects/PhysiologyData/logs") str(logfiles) } } diff --git a/man/ReadNclampLogTable.Rd b/man/ReadNclampLogTable.Rd index f92fa97..9613c3f 100644 --- a/man/ReadNclampLogTable.Rd +++ b/man/ReadNclampLogTable.Rd @@ -5,14 +5,14 @@ ReadNclampLogTable(f, Verbose = FALSE) } \arguments{ - \item{f}{Path to the log file} + \item{f}{path to the log file.} - \item{Verbose}{Whether to print status information while - reading the file} + \item{Verbose}{whether to print status information while + reading the file.} } \value{ A dataframe containing a row for each acquisition protocol -run +run. } \description{ log tables are special Igor .pxp files that contain only diff --git a/man/SummariseSweepFile.Rd b/man/SummariseSweepFile.Rd index 887d6e7..2657572 100644 --- a/man/SummariseSweepFile.Rd +++ b/man/SummariseSweepFile.Rd @@ -2,24 +2,24 @@ \alias{SummariseSweepFile} \title{Extract summary information from an Nclamp/Igor Sweep File} \usage{ -SummariseSweepFile(f, Verbose = F) +SummariseSweepFile(f, Verbose = FALSE) } \arguments{ - \item{f}{path to an Nclamp/Igor pxp format sweep file} + \item{f}{path to an Nclamp/Igor PXP format sweep file.} - \item{Verbose}{print details while parsing underlying pxp - file} + \item{Verbose}{if \code{TRUE}, print details while + parsing underlying PXP file.} } \value{ -a list of about 25 fields summarising the sweep file +A list of about 25 fields summarising the sweep file. } \description{ e.g. for import into Physiology database } \examples{ -l=SummariseSweepFile(system.file("igor","WedJul407c2_001.pxp",package="IgorR")) -cat("There are",l$NumWaves,"waves in the file each of total duration",l$StimWaveLength, - "ms and sample duration",l$StimSampleInterval,"ms \\n") +l <- SummariseSweepFile(system.file("igor", "WedJul407c2_001.pxp", package="IgorR")) +cat("There are", l$NumWaves, "waves in the file each of total duration", l$StimWaveLength, + "ms and sample duration", l$StimSampleInterval, "ms \\n") } \author{ jefferis diff --git a/man/SweepFilesToDataFrame.Rd b/man/SweepFilesToDataFrame.Rd index 6b09adb..3955274 100644 --- a/man/SweepFilesToDataFrame.Rd +++ b/man/SweepFilesToDataFrame.Rd @@ -5,15 +5,15 @@ SweepFilesToDataFrame(ff) } \arguments{ - \item{ff}{paths to a set of sweep files} + \item{ff}{paths to a set of sweep files.} } \value{ -dataframe with rows for each sweep file +A dataframe with rows for each sweep file. } \description{ Note that this is still a little fragile if the lists -produced by SummariseSweepFile do not have consistent field -names +produced by \code{\link{SummariseSweepFile}} do not have +consistent field names. } \author{ jefferis diff --git a/man/UpdateSweepDataFrame.Rd b/man/UpdateSweepDataFrame.Rd index 21593f8..1a25707 100644 --- a/man/UpdateSweepDataFrame.Rd +++ b/man/UpdateSweepDataFrame.Rd @@ -1,27 +1,27 @@ \name{UpdateSweepDataFrame} \alias{UpdateSweepDataFrame} -\title{Update the csv file summarising the sweeps in an Nclamp data folder} +\title{Update the CSV file summarising the sweeps in an Nclamp data folder} \usage{ UpdateSweepDataFrame(folder, outfile = NULL, action = c("update", "force"), DryRun = FALSE) } \arguments{ - \item{folder}{Path to the folder} + \item{folder}{path to the folder.} - \item{outfile}{Path to outfile (default: - /path/to/datafolder/datafolder.csv)} + \item{outfile}{path to outfile (default: + \code{/path/to/datafolder/datafolder.csv}).} - \item{action}{TODO update newer (default) or force update - (not implemented)} + \item{action}{update newer (default) or force update (not + yet implemented).} - \item{DryRun}{Report which files would be processed, but - do nothing} + \item{DryRun}{if \code{TRUE}, report which files would be + processed, but do nothing.} } \value{ -TRUE if something happened, FALSE otherwise +\code{TRUE} if something happened, \code{FALSE} otherwise. } \description{ -Update the csv file summarising the sweeps in an Nclamp +Update the CSV file summarising the sweeps in an Nclamp data folder } \author{ diff --git a/man/read.ibw.Rd b/man/read.ibw.Rd index 452350d..f7f9737 100644 --- a/man/read.ibw.Rd +++ b/man/read.ibw.Rd @@ -6,25 +6,25 @@ read.ibw(wavefile, Verbose = FALSE, ReturnTimeSeries = FALSE, MakeWave = FALSE, HeaderOnly = FALSE) } \arguments{ - \item{wavefile}{Either a character vector containing the - path to a file or an R \link{connection}} + \item{wavefile}{either a character vector containing the + path to a file or an R \link{connection}.} - \item{Verbose}{Whether to print status information while - reading the file} + \item{Verbose}{if \code{TRUE}, print status information + while reading the file.} - \item{ReturnTimeSeries}{Return as an R time series - (package \code{\link{ts}})} + \item{ReturnTimeSeries}{if \code{TRUE}, return as an R + time series (package \code{\link{ts}}).} - \item{MakeWave}{Assign wave to a list in the global user - environment} + \item{MakeWave}{if \code{TRUE}, assign wave to a list in + the global user environment.} - \item{HeaderOnly}{Only return the header of the Igor - Wave} + \item{HeaderOnly}{if \code{TRUE}, only return the header + of the Igor Wave.} } \value{ -returns a vector containing the wave data OR returns the -name of a new R vector containing the data which has been -made in the user environment +A vector containing the wave data or, if \code{MakeWave == +TRUE}, returns the name of a new R vector containing the +data which has been made in the user environment } \description{ Read binary files in the Igor Binary Wave format (IBW) diff --git a/man/read.pxp.Rd b/man/read.pxp.Rd index e384c1d..c625fef 100644 --- a/man/read.pxp.Rd +++ b/man/read.pxp.Rd @@ -6,37 +6,39 @@ read.pxp(pxpfile, regex, ReturnTimeSeries = FALSE, Verbose = FALSE, StructureOnly = FALSE, ExtractText = FALSE, IgorPlatform = NULL, ...) } \arguments{ - \item{pxpfile}{Character vector naming a PXP file or an R - \link{connection}} + \item{pxpfile}{character vector naming a PXP file or an R + \link{connection}.} - \item{regex}{only read records (e.g. waves) in the pxp - file whose names match a \link{regex}} + \item{regex}{if \code{TRUE}, only read records (e.g. + waves) in the PXP file whose names match a \link{regex}.} - \item{ReturnTimeSeries}{Igor waves are returned as a ts - object with sensible x scaling (FALSE by default)} + \item{ReturnTimeSeries}{if \code{TRUE}, Igor waves are + returned as a \code{link{ts}} object with sensible x + scaling (\code{FALSE} by default).} \item{Verbose}{whether to print information to console during loading (numeric values are also allowed 0=none, - 1=basic, 2=all)} + 1=basic, 2=all).} - \item{StructureOnly}{TODO Only the structure of the pxp - file for inspection} + \item{StructureOnly}{(TODO) if \code{TRUE}, only the + structure of the PXP file for inspection.} - \item{ExtractText}{Whether to extract procedures, + \item{ExtractText}{whether to extract procedures, recreation macros, history and plain text notebooks - (FALSE by default)} + (\code{FALSE} by default).} \item{IgorPlatform}{OS on which Igor file was saved - (windows or macintosh)} + (windows or macintosh).} - \item{...}{Optional parameters passed to \link{read.ibw}} + \item{...}{optional parameters passed to + \link{read.ibw}.} } \value{ A list containing all the individual waves or variables in -the pxp file +the PXP file. } \description{ -Note that pxp files are only partially documented so some +Note that PXP files are only partially documented so some contents cannot be parsed (e.g. image data). This function currently reads data records (Igor waves and variables), history, procedures, recreation macros and plain text @@ -46,12 +48,12 @@ notebooks. Formatted notebooks cannot be read. \code{IgorPlatform} will determine in which encoding text is read (WINDOWS-1252 for windows and macintosh for macintosh). Unique abbreviations are acceptable. Defaults -to "windows" on windows, "macintosh" otherwise. Note that -Igor Pro 5.5 added a PlatformRecord to the pxp file format -which is used to determine the file's platform of origin -when available. Since this is informatino straight from the -horse's mouth it will override the \code{IgorPlatform} -argument. +to \code{"windows"} on Windows, \code{"macintosh"} +otherwise. Note that Igor Pro 5.5 added a PlatformRecord to +the PXP file format which is used to determine the file's +platform of origin when available. Since this is +information straight from the horse's mouth it will +override the \code{IgorPlatform} argument. } \examples{ r=read.pxp(system.file("igor","testexpt.pxp",package="IgorR"))