;+ 
; NAME: 
; SWARM_PCP_PROCESS
; 
; PURPOSE: 
; This is the high-level routine that takes Swarm EFI input, produces the PCP flag as well as
; the GDI growth rates and their errors, and saves the results in CDF format. Typically, this
; routine is called with one day of input data.
; 
; CALLING SEQUENCE: 
; swarm_pcp_process, probe, juls, glats, glons, alts, mlats, ndens, v_sc, v_ion, te, preliminary, output_dir
;
; INPUTS:
; probe: The Swarm probe identifies, i.e., A, b, or C.
; 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.
; mlats: The geomagnetic latitudes of the satellite. When run at UiO, we use the AACGM coordinates. 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. For n data point inside the file this is a vector of length n.
; v_sc: The spacecraft velocity, from the EFI data files. For n data point inside the file this is a vector of diminsion [n,3].
; v_ion: The ion drift velocity, from the EFI data files. For n data point inside the file this is a vector of diminsion [n,3].
; te: The electron temperature provided by the Langmuir probe of the EFI, from the EFI data files. For n data point inside the file this is a vector of length n.
; preliminary: A scalar value which, if non-zero, indicates that the EFI data is part of the preliminary data set.
; output_dir: A string containing the name of the directory into which the CDF files are written.
;
; OUTPUTS:
; None. 
;
; OPTIONAL INPUTS:
; None. 
;
; OPTIONAL OUTPUTS:
; None.
;
; KEYWORD PARAMETERS:
; pcount: Set this to a named variable that will upon completion contain the number of patches found within the data.
; ps1idx: Set this to a named variable that will upon completion contain an array of indices which mark the beginning of the first edge of all patches found. It 
; has a length of pcount. The times of the polar cap patch beginning are then juls[ps1idx].
; ps2idx: Set this to a named variable that will upon completion contain an array of indices which mark the beginning of the patch proper of all patches found. It 
; has a length of pcount. The times of the polar cap patch proper beginning are then juls[ps2idx].
; pe2idx: Set this to a named variable that will upon completion contain an array of indices which mark the end of the patch proper of all patches found. It 
; has a length of pcount. The times of the polar cap patch proper ending are then juls[pe2idx].
; pe1idx: Set this to a named variable that will upon completion contain an array of indices which mark the end of the second edge of all patches found. It 
; has a length of pcount. The times of the polar cap patch ending are then juls[pe1idx].
; 
; EXAMPLE:
; ; read the electric field data, i.e., the data from both the Thermal Ion Imager and the 
; ; Langmuir Probe
; swarm_efi_read, 20140924, 'A',	$
; 	juls=juls, glats=glats, glons=glons, alts=alts, $
; 	ndens=ndens, v_sc=v_sc, v_ion=v_ion, te=te, $
; 	preliminary=preliminary
; 
; ; convert goegraphic latitude to geomagnetic latitude
; mlats = swarm_pcp_convert_mlat( glats, glons, alts )
; 
; ; process data and write CDF output
; swarm_pcp_process, probe, juls, glats, glons, alts, mlats, ndens, v_sc, v_ion, te, preliminary, cdf_dir, $
; 	pcount=pcount, ps1idx=ps1idx, ps2idx=ps2idx, pe1idx=pe1idx, pe2idx=pe2idx
; 
; 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).
;-
;idldoc, root='/mn/fys-server-rp1/a2/lbnc/idl/pcp', out='/mn/fys-server-rp1/web/swarm/code/docs', format='idl', title='Swarm+Innovation: Polar Cap Products', subtitle='PCP IDL code documentation', footer='/mn/fys-server-rp1/a2/lbnc/idl/pcp/cpr.txt'
pro swarm_pcp_process, probe, juls, glats, glons, alts, mlats, ndens, v_sc, v_ion, te, preliminary, output_dir, $
		pcount=pcount, ps1idx=ps1idx, ps2idx=ps2idx, pe1idx=pe1idx, pe2idx=pe2idx

	; some error checking
	if n_params() ne 12 then begin
		message, 'Must provide PROBE, JULS, GLATS, GLONS, ALTS, MLATS, NDENS, V_SC, V_ION, TE, PRELIMINARY, and OUTPUT_DIR.', /info
		return
	endif

	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

	; 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, background, 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

end