#169: Add support for complex numbers to CF
-----------------------------+------------------------------
Reporter: mikedixon | Owner: cf-conventions@…
Type: enhancement | Status: new
Priority: high | Milestone:
Component: cf-conventions | Version:
Resolution: | Keywords:
-----------------------------+------------------------------
Description changed by mikedixon:
Old description:
> As of CF 1.7, it appears that there is no specific support in CF for
> complex numbers.
>
> For radar analysis and research, complex numbers are used for both raw
> IQ (in-phase and quadrature) data, and for spectra and covariances.
>
> Therefore we are submitting a proposal for the addition of support for
> complex numbers.
>
> The full proposal is attached.
>
> The documents are maintained at:
>
> https://github.com/NCAR/CfRadial/tree/master/docs
New description:
== Motivation ==
The ongoing development of the CfRadial convention, aimed at representing
radar and lidar data in CF NetCDF, has highlighted the need to properly
represent complex numbers in CF.
The intention with this proposal is to obtain agreement on adopting a
complex number convention that (a) respects the CF approach, (b) satisfies
the requirements of the radar and lidar research community and (c) provide
a general solution so that complex numbers from any discipline can be
accurately and simply represented.
== The nature of complex numbers ==
A complex number can be expressed in the form P = X + iY, where X and Y
are real numbers, and i is the square root of -1. For the complex number P
= X + iY, X is called the real part, and Y is called the imaginary part.
Complex numbers can also be represented in a polar or exponential forms.
The relationship between the Cartesian form and the polar form is:
P = X + iY = R(cos(theta) + isin(theta))
where R is the distance from the origin to the point P, and theta is the
angle between the X axis and the line OP, measured counterclockwise.
== Representing complex numbers as 2 reals ==
The above discussion demonstrates that no matter which form you choose to
use, a complex number requires the storage of two real numbers, as well as
a clear description of which form you are using.
It seems reasonable to determine the form being used by inspecting
the units attribute.
== Use of complex numbers in radar data ==
At the most raw level, radars generate time series of I (in-phase) and Q
(quadrature) signals. These two signal components are considered to
comprise a complex number.
Additionally, the spectra of radar signals are stored as complex numbers.
Because of the very large dynamic range of radar signals (up to 10 orders
of magnitude), these complex numbers are often stored as power, in log
units, and phase, in degrees.
== Storing complex numbers in NetCDF ==
Because complex numbers must be represented by 2 real numbers, a complex
variable will have one extra dimension, of size 2.
We propose that this dimension should be the last of the dimensions used
for a variable – i.e. the 2 parts of the number are stored immediately one
after the other in the array.
So, for example, a radar variable holding complex data for an I/Q time
series could be represented as follows
{{{
time = 3000 ;
range = 996 ;
complex = 2;
float IQ(time, range, complex) ;
IQ:is_complex = “true” ;
IQ:long_name = "time_series_inphase_and_quadrature" ;
IQ:standard_name = "radar_time_series_inphase_and_quadrature" ;
IQ:units = "volt" ;
IQ:_FillValue = -9999F ;
IQ:coordinates = "time range" ;
}}}
== Attribute indicating variable is complex ==
As indicated in the example above, we propose that the string attribute:
{{{
is_complex = "true";
}}}
be attached to any variable that holds complex numbers.
== Units attribute for real/imaginary form ==
If the complex number is stored using real and imaginary parts, the units
of both parts will be the same.
This is true for the example above, where we have:
{{{
IQ:units = "volts";
}}}
== Units attribute for polar form ==
If the polar or exponential form is used, the units of the two parts will
not be the same.
We could use a single units string attribute, but make it comma-delimited
to separate the units for the 2 parts.
For example:
{{{
IQ:units = "dBm,degree";
}}}
Or we could have 2 separate units attributes:
For example:
{{{
IQ:units_first_part = "dBm";
IQ:units_second_part = "degree";
}}}
The full proposal is attached.
The documents are maintained at:
https://github.com/NCAR/CfRadial/tree/master/docs
--
--
Ticket URL: <https://cf-trac.llnl.gov/trac/ticket/169#comment:2>
CF Metadata <http://cf-convention.github.io/>
CF Metadata
