Variable naming conventions
All CReSIS Toolbox Development Guides
Contents |
Variable Names
Variables names to avoid
- Do not use variable names that are also function names or built-in variables (e.g. "i", "j", "line", "angle", "system")
Variable names which include multiple words should have an underscore between the words. For example, "all_data", "field_col".
Variable names should be descriptive, but as succinct as possible and should use the conventional name whenever possible.
CReSIS Toolbox General Names
Indexes
Use idx for any variable which will be used to indicate the index of an element in an array.
Specific examples:
- param_idx for the index into the params structure array
- lay_idx for the index of a list of layers
- fn_idx for the index of a list of filenames
Frames, Segments
Variable | Description |
---|---|
frm | Refers to the frame which a numeric number from 1 to 999. Larger numbers of frames in a segment are not currently supported due to the 3-digit limitation. |
frm_id | Refers to the numeric representation of the frame string (frm_str) without the underscores. |
frm_str | Refers to the frame string "YYYYMMDD_SS_FFF" (letters stand for year, month, day, segment, frame). |
seg | Refers to the segment which is a numeric number from 1 to 99. Larger numbers of segments in a day are not currently supported due to the 2-digit limitation. |
seg_str (aka day_seg) | Refers to the string "YYYYMMDD_SS" (letters stand for year, month, day, segment). |
seg_id | Refers to the numeric representation of the frame string day_seg without the underscores. May also refer to the OPS database segment ID. |
Filenames
Variable names for filenames should end with the string "fn" for filename. For each of the parts of the file path we use "_dir", "_name", and "_ext":
[param_fn_dir,param_fn_name,param_fn_ext] = fileparts(param_fn)
Standard examples:
- "echo_fn" is the echogram (e.g. CSARP_qlook) file filename.
- "gps_fn" is the gps file filename.
- "frames_fn" is the frames file filename.
- "lay_fn" is the layerdata (e.g. CSARP_layerData) file filename.
- "param_fn" is the parameter spreadsheet filename.
- "records_fn" is the records file filename.
CReSIS Toolbox Image, Waveform, Board, ADC Names
imgs: cell array of wf_adc_list's
img: index into the imgs cell array. Each cell entry contains an N by 2 waveform-adc pair table. Starts counting from 1 and is used in the filenames for a particular image.
imgs_list: list array of imgs's. imgs_idx: index into this array.
img_lists: Cell array of img_list's. img_lists_idx: index into this array.
img_list: List of image indices, img. Each entry in the img_list vector, should be an index into an imgs cell array. img_list_idx: index into this array.
wf_adc_list: There are two possible modes. The primary mode is used for everything except array.m and is an N by 2 array representing a waveform-adc pair list. The other mode is used only for multilooking subarrays in array.m. In this case, wf_adc_list is a cell array of wf_adc_list's that will be incoherently combined.
wf_adc: Index into a wf_adc_list
wf_adcs: List of indices into a wf_adc_list
wf: Waveform number. Starts counting from 1 and is used in the filenames for a particular waveform.
wfs: Structure with all the information to load and process a particular waveform. wfs(wf) contains the information for waveform "wf".
adc: Analog to digital converter number. Starts counting from 1 and is used in the filenames for a particular adc.
When data are loaded using an imgs structure, they would be stored as:
data{img}(bins,rlines,wf_adc)
where:
- length(data) = length(imgs)
- bins: range bins
- rlines: range lines
- size(data{img}) = size(imgs{img},1)
CReSIS Toolbox Signal Variable Names
Time Axis
- time: fast-time axis (sec). For radar, time 0 is the start of the transmit waveform in the toolbox. Typically a column vector.
time = t0 + (0:Nt-1).'*dt;
- t0: start time of time axis (sec)
- fs: sampling frequency (Hz)
- dt: fast-time sample spacing (sec) (read [math]\Delta t[/math]), dt = 1/fs
- Nt: number of fast-time samples
- dr: range bin in free space (read [math]\Delta r[/math]), (m)
- td: target delay (sec)
- T: range gate (sec)
- PRI: pulse repetition interval (sec)
Frequency Axis
freq = fc + df * (-floor(Nt/2):floor((Nt-1)/2)).'; % Places zero/DC frequency in the center (typical for plotting and sorting) freq = ifftshift(freq); % Places zero/DC frequency in bin 1 (typical for processing)
- fc: center frequency (Hz)
- freq: fast-time frequency axis (Hz). Typically a column vector.
- PRF: pulse repetition frequency (Hz)
Chirp Parameters
- f0: start frequency (Hz)
- f1: stop frequency (Hz)
- BW: bandwidth (Hz), BW = abs(f1-f0)
- Tpd: pulse duration (sec)
- alpha: chirp rate (Hz/sec), alpha = (f1-f0)/Tpd, negative alpha is a down-chirp
Along-track (x-coordinate), Doppler, and Wavenumber Axis
Variable | Description |
---|---|
along_track | along-track or x-coordinate (m) |
doppler | Doppler frequency (Hz) |
k | wavenumber for radar (k=[math]\lambda[/math] / (4*[math]\pi[/math])) |
kx | wavenumber domain of slow-time (along-track) axis. Typically a row vector. (rad/m) |
dkx | step size in wavenumber domain (rad/m) |
dx | step size in space (m) --> sometimes this is approximate because dx is only an approximation for non-uniformly sampled data |
dxt | step size in time (sec); the GPS_time or gps_time axis |
Nx | number of slow-time samples |
X | length of along-track axes (m), X = dx*Nx --> sometimes this is approximate because dx is only an approximation for non-uniformly sampled data |
Xt | duration of along-track axes (sec), Xt = dxt*Nx |
Array Processing
Variable | Description |
---|---|
Nc | Number of channels |
Nruns | Number of runs per simulation setup. |
Nsims | Number of simulation setups. |
sv_idx | Steering vector index (instances of doa_idx should be changed to sv_idx). |
Nsv | Number of steering vectors to beamform outputs for |
Nsrc | Number of sources |
CReSIS Toolbox Date and Time
Date or time (called "time stamps") are usually stored in the variable "gps_time". We store all time stamps in the ANSI-C standard. The ANSI-C standard is number of seconds since Jan 1, 1970. We use a double variable which means that we can represent older dates with negative numbers. This also means that these variables do not have the precision needed for precise fast-time manipulation because double (64 bit float) does not have the dynamic range to do this.
For a list of functions to convert, manipulate, and print gps_time, please see the GPS File Guide: Time conversions section.
Symbols
These are the standard nomenclature/symbols that we use for simulation, publication, and internal discussions. We recommend using these symbols always.
Array processing symbols
Symbol | Description |
---|---|
[math] q [/math] | Refers to the q^{th} source in a range-bin. [math] q\in{{1,2,...,Q}} [/math] |
[math] Q [/math] | Model order (i.e. number of sources/targets in a range bin) |
[math] Q_{max} [/math] | Maximum model order or number of sources/targets in a range bin. [math] 0 \leq Q \leq p-1 [/math] |
Nsv | Number of steering vectors in a grid |
[math] p [/math] | Refers to the p^{th} sensor in the array. [math] p\in{1,2,...,P} [/math] |
[math] P [/math] | Number of sensors/channels |
[math] M [/math] | Number of snapshots. Also known as multilooks in radar context. Represents the number of measurements available for array processing. |
k | k is used as a test parameter. It represents possible number of targets,[math] k \in \lbrace 0, 1, ..., Q\rbrace[/math]. NOTE: 𝑘 also used to refer to wavenumber. |
[math]\lambda[/math] | Wavelength |
L | Log-likelihood function. Dim: [math] Q \times 1 [/math] |
P(p,k,M) | Penalty. Dim: [math] Q \times 1 [/math] |
[math] \mathbf{x} [/math] | Measurement/observation vector. Dim: [math] P \times 1 [/math] |
[math] \mathbf{X} [/math] | Measurement/observation matrix. Dim: [math] P \times M [/math] |
[math] \mathbf{s} [/math] | Signal/backscatter vector. Dim: [math] Q \times 1 [/math] |
[math] \mathbf{S} [/math] | Signal/backscatter vector. Dim: [math] Q \times M [/math] |
[math] \mathbf{R_{xx}} [/math] | Data covariance matrix. [math]\mathbf{R_{xx}}[/math] is estimated as [math] \mathbf{R} = \dfrac{1}{M} \mathbf{X} \mathbf{X}^H [/math]. Dim: [math] P \times P[/math] |
[math] \mathbf{a} [/math] | Steering vector. Dim: [math] P \times 1 [/math] |
[math] \mathbf{A} [/math] | Steering matrix. Dim: [math] P \times Q [/math] |
[math] \mathbf{n} [/math] | Noise vector. Dim: [math] P \times 1 [/math] |
[math] \mathbf{N} [/math] | Noise matrix. Dim: [math] P \times M [/math] |
[math] \theta_q [/math] | Direction of arrival (DOA) of the q^{the} source/target |
[math] \pmb{\theta}=[\theta_1, ..., \theta_Q]^T [/math] | Direction of arrival (DOA) of all targets. Dim: [math] Q \times 1 [/math] |
[math] \hat{\theta_i} [/math] | Estimated direction of arrival (DOA) of the [math] i^{th} [/math] target (DoA) |
[math] \hat{\pmb{\theta}}=[\hat{\theta_1}, ..., \hat{\theta_Q}]^T [/math] | Estimated direction of arrival (DOA) of all targets. Dim: [math] Q \times 1 [/math] |
[math] \ell [/math] | Eigenvalue |
[math] v [/math] | Eigenvector |
[math] \mathbf{P}_{\mathbf{A}} [/math] | Projection matrix (projects on the subspace spanned by the steering vectors). Dime Dim: [math] P \times P [/math] |
[math] B [/math] | Bandwidth of received chirp |
[math] f_c [/math] | Center frequency of transmit chirp |
[math] f_0/f_1 [/math] | Start/stop frequency of transmit chirp |
[math] f_d [/math] | Doppler frequency |
[math] t_d [/math] | Time delay |
[math] \alpha [/math] | Chirp rate |
[math] f_s [/math] | Sampling frequency |
[math] W [/math] | Number of subbands for wideband array processing. |
SAR processing symbols
Symbol | Description |
---|---|
[math] \sigma_r [/math] | Range resolution |
[math] \sigma_x [/math] | Azimuth resolution |
[math] \sigma_g [/math] | Ground-range resolution |
[math] \delta [/math] | Slant range resolution |
[math] c [/math] | Speed of light |
[math] N_t [/math] | Number of fast-time samples in a complex SAR image (i.e. number of snapshots in the range dimension) |
[math] N_x [/math] | Number of along-track samples in a complex SAR image (i.e. number of snapshots in the azimuth dimension) |
H(f) | Frequency domain windowing used in pulse compression (typically Hanning) |
h | Flight height relative to the imaged surface. The radar position is the reference. For example, if h=1000 m, then the z axis of the targets is -1000 m. |
[math]R[/math] and [math]\mathbf{r}[/math] | Range to the target. R is the magnitude. r is the vector. R_0 is the range of closest approach. For the SAR cylindrical coordinate system, this is equivalent to the distance from the flight trajectory path (often denoted as [math]\rho[/math] in the regular cylindrical coordinate system). |
[math] [\hat{\mathbf{X}}_{FCS}, \hat{\mathbf{Y}}_{FCS}, \hat{\mathbf{Z}}_{FCS}] [/math] | Basis of the SAR coordinate system (called FCS or flight coordinate system in the toolbox), which is a right-hand coordinate system: +X points along the flight path, +Y points to the left, and +Z points up. Note that this coordinate system is not fixed, which means that each pixel in the SAR image may have its own coordinates based on its location. The cresis toolbox approximates this by allowing a coordinate system for each range line (but all range bins in that range line are forced to use the same measurement phase center and coordinate system). |