PLTS can import and export CITIfiles.
CITIfile is a standardized data format, used for exchanging data between different computers and instruments. CITIfile is an abbreviation for "Common Instrumentation Transfer and Interchange file".
This standard has been a group effort between instrument designers and designers of computer-aided design programs. As much as possible, CITIfile meets current needs for data transfer, and it was designed to be expandable so it can meet future needs.
CITIfile defines how the data inside an ASCII package is formatted. Since it is not tied to any particular disk or transfer format, it can be used with any operating system (BASIC, DOS, UNIX, etc.), with any disk format (LIF, DOS, HFS, etc.), or with any transfer mechanism (disk, LAN, GPIB, etc.).
By careful implementation of the standard, instruments and software packages using CITIfile are able to load and work with data created on another instrument or computer. It is possible, for example, for a network analyzer to directly load and display data measured on a scalar analyzer, or for a software package running on a computer to read data measured on the network analyzer.
Note: For many data processing applications, the S4P file may provide a more convenient format.
Data Formats
There are two main types of data formats: binary and ASCII. CITIfile uses the ASCII text format. While this format does take up more bytes of space than a binary format, ASCII data is a transportable, standard type of format which is supported by all operating systems. In addition, the ASCII format is accepted by most text editors. This allows files to be created, examined, and edited easily, making CITIfile easier to test and debug.
File and Operating System Formats
CITIfile was designed to be independent of the data storage mechanism, and therefore may be implemented for any file system. However transfer between file systems may sometimes be necessary. Any commercially available software that has the ability to transfer ASCII files between systems may be used to transfer CITIfile data.
This section will define the following terms: package, header, data array, keyword
A typical package is divided into two parts: The first part, the header, is made up of keywords and setup information. The second part, the data, usually consists of one or more arrays of data. Example 1 shows the basic structure of a CITIfile package:
Example 1, A CITIfile Package
The "header" part
CITIFILE A.01.00
NAME MEMORY
VAR FREQ MAG 3
DATA S RI
The "data" part
BEGIN
-3.54545E-2, -1.38601E-3
0.23491E-3, -1.39883QE-3
2.00382E-3, -1.40022E-3
END
When stored in a disk file there may be more than one CITIfile package.
The header section contains information about the data that will follow. It may also include information about the setup of the instrument that measured the data. For example, the header may include information such as:
CITIfile version number
Network analyzer model number
Firmware revision currently installed in the analyzer
Type of Data
Data Format
Measurement parameters
Start and stop frequencies
Number of sample points
The CITIfile header shown in Example 1 has just the bare minimum of information necessary; no instrument setup information was included.
An array is numeric data that is arranged with one data element per line. In the Smith chart and polar formats, the data is in real and imaginary pairs. In all other formats, the data is still in pairs, but the second term of the pair is 0E0. All information is true formatted data in the same format as on the analyzer display (dB, SWR, etc.).
A CITIfile package may contain more than one array of data. Arrays of data start after the BEGIN keyword, and the END keyword will follow the last data element in an array. A CITIfile package does not necessarily need to include data arrays; for instance, CITIfile could be used to store the current state of an instrument. In that case the keywords VAR, DATA, BEGIN, and END would not be required.
|
Keyword |
Explanation and Examples |
|---|---|
|
CITIFILE |
CITIFILE A.01.01 identifies the file as a CITIfile, and indicates the revision level of the file. The CITIfile keyword and revision code must precede any other keywords. The CITIfile keyword at the beginning of the package assures the device reading the file that the data that follows is in the CITIfile format. The revision number allows for future extensions of the CITIfile standard. The revision code shown here following the CITIfile keyword indicates that the machine writing this file is using the A.01.01 version of CITIfile as defined here. Any future extensions of CITIfile will increment the revision code. |
|
NAME |
NAME CAL_SET allows the current CITIfile "package" to be named. The name of the package should be a single word with no embedded spaces. A list of standard package names follows: |
|
Label |
Definition. |
|
RAW_DATA |
Uncorrected data. |
|
DATA |
Data that has been error corrected.When only a single data array exists, it should be named DATA. |
|
FORMATTED |
Corrected and formatted data. |
|
MEMORY |
Data trace stored for comparison purposes. |
|
CAL_SET |
Coefficients used for error correction. |
|
CAL_KIT |
Description of the standards used. |
|
DELAY_TABLE |
Delay coefficients for calibration. |
|
VAR |
VAR FREQ MAG 201 defines the name of the independent variable (FREQ), the format of values in a VAR_LIST_BEGIN table (MAG, if used), and the number of data points (201).Typical names for the independent variable are FREQ (in Hz), TIME (in seconds), and POWER (in dBm). For the VAR_LIST_BEGIN table, only the "MAG" format is supported at this point. # #NA POWER1 1.0E1 allows variables specific to a particular type of device to be defined. The pound sign (#) tells the device reading the file that the following variable is for a particular device. The "NA" shown here indicates that the information is for a Network Analyzer. This convention allows new devices to be defined without fear of conflict with keywords for previously defined devices. The device identifier (i.e. NA) may be any number of characters. |
|
SEG_LIST_BEGIN |
SEG_LIST_BEGIN indicates that a list of segments for the independent variable follow. Format for the segments is: [segment type] [start] [stop] [number of points]. The current implementation only supports a single segment. If there is more than one segment, the VAR_LIST_BEGIN construct is used. CITIfile revision A.01.00 supports only the SEG (linear segment) segment type. |
|
SEG_LIST_END |
SEG_LIST_END defines the end of a list of independent variable segments. |
|
VAR_LIST_BEGIN |
VAR_LIST_BEGIN indicates that a list of the values for the independent variable (declared in the VAR statement) follow. Only the MAG format is supported in revision A.01.00. |
|
VAR_LIST_END |
VAR_LIST_END defines the end of a list of values for the independent variable. |
|
DATA |
DATA S[1,1] RI defines the name of an array of data that will be read later in the current CITIfile package, and the format that the data will be in. Multiple arrays of data are supported by using standard array indexing. Versions A.01.00 and A.01.01 of CITIfile only support the RI (real and imaginary) format, and a maximum of two array indexes. Commonly used array names include the following: "S" for "S parameter" Example: S[2,1] "E" for "Error term" Example: E[1] "USER" for "User parameter" Example: USER[1] "VOLTAGE" Example: VOLTAGE[1] "VOLTAGE_RATIO" for a ratio of Example: VOLTAGE_RATIO[1,0] two voltages (A/R). |
|
CONSTANT |
CONSTANT [name] [value] allows for the recording of values which don't change when the independent variable changes. CONSTANTs are part of the main CITIfile definition. Users must not define their own CONSTANTs. Use the #KEYWORD device specification to create your own KEYWORD instead. The #NA device specification is an example of this. No constants were defined for revision A.01.00 of CITIfile. CITIfile revision A.01.01 defined the following constant: CONSTANT TIME [year] [month] [day] [hour] [min] [secs] |
The COMMENT statement is not absolutely required, but is highly recommended to aid readability.
The year should always be the full four digits ("1999" is correct, but "99" is not). This is to avoid problems with the year 2000, when the shortened version of the year will be "00."
The hour value should be in 24-hour "military" time.
When writing a CITIfile and the fractional seconds value is zero, then the "seconds" value may be printed either with or without a decimal point: either "47.0" or "47" would be acceptable. When reading a CITIfile, the seconds value should always be read as if it were a floating point number.
See other File and Print Operations topics