# TODO: Add comment
# 
# Author: E.Korsching 11-2024
###############################################################################



#### small lines instead of e.g. point symbols


level.plot <- function(x, text=NULL, textcol=NULL, at=NULL, xlab="", ylab="",
		col="lightblue", width=1, pch=NULL, lty=1, lwd=1, cex=0.7, scex=1, tcex=1, adj=0.5, srt=0)
{
	# plot line symbols in a new or existing plot
	# x: a matrix, y values in rows, different samples per row
	# text: NULL  or  as many as row length,   textcol: color vector as long as 'text'
	# at: place 'text' at certain positions, joint view on 'text' 'textcol' 'at'
	# col: one or as many colors as rows
	# xlab,ylab: descriptions for x and y,  adj: label offset position,  srt: label rotation
	# width: length of line,   pch: symbol if NULL lty,   lty: line type   lwd: line size,
	# cex: size of symbols, scex: symbol size, tcex: text label size
	nr <- nrow(x)
	nc <- ncol(x)

	# define x positions if not given
	if(is.null(at)){
		at <- seq(1,nc)
		x.max <- nc + 0.5
	}else{
		x.max <- max(at) + 0.5
	}
	# customize y pch symbols
	if(!is.null(pch)){
		pch.len <- length(pch)
		if(pch.len>1 & pch.len<nr){ stop("\n error: you need a pch for each factor  or  one pch for all") }
		if(pch.len==1 & nr>1){ pch <- rep(pch[1],nr) }
	}
	# customize y lty values
	lty.len <- length(lty)
	if(lty.len>1 & lty.len<nr){ stop("\n error: you need a lty for each factor  or  one lty for all") }
	if(lty.len==1 & nr>1){ lty <- rep(lty[1],nr) }
	# customize y lwd values
	lwd.len <- length(lwd)
	if(lwd.len>1 & lwd.len<nr){ stop("\n error: you need a lwd for each factor  or  one lwd for all") }
	if(lwd.len==1 & nr>1){ lwd <- rep(lwd[1],nr) }
	# customize y color values
	col.len <- length(col)
	if(col.len>1 & col.len<nr){ stop("\n error: you need a color for each factor  or  one color for all") }
	if(col.len==1 & nr>1){ col <- rep(col[1],nr) }
	# customize x text labels
	if(is.null(text)){
		text.len <- 0
	}else{
		text.len <- length(text)
	}
	if(text.len!=0 & text.len<nc){ stop("\n error: you need a label for each factor or set text to NULL") }
	if(text.len==0){ text <- as.character(seq(1,nc)) }
	
	# plot per row
	yr <- range(x)
	y.min <- yr[2]/12
	plot(x=0, y=0, type="n", ylab="", xlab="", xlim=c(0.6,x.max), ylim=c(-y.min, yr[2]), axes=F, cex=cex)
	# factors
	for(i in 1:nr){	# per row
		# horizontal level elements
		k <- 1
		for(j in at){
			if(is.null(pch)){
				segments(x0=j-width/2, y0=x[i,k], x1=j+width/2, col=col[i], lty=lty[i], lwd=lwd[i])
			}else{
				if(is.na(pch[i])){
					segments(x0=j-width/2, y0=x[i,k], x1=j+width/2, col=col[i], lty=lty[i], lwd=lwd[i])
				}else{
					points(x=j,y=x[i,k], col=col[i], cex=scex)
				}
			}
			k <- k+1
		}
	}
	text(x=at, y=-(y.min/2), labels=text, col=textcol, cex=tcex, adj=adj, srt=srt)			# x axis labels
	axis( side=2, las=0, cex.axis=1.1, cex.lab=1.1 )
	title(xlab=xlab, ylab=ylab, line=0.8)
}

#level.plot(x=matrix(c(1,3,5,7,2,2,2,2,8,5,7,6),3,4,byrow=T),  text=NULL, at=NULL, xlab="X", ylab="Y",
#		col=c("lightblue","green","red"), width=0.7, pch=NULL, lty=c(1,2,3), lwd=c(2,4,2), cex=0.7, scex=1, tcex=1, adj=0.5, srt=0)
#
#level.plot(x=matrix(c(1,3,5,7,2,2,2,2,8,5,7,6),3,4,byrow=T), text=NULL, at=NULL, xlab="X", ylab="Y",
#		col=c("lightblue","green","red"), width=0.7, pch=c(NA,2,NA), lty=c(1,2,3), lwd=c(2,2,4), cex=0.7, scex=2, tcex=1, adj=0.5, srt=0)