[pulseview.git] / manual / analysis.txt

== Data Analysis

Once you have acquired some measurement data, it's time to have a look and see what
insights you can gain from it. Usually, the first step is to look at the data as a
whole, achieved by clicking the _Zoom to Fit_ button:

image::pv_analysis.png[]

<1> Zoom-to-Fit button
<2> Zoom in/zoom out buttons
<3> Cursors
<4> Time scale (used to set up and show markers, see below)

If you have located an area of interest (maybe with the help of decoders, more about
that later), you can zoom in on it using the _zoom in_/_zoom out_ buttons, using the
scroll wheel of your mouse or the pinch/expand gestures on your touch panel.

[NOTE]
When a data capture is ongoing, the Zoom-to-Fit button stays active if you click it,
meaning that PulseView automatically fits all data to the views until either the
capture is finished or the Zoom-to-Fit button is clicked again.
If you want this feature but don't want to always have to click the button, you
can enable the "Always Zoom-to-Fit" option in the settings.

=== Cursors and Markers

Just looking at the signal data however is usually not sufficient. A lot of times,
you'll want to make sure that timings are honored and the bit times are like what
you'd expect. To do so, you'll want to use cursors and markers.

In the picture above, you can enable the cursor by clicking on the cursor button.
You can move both of its boundaries around by clicking on the blue flags in the
time scale area. The area between the two boundary lines shows the time distance
and its inverse (i.e. the frequency). If you can't see it, just zoom in until it
shows. You can also move both boundaries at the same time by dragging the label
where this information is shown.

image::pv_cursors_markers.png[]

<1> Cursors button, showing enabled state
<2> Cursor
<3> Marker

Markers are movable indicators that you can create wherever you like on the
time scale - just double-click on it and it'll create one for you where your
mouse cursor is at the time. You can click on its label and you'll have the
option to change its name, or drag it to reposition it.

[NOTE]
For timing comparison purposes, you can also enable a vertical marker line that
follows your mouse cursor: _Settings_ -> _Views_ -> _Highlight mouse cursor_

[NOTE]
There is also a special kind of marker that appears for each time the data
acquisition device has triggered. It cannot be moved and appears as a vertical
dashed line.

=== Special-Purpose Decoders

There are some decoders available that analyze the data instead of decoding it.
You can make use of them to examine various properties of the signals that are
of interest to you.

Their names are:

* Counter - counts pulses and/or groups of pulses (i.e. words)
* Guess bitrate - guesses the bitrate when using a serial protocol
* Jitter - determines the jitter (variance) of a signal
* Timing - shows the time passing between the chosen signal edges

=== Other Features

Trace Views also allow you to maximize the viewing area by minimizing the area
occupied by the label area on the left. To do this, simply position the mouse
cursor at the right edge of the label area (or left edge of the viewing area).
Your mouse cursor will change shape and you now can drag the border.

This way, you can give signals long, expressive names without clogging up the
view area.

Also, you can create multiple views by clicking on the "New View" button on
the very left of the toolbar. Those can be rearranged as you wish.
Commit	Line	Data
1894027b SA	1	== Data Analysis
	2
	3	Once you have acquired some measurement data, it's time to have a look and see what
	4	insights you can gain from it. Usually, the first step is to look at the data as a
	5	whole, achieved by clicking the _Zoom to Fit_ button:
	6
	7	image::pv_analysis.png[]
	8
	9	<1> Zoom-to-Fit button
	10	<2> Zoom in/zoom out buttons
	11	<3> Cursors
daeba21f	12	<4> Time scale (used to set up and show markers, see below)
1894027b SA	13
	14	If you have located an area of interest (maybe with the help of decoders, more about
	15	that later), you can zoom in on it using the _zoom in_/_zoom out_ buttons, using the
	16	scroll wheel of your mouse or the pinch/expand gestures on your touch panel.
	17
	18	[NOTE]
	19	When a data capture is ongoing, the Zoom-to-Fit button stays active if you click it,
	20	meaning that PulseView automatically fits all data to the views until either the
	21	capture is finished or the Zoom-to-Fit button is clicked again.
daeba21f SA	22	If you want this feature but don't want to always have to click the button, you
daeba21f SA	23	can enable the "Always Zoom-to-Fit" option in the settings.
1894027b	24
daeba21f	25	=== Cursors and Markers
1894027b SA	26
	27	Just looking at the signal data however is usually not sufficient. A lot of times,
	28	you'll want to make sure that timings are honored and the bit times are like what
daeba21f	29	you'd expect. To do so, you'll want to use cursors and markers.
1894027b SA	30
	31	In the picture above, you can enable the cursor by clicking on the cursor button.
	32	You can move both of its boundaries around by clicking on the blue flags in the
	33	time scale area. The area between the two boundary lines shows the time distance
	34	and its inverse (i.e. the frequency). If you can't see it, just zoom in until it
	35	shows. You can also move both boundaries at the same time by dragging the label
	36	where this information is shown.
	37
	38	image::pv_cursors_markers.png[]
	39
	40	<1> Cursors button, showing enabled state
	41	<2> Cursor
daeba21f	42	<3> Marker
1894027b	43
daeba21f	44	Markers are movable indicators that you can create wherever you like on the
1894027b SA	45	time scale - just double-click on it and it'll create one for you where your
1894027b SA	46	mouse cursor is at the time. You can click on its label and you'll have the
daeba21f	47	option to change its name, or drag it to reposition it.
1894027b SA	48
	49	[NOTE]
	50	For timing comparison purposes, you can also enable a vertical marker line that
	51	follows your mouse cursor: _Settings_ -> _Views_ -> _Highlight mouse cursor_
	52
	53	[NOTE]
daeba21f	54	There is also a special kind of marker that appears for each time the data
1894027b SA	55	acquisition device has triggered. It cannot be moved and appears as a vertical
	56	dashed line.
	57
	58	=== Special-Purpose Decoders
	59
	60	There are some decoders available that analyze the data instead of decoding it.
	61	You can make use of them to examine various properties of the signals that are
	62	of interest to you.
	63
	64	Their names are:
	65
	66	* Counter - counts pulses and/or groups of pulses (i.e. words)
	67	* Guess bitrate - guesses the bitrate when using a serial protocol
	68	* Jitter - determines the jitter (variance) of a signal
	69	* Timing - shows the time passing between the chosen signal edges
	70
daeba21f SA	71	=== Other Features
	72
	73	Trace Views also allow you to maximize the viewing area by minimizing the area
	74	occupied by the label area on the left. To do this, simply position the mouse
	75	cursor at the right edge of the label area (or left edge of the viewing area).
	76	Your mouse cursor will change shape and you now can drag the border.
	77
	78	This way, you can give signals long, expressive names without clogging up the
	79	view area.
	80
	81	Also, you can create multiple views by clicking on the "New View" button on
	82	the very left of the toolbar. Those can be rearranged as you wish.