;+ 
; NAME: 
; SWARM_PCP_CDF_WRITE
; 
; PURPOSE: 
; This routine writes the results of the patch identification algorithm, the plasma density gradient calculations, and the gradient drift instability calculations into a CDF file.
; 
; CALLING SEQUENCE: 
; swarm_pcp_cdf_write, probe, $
; 	backfilterlen, backfilterperc, forefilterlen, forefilterperc, output_dir, $
; 	PMININC, PMAXDIFF, PMINLEN, PMINMLAT, PGRADLEN, $
; 	juls, glats, glons, alts, $
; 	ndens, background, foreground, pcp_flag, te, $
; 	ndens_gradient, ndens_edge_gradient, ion_velocity, ion_edge_velocity, $
; 	gdi_growth_rate, error_gdi_growth_rate, gdi_edge_growth_rate, error_gdi_edge_growth_rate, $
; 	vi_vs_angle, $
; 	version, preliminary
;
; INPUTS:
; probe: The Swarm probe identifies, i.e., A, b, or C.
; backfilterlen: The length (in number of data points) of the percentile filter over which to calculate the background plasma density. At UiO, we use 551 points.
; backfilterperc: The percentile within the window of length backfilterlen which is defined a the background plasma density. At UiO, we use the 35th percentile.
; forefilterlen: The length (in number of data points) of the percentile filter over which to calculate the foreground plasma density. At UiO, we use 7 points.
; forefilterperc: The percentile within the window of length forefilterlen which is defined a the foreground plasma density. At UiO, we use the 50th percentile.
; output_dir: The directory into which to write the CDF files.
; PMININC: The minimum relative increase of the foreground above the background to qualify as a patch, defined in SWARM_PCP_FIND_PATCHES.
; PMAXDIFF: The percent density increase that marks the beginning and end of the patch edges, defined in SWARM_PCP_FIND_PATCHES.
; PMINLEN: The minimum number of points which make up the entire patch (including edges), defined in SWARM_PCP_FIND_PATCHES.
; PMINMLAT: The minimum geomagnetic latitude below which we do not expect patches, defined in SWARM_PCP_FIND_PATCHES.
; PGRADLEN: Set this to the same number of data points as used for the window with in SWARM_PCP_CALC_NGRAD.
; juls: The Julian dates (as provided by IDL's JULDAY function) of the data points from the EFI 
; data files. For n data point inside the file this is a vector of length n.
; glats: The geographic latitudes of the satellite, from the EFI data files. For n data point inside the file this is a vector of length n.
; glons: The geographic longitudes of the satellite, from the EFI data files. For n data point inside the file this is a vector of length n.
; alts: The altitudes of the satellite, from the EFI data files. For n data point inside the file this is a vector of length n.
; ndens: The plasma density provided by the Langmuir probe of the EFI, from the EFI data files.
; background: The background plasma density calculated through percentile filtering in SWARM_PCP_FIND_PATCHES.
; foreground: The foreground plasma density calculated through percentile filtering in SWARM_PCP_FIND_PATCHES.
; pcp_flag: The PCP flag returned by SWARM_PCP_FIND_PATCHES. Each plasma density measurement is associated with this value, indicating whether the particular measurement is part of a polar cap patch, or not. The function sets the value of this flag, if inside a patch, to 2; it is 0 otherwise.
; te: The electron temperature provided by the Langmuir probe of the EFI, from the EFI data files.
; ndens_gradient: The plasma density gradient calculated as the slope of a linear least-square fit to the (unfiltered) plasma density data in SWARM_PCP_CALC_NGRAD.
; ndens_edge_gradient: The plasma density gradient calculated as the slope of a linear least-square fit to the (unfiltered) plasma density data in SWARM_PCP_CALC_NGRAD. The window width over which the data is fitted is the length of the polar cap patch edge.
; ion_velocity: The absolute ion drift speed used to calculate the linear gradient drift instability growth rate, calculated as the mean over 27 data points in SWARM_PCP_CALC_GDI.
; ion_edge_velocity: The absolute ion drift speed used to calculate the linear gradient drift instability growth rate, calculated over the polar cap patch edges in SWARM_PCP_CALC_GDI.
; gdi_growth_rate: The linear gradient drift instability growth rate calculated by SWARM_PCP_CALC_GDI.
; error_gdi_growth_rate: The error estimate from Gaussian error propagation of the linear gradient drift instability growth rate calculated by SWARM_PCP_CALC_GDI.
; gdi_edge_growth_rate: The linear gradient drift instability growth rate, calculated over the polar cap patch edges calculated by SWARM_PCP_CALC_GDI.
; error_gdi_edge_growth_rate: The error estimate from Gaussian error propagation of the linear gradient drift instability growth rate, calculated over the polar cap patch edges calculated by SWARM_PCP_CALC_GDI.
; vi_vs_angle: The angle (in degree) between the ion drift velocity and the spacecraft velocity calculated by SWARM_PCP_CALC_GDI. This is used to distinguish between stable and unstable configurations.
; version: Version number of the output - is used to create the CDF filename.
; preliminary: Set this keyword to one to indicate that the results are based on the EFI preliminary dataset.
;
; OUTPUTS:
; None.
;
; OPTIONAL INPUTS:
; None.;
;
; OPTIONAL OUTPUTS:
; None.
;
; KEYWORD PARAMETERS:
; filename: Instead of creating a CDF file name according to ESA convention you can specify your own file name.
; 
; EXAMPLE:
; 	; Find patches
; 	pcp_flag = swarm_pcp_find_patches( mlats, ndens, 551, 35, 7, 50, $
; 		pcount=pcount, ps1idx=ps1idx, ps2idx=ps2idx, pe1idx=pe1idx, pe2idx=pe2idx, $
; 		background=background, foreground=foreground, $
; 		PMININC=PMININC, PMAXDIFF=PMAXDIFF, PMINLEN=PMINLEN, PMINMLAT=PMINMLAT )
; 
; 	; Calculate the density gradient
; 	swarm_pcp_calc_ngrad, juls, ndens, v_sc, glats, glons, alts, $
; 		ps1idx, ps2idx, pe1idx, pe2idx, $
; 		ndens_gradient=ndens_gradient, error_ndens_gradient=error_ndens_gradient, $
; 		ndens_edge_gradient=ndens_edge_gradient, error_ndens_edge_gradient=error_ndens_edge_gradient, $
; 		PGRADLEN=PGRADLEN
; 
; 	; Calculate the GDI growth rates
; 	swarm_pcp_calc_gdi, juls, v_sc, v_ion, ndens, ndens_gradient, error_ndens_gradient, $
; 		ndens_edge_gradient, error_ndens_edge_gradient, pcp_flag, $
; 		ps1idx, ps2idx, pe1idx, pe2idx, $
; 		ion_velocity=ion_velocity, ion_edge_velocity=ion_edge_velocity, $
; 		gdi_growth_rate=gdi_growth_rate, gdi_edge_growth_rate=gdi_edge_growth_rate, $
; 		error_gdi_growth_rate=error_gdi_growth_rate, error_gdi_edge_growth_rate=error_gdi_edge_growth_rate, $
; 		vi_vs_angle=vi_vs_angle, PGRADLEN=PGRADLEN
; 
; 	; write the CDF
; 	swarm_pcp_cdf_write, probe, 551, 35, 7, 50, output_dir, $
; 		PMININC, PMAXDIFF, PMINLEN, PMINMLAT, PGRADLEN, $
; 		juls, glats, glons, alts, $
; 		ndens, background, foreground, pcp_flag, te, $
; 		ndens_gradient, ndens_edge_gradient, ion_velocity, ion_edge_velocity, $
; 		gdi_growth_rate, error_gdi_growth_rate, gdi_edge_growth_rate, error_gdi_edge_growth_rate, $
; 		vi_vs_angle, $
; 		1, preliminary
; 
; COPYRIGHT:
; This file was developed as part of the Swarm + Innovation: Polar Cap Products project. 
; Please visit http://www.mn.uio.no/fysikk/english/research/projects/swarm/ for more information.
; PCP (Polar Cap Products) is a project funded by the European Space Agency 
; (Contract No. 4000114121/15/NL/MP) in the framework of the STSE (Support To Science Element) 
; Swarm + Innovation Program.
; If you have any questions, please contact Lasse Clausen (lasse.clausen@fys.uio.no) or Wojciech 
; Miloch (w.j.miloch@fys.uio.no).
;-
pro swarm_pcp_cdf_write, probe, $
	backfilterlen, backfilterperc, forefilterlen, forefilterperc, output_dir, $
	PMININC, PMAXDIFF, PMINLEN, PMINMLAT, PGRADLEN, $
	juls, glats, glons, alts, $
	ndens, background, foreground, pcp_flag, te, $
	ndens_gradient, ndens_edge_gradient, ion_velocity, ion_edge_velocity, $
	gdi_growth_rate, error_gdi_growth_rate, gdi_edge_growth_rate, error_gdi_edge_growth_rate, $
	vi_vs_angle, $
	version, preliminary, $
	filename=filename

	if ~file_test( output_dir, /directory ) then begin
		message, 'Output directory does not exist: '+output_dir, /info
		return
	endif
	if ~file_test( output_dir, /write ) then begin
		message, 'Output directory is not writable: '+output_dir, /info
		return
	endif

	; for file handling
	ps = path_sep()

	gdesc = 'This file contains the polar cap patch flag and the linear gradient drift instability growth rate' + $
		'derived from Swarm Langmuir probe and Thermal Ion Imager data. These data products were developed as part of the Swarm + Innovation: Polar Cap Products' + $
		' project. Please visit http://www.mn.uio.no/fysikk/english/research/projects/swarm/ for more information.'
	gfund = 'PCP (Polar Cap Products) is a project funded by the European Space Agency (Contract No. 4000114121/15/NL/MP)' + $
		' in the framework of the STSE (Support To Science Element) Swarm + Innovation Program.'
	gweb = 'http://www.mn.uio.no/fysikk/english/research/projects/swarm/'
	gcon = 'If you have any questions, please contact Lasse Clausen (lasse.clausen@fys.uio.no)' + $
		' or Wojciech Miloch (w.j.miloch@fys.uio.no).'
	gprelim_y = 'This data is BASED ON the PRELIMINARY DATASET realeased earlier during the Swarm mission.'
	gprelim_n = 'This data is BASED ON the OPERATIONAL DATASET.'

	nn = n_elements(juls)
	sdate = swarm_pcp_julday2string( juls[0L] )
	fdate = swarm_pcp_julday2string( juls[nn-1L] )
	strver = string(version,format='(I02)')

	caldat, juls, mo, dy, yr, hr, mn, se
	cdf_epoch, epoch, yr, mo, dy, hr, mn, floor(se), round( ( se mod 1. )*1000. ), /compute

	; SW_PREL_EFIA_LP_1B_20150817T000000_20150817T235959_0103.ZIP
	filename = output_dir + ps + $
		'SW_PREL_PCP'+strupcase(probe)+'_PATCH_2_'+sdate+'_'+fdate+'_01'+strver+'.cdf'

	message, 'Writing in '+filename, /info

	id = cdf_create( filename, /row_major, /single_file, clobber=1 )

	att_id = cdf_attcreate( id, 'gDesc', /global )
	cdf_attput, id, 'gDesc', 0, gdesc
	att_id = cdf_attcreate( id, 'gWebsite', /global )
	cdf_attput, id, 'gWebsite', 0, gweb
	att_id = cdf_attcreate( id, 'gFunding', /global )
	cdf_attput, id, 'gFunding', 0, gfund
	att_id = cdf_attcreate( id, 'gContact', /global )
	cdf_attput, id, 'gContact', 0, gcon
	att_id = cdf_attcreate( id, 'gPrelim', /global )
	if preliminary eq 0 then $
		cdf_attput, id, 'gPrelim', 0, gprelim_n $
	else $
		cdf_attput, id, 'gPrelim', 0, gprelim_y

	att_id = cdf_attcreate( id, 'vDesc', /variable )

	var_id = cdf_varcreate( id, 'PMININC', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'PMAXDIFF', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'PMINLEN', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'PMINMLAT', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'PGRADLEN', /cdf_int1, /zvariable )

	cdf_varput, id, 'PMININC', fix(PMININC)
	cdf_attput, id, 'vDesc', 'PMININC', $
		'Minimum relative increase of the foreground above the background to qualify as a patch. This value is typically 2.'

	cdf_varput, id, 'PMAXDIFF', fix(PMAXDIFF)
	cdf_attput, id, 'vDesc', 'PMAXDIFF', $
		'Percent density increase that marks the beginning and end of the patch edges. This value is typically 30.'

	cdf_varput, id, 'PMINLEN', fix(PMINLEN)
	cdf_attput, id, 'vDesc', 'PMINLEN', $
		'Minimum number of points during which the relative increase has to be higher than PINCMIN. This value is typically 15.'

	cdf_varput, id, 'PMINMLAT', fix(PMINMLAT)
	cdf_attput, id, 'vDesc', 'PMINMLAT', $
		'Minimum geomagnetic latitude below which we expect no patches. This value is typically 77.'

	cdf_varput, id, 'PGRADLEN', fix(PGRADLEN)
	cdf_attput, id, 'vDesc', 'PGRADLEN', $
		'Length (in points) over which the density gradients for the GDI growth rate are calculated. This value is typically 27.'

	var_id = cdf_varcreate( id, 'backfilterlen', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'backfilterperc', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'forefilterlen', /cdf_int1, /zvariable )
	var_id = cdf_varcreate( id, 'forefilterperc', /cdf_int1, /zvariable )

	cdf_varput, id, 'backfilterlen', backfilterlen
	cdf_attput, id, 'vDesc', 'backfilterlen', $
		'Length of the percentile filter used for the calculation of the background density, in points. This value is typically 551.'

	cdf_varput, id, 'backfilterperc', backfilterperc
	cdf_attput, id, 'vDesc', 'backfilterperc', $
		'Percentile to be used for the calculation of the background density (0-100). This value is typically 35.'

	cdf_varput, id, 'forefilterlen', forefilterlen
	cdf_attput, id, 'vDesc', 'forefilterlen', $
		'Length of the percentile filter used for the calculation of the foreground density, in points. This value is typically 7.'

	cdf_varput, id, 'forefilterperc', forefilterperc
	cdf_attput, id, 'vDesc', 'forefilterperc', $
		'Percentile to be used for the calculation of the foreground density (0-100). This value is typically 50.'

	var_id = cdf_varcreate( id, 'epoch', [1], /cdf_epoch, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'glats', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'glons', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'alts', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'ndens', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'background', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'foreground', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'pcp_flag', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'te', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )

	cdf_varput, id, 'epoch', epoch
	cdf_attput, id, 'vDesc', 'epoch', $
		'CDF epoch of the measurement, i.e., number of milliseconds since 01.01.0000 00:00.'

	cdf_varput, id, 'glats', glats
	cdf_attput, id, 'vDesc', 'glats', $
		'Geographic latitude of the satellite in degrees.'

	cdf_varput, id, 'glons', glons
	cdf_attput, id, 'vDesc', 'glons', $
		'Geographic longitude of the satellite in degrees.'

	cdf_varput, id, 'alts', alts + !re
	cdf_attput, id, 'vDesc', 'alts', $
		'Geocentric altitude of the satellite in km.'

	cdf_varput, id, 'ndens', ndens
	cdf_attput, id, 'vDesc', 'ndens', $
		'Plasma density, directly copied from the Langmuir probe files (in cm^(-3)).'

	cdf_varput, id, 'background', background
	cdf_attput, id, 'vDesc', 'background', $
		'Background density, as calculated from ndens using a percentile filter of backfilterlen length and' + $
		' backfilterperc as the percentile.'

	cdf_varput, id, 'foreground', foreground
	cdf_attput, id, 'vDesc', 'foreground', $
		'Foreground density, as calculated from ndens using a percentile filter of forefilterlen length and' + $
		' forefilterperc as the percentile.'

	cdf_varput, id, 'pcp_flag', pcp_flag
	cdf_attput, id, 'vDesc', 'pcp_flag', $
		'The polar cap patch flag: '+$
		' 0 if the plasma density measurement occurred OUTSIDE a polar cap patch.' + $
		' 1 if the plasma density measurement occurred at the LEADING edge of a polar cap patch.' + $
		' 2 if the plasma density measurement occurred INSIDE a polar cap patch proper.' + $
		' 3 if the plasma density measurement occurred at the TRAILING edge of a polar cap patch.' + $
		'When no ion drift data is available, the leading and trailing edges cannot be determined. ' + $
		'In this case the polar cap patch flag is set to 2 throughout the entire patch, i.e., on both edges and inside the patch proper.'

	cdf_varput, id, 'te', te
	cdf_attput, id, 'vDesc', 'te', $
		'Electron temperature, directly copied from the Langmuir probe files (in K).'

	var_id = cdf_varcreate( id, 'ndens_gradient', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'ndens_edge_gradient', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'ion_velocity', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'ion_edge_velocity', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'gdi_growth_rate', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'gdi_edge_growth_rate', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'error_gdi_growth_rate', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'error_gdi_edge_growth_rate', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	var_id = cdf_varcreate( id, 'vi_vs_angle', [1], /cdf_float, /zvariable, dim=nn, /rec_vary )
	
	cdf_varput, id, 'ndens_gradient', ndens_gradient
	cdf_attput, id, 'vDesc', 'ndens_gradient', $
		'Running electron density gradient calculated via linear regression over PGRADLEN data points. '+$
		'In units of m^(-3)/m.'

	cdf_varput, id, 'ndens_edge_gradient', ndens_edge_gradient
	cdf_attput, id, 'vDesc', 'ndens_edge_gradient', $
		'Linear electron density gradient calculated over the edges of a patch. In units of m^(-3)/m. '+$
		'This variable is non-zero only on the edges of polar cap patches.'

	cdf_varput, id, 'ion_velocity', ion_velocity
	cdf_attput, id, 'vDesc', 'ion_velocity', $
		'Absolute ion velocity from the Thermal Ion Imager averaged over PGRADLEN data points. '+$
		'In units of m/s.'

	cdf_varput, id, 'ion_edge_velocity', ion_edge_velocity
	cdf_attput, id, 'vDesc', 'ion_edge_velocity', $
		'Absolute ion velocity from the Thermal Ion Imager averaged over the edges of a patch. In units of m/s. '+$
		'This variable is non-zero only on the edges of polar cap patches.'

	cdf_varput, id, 'gdi_growth_rate', gdi_growth_rate
	cdf_attput, id, 'vDesc', 'gdi_growth_rate', $
		'Growth rate of the Gradient Drift Instability. In units of 1/s.'+$
		'This variable is non-zero only within polar cap patches.'

	cdf_varput, id, 'error_gdi_growth_rate', error_gdi_growth_rate
	cdf_attput, id, 'vDesc', 'error_gdi_growth_rate', $
		'Error estimate of the GDI growth rate, from Gaussian error propagation. In units of 1/s.'

	cdf_varput, id, 'gdi_edge_growth_rate', gdi_edge_growth_rate
	cdf_attput, id, 'vDesc', 'gdi_edge_growth_rate', $
		'Growth rate of the Gradient Drift Instability calculated from ndens_edge_gradient and ion_edge_velocity. '+$
		'In units of 1/s. This variable is non-zero only on the edges of polar cap patches.'

	cdf_varput, id, 'error_gdi_edge_growth_rate', error_gdi_edge_growth_rate
	cdf_attput, id, 'vDesc', 'error_gdi_edge_growth_rate', $
		'Error estimate of the GDI growth rate, from Gaussian error propagation. In units of 1/s.'

	cdf_varput, id, 'vi_vs_angle', vi_vs_angle
	cdf_attput, id, 'vDesc', 'vi_vs_angle', $
		'Angle (in degree) between the vector ion velocity from the Thermal Ion Imager and the spacecraft velocity. '+$
		'Both velocities have been component averaged over PGRADLEN data points. '+$
		'A value of vi_vs_angle around 0 degree indicates parallel velocities, vi_vs_angle around 180 degrees '+$
		'indicates anti-parallel velocities. In the case of parallel velocities, the first edge encountered by the '+$
		'satellite is the trailing edge. If the velocities are anti-parallel, the first edge is the leading edge.'

	cdf_close, id

end