add more documentation for function

[hematthi]

EchelleInstruments.jl/src/expres/io.jl

Lines 127 to 174 in 98d5a94

	function read_data(f::FITS, metadata::Dict{Symbol,Any}; normalization::Symbol = :raw, use_excalibur::Bool = true, return_λ_obs::Bool=false, return_excalibur_mask::Bool = false)
	if return_λ_obs
	λ, λ_obs, spectrum, uncertainty = FITSIO.read(f["optimal"],"bary_wavelength"), FITSIO.read(f["optimal"],"wavelength"), FITSIO.read(f["optimal"],"spectrum"), FITSIO.read(f["optimal"],"uncertainty")
	else
	λ, spectrum, uncertainty = FITSIO.read(f["optimal"],"bary_wavelength"), FITSIO.read(f["optimal"],"spectrum"), FITSIO.read(f["optimal"],"uncertainty")
	end
	if use_excalibur
	# For pixels where a presumably more accurate wavelength is avaliable, overwrite it.
	excalibur_mask = haskey(metadata,:excalibur_mask) ? metadata[:excalibur_mask] : FITSIO.read(f["optimal"],"excalibur_mask")
	λ_excalibur = FITSIO.read(f["optimal"],"bary_excalibur")
	λ[excalibur_mask] .= λ_excalibur[excalibur_mask]
	if return_λ_obs
	λ_excalibur_obs = FITSIO.read(f["optimal"],"excalibur")
	λ_obs[excalibur_mask] .= λ_excalibur_obs[excalibur_mask]
	end
	end
	if normalization == :blaze
	flux = spectrum
	var = uncertainty.^2
	metadata[:normalization] = :blaze
	elseif normalization == :raw
	# Restore fluxes to include the blaze function and scale uncertainties appropriately
	blaze = haskey(metadata,:blaze) ? metadata[:blaze] : FITSIO.read(f["optimal"],"blaze")
	blaze_smoothed = smooth_blaze(blaze)
	flux = spectrum.*blaze_smoothed
	# Since EXPRES pipeline returns standard deviation rather than variance
	var = (uncertainty.*blaze_smoothed).^2
	metadata[:normalization] = :raw
	elseif normalization == :continuum
	#blaze = haskey(metadata,:blaze) ? metadata[:blaze] : FITSIO.read(f["optimal"],"blaze")
	#blaze_smoothed = smooth_blaze(blaze)
	continuum = haskey(metadata,:continuum) ? metadata[:continuum] : FITSIO.read(f["optimal"],"continuum")
	flux = spectrum./continuum
	var = (uncertainty./continuum).^2
	metadata[:normalization] = :continuum
	else
	@error "# Reading data directly with normalization " * string(normalization) * " is not implemented."
	end
	if return_λ_obs
	if return_excalibur_mask
	return Spectra2DExtended(λ, λ_obs, flux, var, EXPRES2D(), metadata=metadata), excalibur_mask
	else
	return Spectra2DExtended(λ, λ_obs, flux, var, EXPRES2D(), metadata=metadata)
	end
	else
	return Spectra2DBasic(λ, flux, var, EXPRES2D(), metadata=metadata)
	end
	end

It would be helpful to describe the optional parameters, and the outputs (especially since they can vary, e.g. with or without excalibur_mask)