;+
; NAME:
;	PlotPrep
; PURPOSE:
; CALLING SEQUENCE:
	FUNCTION PlotPrep, xin, yin, nvalid, $

		oplotx		= oplotx	 , $
		newyaxis	= newyaxis	 , $

		yaxis		= yaxis 	 , $
		xrange		= xrange	 , $
		yrange		= yrange	 , $
		ystyle		= ystyle	 , $
		ynozero		= ynozero	 , $
		ylog		= ylog		 , $
		changecolor	= changecolor, $
		ycolor		= ycolor	 , $
		silent		= silent	 , $
		_extra		= _extra	 , $

		; Output

		xpnt		= xpnt 		 , $
		ypnt		= ypnt 		 , $
		npnt		= npnt
; INPUTS:
;	xin			one-dimensional abcissa array
;				To plot a time axis (using TimeXAxis) xin must be
;				an array of time structures, or a string array that
;				is converted to time structures with TimeSet. 
;	yin			one-dimensional ordinate array
;				must have the same size as xin
;	nvalid		one-dimensional array identifying the array elements
;				to be plotted as:
;				- an array of indices e.g. [0,1,2,7,8,9,10]
;				- a boolean array (containing only values 0 or 1)
;					of same size as xin and yin, e.g. [1,1,1,0,0,0,0,1,1,1,1]
;				if nvalid is absent, all finite ordinate values are plotted
; OPTIONAL INPUT PARAMETERS:
;	/oplotx		if not set, then a new plot (with a new x-axis) is started)
;				(implicitly /newyaxis is set and yaxis=-1, i.e. a y-axis
;				will be drawn on the left)
;				if set, then the arrays are overplotted on a previous plot
;				(the keywords /newyaxis and yaxis=yaxis can be used to add
;				additional y axes, if necessary)
;	/newyaxis	adds a new yaxis
;				(if /oplotx is NOT set, then /newyaxis is assumed set)
;	yaxis=yaxis	controls the position of a new y axis; yaxis is used
;				only if /newaxis is set
;				yaxis=-1 : y-axis on left (default)
;				yaxis=0	 : y-axis on right
;				0<yaxis<1: y-axis is placed in the right margin
;					(if this is used then ymargin must be made big enough
;					to hold the extra y axis).
;
;	silent=silent
;				suppresses informational messages
; OUTPUTS:
;	Result		number of points to be plotted (= n_elements(npnt))
; OPTIONAL OUTPUT PARAMETERS:
;	xpnt		same as xin; may have been coverted to a time array
;	ypnt		same as yin
;	npnt		indices into xpnt,ypnt with valid ypnt values
; INCLUDE:
	@compile_opt.pro			; On error, return to caller
; COMMON BLOCKS:
	common TimeScale, torigin, trange, tunit, texact		; Set by TimeXAxis
; MODIFICATION HISTORY:
;	NOV-2010, Paul Hick (UCSD/CASS)
;		Extracted from PlotCurve
;-

InitVar, silent 	, 0
InitVar, ynozero	, /key
InitVar, ylog		, /key

InitVar, oplotx		, /key
InitVar, newyaxis	, /key

newyaxis OR= NOT oplotx

; torigin and tunit must be set by a previous call to TimeAxis
; (in common block TimeScale)

SWITCH 1 OF

; Plot a time axis

IsType(xin,/string): xin = TimeSet(xin)		; Notice fallthrough
IsTime(xin): BEGIN
	;IF NOT IsTime(torigin) THEN TimeXAxis, xin
	IF NOT oplotx THEN BEGIN
		InitVar, xrange, xin
		IF IsType(xrange,/string) THEN xrange = TimeSet(xrange)
		TimeXAxis, xrange, _extra=_extra
		oplotx   = 1
		newyaxis = 1
	ENDIF
	xpnt = TimeOp(/subtract, xin, torigin, tunit)
	ypnt = yin

	break
END

; Plot a normal axis (not a time axis)

ELSE: BEGIN
	xpnt = xin
	ypnt = yin

	break
END

ENDSWITCH

;IF NOT oplotx OR n_elements(yaxis) EQ 0 THEN yaxis=-1
InitVar, yaxis, -1

nx = n_elements(xpnt)

n = n_elements(nvalid)
IF n EQ 0 THEN BEGIN				; nvalid absent: plot finite fnc values
	npnt = where( finite(ypnt) NE 0, n)
ENDIF ELSE IF nvalid[0] EQ -1 THEN BEGIN; nvalid = -1: no valid points
	n = 0
ENDIF ELSE IF n EQ nx THEN BEGIN	; nvalid is boolean or nvalid=indgen(nx)
	npnt = nvalid
	m = where(npnt EQ indgen(nx),i)
	IF i NE nx THEN npnt = where(npnt EQ 1,n) ; it's a boolean array
ENDIF ELSE	$
	npnt = nvalid

IF silent LE 0 THEN message, /info, 'plotting'+strcompress(n)+' out of'+strcompress(nx)+' points'

IF NOT oplotx THEN BEGIN			; Draw new x-axis

	; Use full range for x-axis if there are not datapoints or /changecolor is set
	; Otherwise restrict to range of valid data points

	xp = (n EQ 0 or changecolor) ? xpnt : xpnt[npnt]
	plot, [xp], 0*[xp],		$
		/nodata,			$		; Do not plot any data
		ystyle = 4,			$		; Do not plot y axis
		xrange = xrange,	$
		_extra = _extra

ENDIF

IF newyaxis THEN BEGIN				; New y-axis   (always if /oplot NOT set)

	IF yaxis EQ -1 THEN	BEGIN		; First y-axis (always if /oplot NOT set)
		xp = !x.crange[0]			; Y-axis on left side with tickmarks pointing left
	ENDIF ELSE BEGIN
		xp = convert_coord(!x.crange[1],0.0,/data,/to_normal)
		xp = xp+yaxis*(1-xp)		; Y-axis on right with tickmarks pointing right
		xp = (convert_coord(xp,0.0,/normal,/to_data))[0]
	ENDELSE

	IF n EQ 0 THEN BEGIN			; No data

		IF yaxis EQ -1 THEN oplot, [xp,xp],!y.crange
									; Plot vertical line on left if y-axis on left
	ENDIF ELSE BEGIN

		IF n_elements(yrange) EQ 0 THEN BEGIN
			CASE changecolor OF
			0: BEGIN
				CASE min(ypnt[npnt])*max(ypnt[npnt]) LT 0 OR ynozero OR ylog OF
				0: yrange = [(min(ypnt[npnt]) LT 0)*min(ypnt[npnt]),(min(ypnt[npnt]) GE 0)*max(ypnt[npnt])]
				1: yrange = [min(ypnt[npnt]),max(ypnt[npnt])]
				ENDCASE
			END
			1: BEGIN
				CASE min(ypnt)*max(ypnt) LT 0 OR ynozero OF
				0: yrange = [(min(ypnt) LT 0)*min(ypnt),(min(ypnt) GE 0)*max(ypnt)]
				1: yrange = [min(ypnt),max(ypnt)]
				ENDCASE
			END
			ENDCASE
		ENDIF

		IF yrange[0] EQ yrange[1] THEN	$
			yrange += [-1,1]

		axis, xp,				$	; Plot y axis
			yaxis  = yaxis NE -1, $
			yrange = yrange		, $
			ynozero= ynozero	, $
			ystyle = ystyle		, $
			ylog   = ylog		, $
			/save				, $	; Save the y-scaling (needed to plot data points)
			color  = ycolor		, $
			_extra = _extra

	ENDELSE

	IF yaxis EQ -1 THEN BEGIN			; If y-axis on left is plotted, then plot vertical line on right
		!p.clip[2]++					; Fixes IDL - bug with clip window
		IF IsType(_extra,/structure) THEN IF (where(tag_names(_extra) EQ 'YTHICK'))[0] NE -1 THEN ythick = _extra.ythick
		;IF tag_exist(_extra,'ythick') THEN ythick = _extra.ythick
		oplot, !x.crange[1]*[1,1], ylog ? 10^!y.crange : !y.crange, _extra=_extra, thick=ythick
	ENDIF

ENDIF

RETURN, n  &  END