R/plot.HEKAseries.R

In tdanker/ephys2: Read, analyze and plot HEKA Patchmaster files

#' Plot a HEKAseries object (HEKA Patchmaster data).
#'
#' ylab is "nA", a zero line is plotted, cursors are displayed if given.
#' A subset of sweeps can be marked (coloured) to indicate that they are special (i.e. used for liquid period results analysis).
#' Sweeps can be ofsetted (waterfall effect). 
#' Data can be zeroed (give an x value to be used for zeroing). 
#' A fraction of the x scale can be displayed (xf0=.5, xf1=1 will plot the second half).
#'
#' @param sweeps select sweeps to plot
#' @param cursors a vector of x values indicating where to draw cursors as vertical dashed lines
#' @param cur.col a vector of colors for the cursors
#' @param pointskip  skip all but each nth point for faster plotting
#' @return nothing
#' @export
#' @examples
#' data(KVsweeps)
#' plot(KVsweeps)
#' plot(KVsweeps, cursors=c(0.01,0.03, 0.04), cur.col=c("red", "blue"))

plot.HEKAseries<-function(HekaDataList,
                      cursors=NULL,
                      cur.col="dark blue",
                      sweeps=1:ncol(as.matrix(HekaDataList$y)), #which sweeps to plot (default all)
                      skip=1, #will plot only each nth of *given* sweeps
                      pointskip=1, #will plot less points for speed
                      mark=NULL,  #indices of sweeps to be marked (colored), referring to all (not only plotted) sweeps (marked sweeps will be plotted in any case)
                      add=F,
                      mark.col="red",
                      main="Sweeps Plot",
                      yoffset=0, #for "waterfall effects"
                      xoffset=0, #for "waterfall effects"
                      ylab="",
                      xlab="seconds",
                      xf1=0, xf2=max(as.matrix(HekaDataList$x)),  #plot only a fraction of xAxis  !fixme does not work for xoffset is set!
                      sweeps.col=rep("grey20",ncol(as.matrix(HekaDataList$y))), #color vector for *all* sweeps, not only the plotted ones
                      col=NA,  #color vector for visble sweeps, (will override sweeps.col)
                      zero=NULL,  #a zeroing cursor (given as index)
                      axes=F,
                      scalebar=T,
                      grid=axes,
                      ...
){


  sweeps=sweeps[(1:(length(sweeps)/skip)*skip)]
  sweeps=c(sweeps, subset(mark, !mark %in% sweeps)) #if a marked trace is not in the collection of plotted sweeps, we add it
  sweeps.col<-rep(sweeps.col, length.out=ncol(as.matrix(HekaDataList$y))[1]) #make shure that there is a color for every sweep in the dataset

  if(is.na(col)){
    col=sweeps.col[sweeps]       #only if col is not given, color of visible sweeps is selected from col.sweeps
  }
  col<-rep(col, length.out=ncol(as.matrix(HekaDataList$y))) #make shure that there is a color for every sweep in the dataset
  #create the color vector for the selected sweeps


  #extract points and sweeps
  y=as.matrix(HekaDataList$y)
  x=as.matrix(HekaDataList$x)

  xmin<-0 #max(x[nrow(x)*xf1],0, na.rm=T)
  #xmax=x[nrow(x)*xf2]


  #cut out Xrange ("zoom in")
  if(!anyNA(c(xf1,xf2))){
    y=cutXrange(y,x,xf1,xf2)
    x=cutXrange(x,x,xf1,xf2)
  }

  if(class(xoffset)=="logical")
    if(xoffset==T)
      xoffset=max(x, na.rm=T)

  yoffsets<-(0:(NCOL(y)-1))*yoffset
  xoffsets<-(0:(NCOL(x)-1))*xoffset
  if(is.matrix(y)){
    y<-t(t(y)+yoffsets)
    x<-t(t(x)+xoffsets)
  }
  xmin=min(x)#!
  xmax=max(x)#!


  if(!is.null(zero)){
    y<-sweep(y,2,colMeans(y[zero,]))
  } #zero

  y<-as.matrix(y)
  x<-as.matrix(x)
  #make shure that we draw at least 20 points
  pointskip<-ceiling(min(pointskip,nrow(y)/200))
  #calulate the points to be plotted
  points<-(1:(nrow(y)/pointskip))*pointskip
  #extract points and sweeps
  #extract points and sweeps


    y_=as.matrix(y[,sweeps])
    x_=as.matrix(x[,sweeps])



  y=as.matrix(y[points,sweeps])
  x=as.matrix(x[points,sweeps])
  xoffsets<-xoffsets[sweeps]
  if(!is.null(HekaDataList$Y_unit))
    if(ylab==""){
      if(substr(HekaDataList$Y_unit[1],1,1)=="V"){
        ylab="mV"
      }else{
        ylab="nA"
      }
    }



  if (axes==F){
    ylab_<-ylab
    ylab=""
    xlab=""
    plotaxes=F
  }else{plotaxes=T}

  #matplot(x,y,type="l",lty=1,col=col,xlab=xlab,ylab=ylab,xlim=c(xmin,xmax), main=main, add=add, axes=plotaxes,...)
  matplot(x,y,type="l",lty=1,col=col,xlab=xlab,ylab=ylab,main=main, add=add, axes=plotaxes,...)
  if (!axes){
    if(scalebar)
      scaleBar(xUnit="s", yUnit=ylab_,...)
  }
  if(grid) grid()


  if(!is.null(mark)){
    try(
      matlines(x[,mark],y[,mark], col=mark.col)    #indexes for marked sweeps refer to the collection of all sweeps, not only the plotted ones
      #we _overplot_ the marked sweeps so that they lay on top.
    )
  }

  assign("actPlot.Cursors", cursors, pos = .GlobalEnv)
  abline(h=0,col="blue", lty=3)
  abline(v=cursors,col=cur.col, lty=3)

  #return infos for other plots
  invisible(list(xoffsets=xoffsets,y=y_))
}



# cut an xRange(zoom in horizontally) for a pair of x and y matrizes ( representing a set
# of 'sweeps')
cutXrange <- function(y, x, Xstart, Xend) {
  start <- findxIndex(x, Xstart)
  end <- findxIndex(x, Xend)
  y[start:end, ]
}

# robust finding of the index of a value in xData that is nearest to xValue)
findxIndex <- function(xData, xValue) {
  which.min(abs(xData - xValue))
}

findxRange <- function(xData, xValues) {
  findxIndex(xData, xValues[1]):findxIndex(xData, xValues[2])
}
findxRangeStartEnd <- function(xData, xValues) {
  c(findxIndex(xData, xValues[1]), findxIndex(xData, xValues[2]))
}