Querying Measurement Results and Statistics
You can get a measurement result simply by sending a query and reading the results. For example, if you send the :MEASure:HORizontal:PWIDth? query, you could get the Pulse Width result 2.0199E-9, but what settings were used for that result?
Instance settings
Every measurement has instance settings that specify things like what waveform source the measurement is made on, what amount of data the measurement is made on (entire waveform, display, or region within the display), whether the measurement is made once per acquisition or multiple times per acquisition (which does not affect the current result but does affect statistic results), whether positive or negative edges or pulses are being measured, and so on.
For example, the :MEASure:HORizontal:PWIDth Pulse Width measurement has these commands for specifying the instance settings:
:MEASure:HORizontal:PWIDth:SOURce:MEASure:HORizontal:PWIDth:REGion:MEASure:HORizontal:PWIDth:OCCurrences:MEASure:HORizontal:PWIDth:PTYPe
When you send a measurement query and read the result, the result depends on the proper instance settings being set beforehand.
Installing measurements
Given a measurement's current instance settings, sending a measurement command will install the measurement into the oscilloscope's measurement Results table. For example, sending the :MEASure:HORizontal:PWIDth command will install the Pulse Width measurement using the current instance settings. This is just like adding a measurement using the front panel graphical user interface (GUI) with the instance settings selected in the Add Measurements dialog box.
Querying measurement statistics
The measurement Results table keeps statistics for installed measurements, like the Mean value, the Std Dev (standard deviation), the Minimum value, the Maximum value, and the measurement Count on which the statistics are based. You can query a measurement's statistics using the MEAN?, SDEViation?, MINimum?, MAXimum?, and COUNt? common measurement child queries. For example, for the Pulse Width measurement, you can use these common child queries:
:MEASure:HORizontal:PWIDth:MEAN?:MEASure:HORizontal:PWIDth:SDEViation?:MEASure:HORizontal:PWIDth:MINimum?:MEASure:HORizontal:PWIDth:MAXimum?:MEASure:HORizontal:PWIDth:COUNt?
When the same measurement is installed multiple times using different instance settings, which statistic results are returned by the common measurement child queries? Again, it depends on the latest instance settings. If no measurement in the Results table matches the latest instance settings, you get a settings conflict.
Just like the measurement query, common child query results depend on the proper instance settings being set beforehand.
Querying directly from the Results table
To save you from having to set up the proper instance settings before every measurement or statistics query, there are queries for getting results and statistics directly from the Results table.
To get all results from the Results table, use the :MEASure:RESults? query.
To get results from the individual measurement rows in the Results table, use these queries:
- :MEASure:LIST:ITEM{N}:COUNt?
- :MEASure:LIST:ITEM{N}:CURRent?
- :MEASure:LIST:ITEM{N}:MAXimum?
- :MEASure:LIST:ITEM{N}:MEAN?
- :MEASure:LIST:ITEM{N}:MINimum?
- :MEASure:LIST:ITEM{N}:SDEViation?
The ITEM{N} number identifies the Results table measurement row. The first measurement in the table is number "1" (not "0").
Keeping track of the measurement row number
When you install a measurement, you can use the LOCation? common child query to get its Results table row number. Keep in mind there are commands that affect the Results table:
- :MEASure:LIST:CLEar — Deletes all measurements from the table
- :MEASure:LIST:MOVE — Moves a measurement from one location to another (and reorders measurements between the locations)
- :MEASure:LIST:REMove — Deletes one measurement from the table (and reorders the measurements that follow)
- :MEASure:LIST:SELect — Selects the measurement to be annotated (does not affect measurement order)
Editing instance settings directly in the Results table
If you opt to set instance variables before using measurement queries or common child queries to get measurement or statistics results, note that there are commands for directly editing some instance settings of measurements in the Results table: