Documentation Center

  • Trial Software
  • Product Updates

Manage Acquired Data

Analog Input Data Management Properties

At the core of any analog input application lies the data you acquire from a sensor and input into your computer for subsequent analysis. The role of the analog input subsystem is to convert analog data to digitized data that can be read by the computer.

After data is extracted from the engine, you can analyze it, save it to disk, etc. In addition to these two functions, there are several properties associated with managing acquired data. These properties are as follows:

Property Name

Description

SamplesAcquired

Indicate the number of samples acquired per channel.

SamplesAvailable

Indicate the number of samples available per channel in the data acquisition engine.

SamplesPerTrigger

Specify the number of samples to acquire for each channel group member for each trigger that occurs.

Preview Data

Before you extract and analyze acquired data, you might want to examine (preview) the data as it is being acquired. Previewing the data allows you to determine if the hardware is performing as expected and if your acquisition process is configured correctly. Once you are convinced that your system is in order, you might still want to monitor the data even as it is being analyzed or saved to disk.

Previewing data is managed with the peekdata function. For example, to preview the most recent 1000 samples acquired for the analog input object ai:

data = peekdata(ai,1000);

After start is issued, you can call peekdata. peekdata is a nonblocking function because it immediately returns control to MATLAB®. Therefore, samples might be missed or repeated.

When a peekdata call is processed, the most recent samples requested are immediately returned, but the data is not extracted from the engine. In other words, peekdata provides a "snapshot" of the most recent requested samples. This situation is illustrated below.

If another peekdata call is issued, then once again, only the most recent requested samples are returned. This situation is illustrated below.

Rules for Using peekdata

Using peekdata to preview data follows these rules:

  • You can call peekdata before a trigger executes. Therefore, peekdata is useful for previewing data before it is logged to the engine or a disk file.

  • In most cases, you will call peekdata while the device object is running. However, you can call peekdata once after the device object stops running.

  • If the specified number of preview samples is greater than the number of samples currently acquired, all available samples are returned with a warning message stating that the requested number of samples were not available.

Poll the Data Block

Under certain circumstances, you might want to poll the data block. Polling the data block is useful when calling peekdata because this function does not block execution control. For example, you can issue peekdata calls based on the number of samples acquired by polling the SamplesAcquired property.

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

You can run this example by typing daqdoc5_1 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object AI for a sound card. The available adaptors and hardware IDs are found with daqhwinfo.

    AI = analoginput('winsound');
    %AI = analoginput('nidaq','Dev1');
    %AI = analoginput('mcc',1);
  2. Add channels — Add one hardware channel to AI.

    addchannel(AI,1);
    %addchannel(AI,0); % For NI and MCC
  3. Configure property values — Define a 10 second acquisition, set up a plot, and store the plot handle and title handle in the variables P and T, respectively.

    duration = 10; % Ten second acquisition
    ActualRate = get(AI,'SampleRate');
    set(AI,'SamplesPerTrigger',duration*ActualRate)
    figure
    P = plot(zeros(1000,1));
    T = title([sprintf('Peekdata calls: '), num2str(0)]);
    xlabel('Samples'), axis([0 1000 -1 1]), grid on
  4. Acquire data — Start AI and update the display for each 1000 samples acquired by polling SamplesAcquired. The drawnow command forces the MATLAB workspace to update the plot. Because peekdata is used, all acquired data might not be displayed.

    start(AI)
    i = 1;
    while AI.SamplesAcquired < AI.SamplesPerTrigger
    	while AI.SamplesAcquired < 1000*i
    	end
    	data = peekdata(AI,1000);
    	set(P,'ydata',data);
    	set(T,'String',[sprintf('Peekdata calls: '),num2str(i)]);
    	drawnow
    	i = i + 1;
    end

    Make sure AI has stopped running before cleaning up the workspace.

    wait(AI,2)
  5. Clean up — When you no longer need AI, you should remove it from memory and from the MATLAB workspace.

    delete(AI)
    clear AI

As you run this example, you might not preview all 80,000 samples stored in the engine. This is because the engine might store data faster than it can be displayed, and peekdata does not guarantee that all requested samples are processed.

Extract Data from the Engine

Many data acquisition applications require that data is acquired at a fixed (often high) rate, and that the data is processed in some way immediately after it is collected. For example, you might want to perform an FFT on the acquired data and then save it to disk. When processing data, you must extract it from the engine.

When you set the LoggingMode property to Memory or Disk&Memory, then engine stores all the data in memory until you extract it with getdata.

If you do not extract this data, and the amount of data stored in memory reaches the limit for the data acquisition object (see daqmem(obj)), a DataMissed event occurs. At this point, the acquisition stops.

Data is extracted from the engine with the getdata function. For example, to extract 1000 samples for the analog input object ai:

data = getdata(ai,1000);

In addition to returning acquired data, getdata can return relative time, absolute time, and event information. As shown below, data is an m-by-n array containing acquired data where m is the number of samples and n is the number of channels.

getdata is considered a blocking function because it returns control to MATLAB only when the requested data is available. Therefore, samples are not missed or repeated. When a trigger executes, acquired data fills the engine. When a getdata call is processed, the requested samples are returned when the data is available, and then extracted from the engine.

As shown below, if a fraction of the data stored in the engine is extracted, then getdata always extracts the oldest data.

If another getdata call is issued, then once again, the oldest samples are extracted.

Rules for Using getdata

Using getdata to extract data stored in the engine follows these rules:

  • If the requested number of samples is greater than the samples to be acquired, then an error is returned.

  • If the requested data is not returned in the expected amount of time, an error is returned. The expected time to return data is given by the time it takes the engine to fill one data block plus the time specified by the Timeout property.

  • You can issue ^C (Ctrl+C) while getdata is blocking. This will not stop the acquisition but will return control to MATLAB.

  • The SamplesAcquired property keeps a running count of the total number of samples per channel that have been acquired.

  • The SamplesAvailable property tells you how many samples you can extract from the engine per channel.

Preview and Extract Data

Suppose you have a data acquisition application that is particularly time consuming. By previewing the data, you can ascertain whether the acquisition is proceeding as expected without acquiring all the data. If it is not, then you can abort the session and diagnose the problem. This example illustrates how you might use peekdata and getdata together in such an application.

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

You can run this example by typing daqdoc5_2 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object AI for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.

    AI = analoginput('winsound');
    %AI = analoginput('nidaq','Dev1');
    %AI = analoginput('mcc',1);
  2. Add channels — Add one hardware channel to AI.

    chan = addchannel(AI,1);
    %chan = addchannel(AI,0); % For NI and MCC
    
  3. Configure property values — Define a 10-second acquisition, set up the plot, and store the plot handle in the variable P. The amount of data to display is given by preview.

    duration = 10; % Ten second acquisition
    set(AI,'SampleRate',8000)
    ActualRate = get(AI,'SampleRate');
    set(AI,'SamplesPerTrigger',duration*ActualRate)
    preview = duration*ActualRate/100;
    subplot(211)
    P = plot(zeros(preview,1)); grid on
    title('Preview Data')
    xlabel('Samples')
    ylabel('Signal Level (Volts)')
  4. Acquire data — Start AI and update the display using peekdata every time an amount of data specified by preview is stored in the engine by polling SamplesAcquired. The drawnow command forces MATLAB to update the plot. After all data is acquired, it is extracted from the engine. Note that whenever peekdata is used, all acquired data might not be displayed.

    start(AI)
    while AI.SamplesAcquired < preview
    end
    while AI.SamplesAcquired < duration*ActualRate
       data = peekdata(AI,preview);
       set(P,'ydata',data)
       drawnow
    end

    Extract all the acquired data from the engine, and plot the data.

    wait(AI,duration+1)
    data = getdata(AI);
    subplot(212), plot(data), grid on
    title('All Acquired Data')
    xlabel('Samples')
    ylabel('Signal level (volts)')
  5. Clean up — When you no longer need AI, you should remove it from memory and from the MATLAB workspace.

    delete(AI)
    clear AI

The data is shown below.

Return Time Information

You can return relative time and absolute time information with the getdata function. Relative time is associated with the extracted data. Absolute time is associated with the first trigger executed.

Relative Time

To return data and relative time information for the analog input object ai:

[data,time] = getdata(ai);

time is an m-by-1 array of relative time values where m is the number of samples returned. time = 0 corresponds to the first sample logged by the data acquisition engine, and time is measured continuously until the acquisition is stopped.

The relationship between the samples acquired and the relative time for each sample is shown below for m samples and n channels.

Absolute Time

To return data, relative time information, and the absolute time of the first trigger for the analog input object ai:

[data,time,abstime] = getdata(ai);

The absolute time is returned using the MATLAB clock format.

[year month day hour minute seconds]

The absolute time from the getdata call is

abstime
abstime =
1.0e+003 *
    1.9990    0.0020    0.0190    0.0130    0.0260    0.0208

To convert the clock vector to a more convenient form:

t = fix(abstime);
sprintf('%d:%d:%d',t(4),t(5),t(6))
ans =
13:26:20

The absolute time of the first trigger is also recorded by the InitialTriggerTime property.

Note that absolute times are recorded by the EventLog property for each trigger executed. You can always find the absolute time associated with a data sample by adding its relative time to the absolute time of the associated trigger. Refer to Record and Retrieve Event Information for more information about returning absolute time information with the EventLog property.

Was this topic helpful?