Commit 2f12dcd43e980d485e840648b571f4b10aff90fb - minexpert2

Document the new signal-to-noise ratio enhancement functions. Filippo Rusconi (Uploading Debian Developer) 3 years ago

5 changed file(s) with 367 addition(s) and 209 deletion(s). Raw diff Collapse all Expand all

doc/user-manual/images/src/png/print-minexpert-dt-mz-colormap-widget-original-z-scale.png less more

Binary diff not shown

doc/user-manual/images/src/png/web-minexpert-dt-mz-colormap-widget-original-z-scale.png less more

Binary diff not shown

+232

-205

doc/user-manual/xml/graphical-user-interface.xml less more

409	409	<listitem xml:id="par_max-thread-count-preferences"
410	410	xreflabel="Preferences menu">
411	411
412		<para>
413
414		<menuchoice>
415		<guimenu>Preferences</guimenu>
416		<guimenuitem>Set max. thread count</guimenuitem>
417		</menuchoice>:
418
419		Set the maximum number of execution threads that mass
420		spectral integrations can use. Note that the program
421		starts to be really efficient with a number of threads at
422		least equal to 4 (see <xref
423		linkend="sec_integrations-using-multiple-threads"/>).
424
425		<tip>
426
427		<para>
	412	<para>
	413
	414	<menuchoice>
	415	<guimenu>Preferences</guimenu>
	416	<guimenuitem>Set max. thread count</guimenuitem>
	417	</menuchoice>:
	418
	419	Set the maximum number of execution threads that mass
	420	spectral integrations can use. Note that the program
	421	starts to be really efficient with a number of threads at
	422	least equal to 4 (see <xref
	423	linkend="sec_integrations-using-multiple-threads"/>).
	424
	425	<tip>
	426
	427	<para>
428	428
429	429	Do not mistake <quote>thread</quote> for
430	430	<quote>core</quote> or <quote>processor</quote>. When

458	458
459	459	</warning>
460	460
461		</para>
462
463		</listitem>
464
465		</itemizedlist>
466
467		</listitem>
468
469		<listitem>
470
471		<para>
472		<guimenu>Help</guimenu>
473		</para>
474		<para>
475
476		This menu's items show help about the program itself and also
477		about the Qt libraries that were used to build it. These informations
478		are essential in case the user wants to make a bug report.
479
480		</para>
481
482		</listitem>
483
484		</itemizedlist>
485
486		</sect1>
487
488
489		<sect1 xml:id="sec_loaded-ms-run-data-sets">
490
491		<title>The Loaded MS Run Data Sets</title>
492
493		<indexterm>
494
495		<primary>information</primary>
496
497		<secondary>dissemination</secondary>
498
499		<tertiary>oral</tertiary>
500
501		</indexterm>
502
503		<para>
504
505		Each time a new MS run data set is loaded from disk or from clipboard,
506		a corresponding <emphasis>MS run data set</emphasis> item is added to
507		the <guilabel>Open MS run data sets</guilabel> dialog window (see
508		<xref linkend="fig_minexpert-open-ms-run-data-sets-dlg"/>).
509
510		</para>
511
512
513		<figure xml:id="fig_minexpert-open-ms-run-data-sets-dlg">
514
515		<title>The open MS run data sets</title>
516
517		<mediaobject>
518
519		<imageobject role="fo"> <imagedata
520		fileref="print-minexpert-open-ms-run-data-sets-dlg.png" format="PNG"
521		scale="100"/> </imageobject>
522
523		<imageobject role="html"> <imagedata
524		fileref="web-minexpert-open-ms-run-data-sets-dlg.png" format="PNG"/>
525		</imageobject>
526
527		<caption>
528
529		<para>
530
531		Each time a new MS run data set is loaded, a corresponding item is
532		added to the list widget. The drop-down menu lists a number of actions
533		that can be performed with these items.
534
535		</para>
536
537
538		</caption>
539
540		</mediaobject>
541
542		</figure>
543
544		<para>
545
546		One of the most useful menu items available from the drop-down menu of <xref
547		linkend="fig_minexpert-open-ms-run-data-sets-dlg"/> is the <guimenuitem>Show
548		MS run data set table view</guimenuitem> item. That menu item triggers the
549		display of a window containing a table view, like in a spreadsheet, that shows
550		the data of each scan contained in the MS run data set loaded from file. This
551		window is described in the following section (see <xref
552		linkend="fig_minexpert-ms-run-data-set-table-view-wnd"/>).
553
554		</para>
555
556		</sect1>
557
558
559		<sect1 xml:id="sec_mass-spectral-data-listing-table-view">
560
561		<title>Mass Spectral Data Listing in a Table View</title>
562
563		<para>
564
565
566
567		From the <guilabel>Open MS run data sets</guilabel> dialog window, it is
568		possible to select one list widget item corresponding to the data set of
569		interest and select the <guimenuitem>Show MS run data set table
570		view</guimenuitem> menu item that opens the <guilabel>MS run data set table
571		view</guilabel> window shown in <xref
572		linkend="fig_minexpert-ms-run-data-set-table-view-wnd"/>.
573
574		</para>
575
576		<figure xml:id="fig_minexpert-ms-run-data-set-table-view-wnd">
577
578		<title>The table view-based scrutiny of one MS run data set</title>
579
580		<mediaobject>
581
582		<imageobject role="fo"> <imagedata
583		fileref="print-minexpert-ms-run-data-set-table-view-wnd.png" format="PNG"
584		scale="80"/> </imageobject>
585
586		<imageobject role="html"> <imagedata
587		fileref="web-minexpert-ms-run-data-set-table-view-wnd.png" format="PNG"/>
588		</imageobject>
589
590		<caption>
591
592		<para>
593
594		Each MS run data set might be scrutinized through the use of this table
595		view. Each filtering criterion has a number of data insertion modalities,
596		described in the text. In this example, the user has set a number of values
597		in the <guilabel>Filtering options</guilabel> group box but has not yet
598		executed the filtering, so the full mass spectral data set is listed in the
599		table view.
600
601		</para>
602
603
604		</caption>
605
606		</mediaobject>
	461	</para>
	462
	463	</listitem>
	464
	465	</itemizedlist>
	466
	467	</listitem>
	468
	469	<listitem>
	470
	471	<para>
	472	<guimenu>Help</guimenu>
	473	</para>
	474	<para>
	475
	476	This menu's items show help about the program itself and also
	477	about the Qt libraries that were used to build it. These informations
	478	are essential in case the user wants to make a bug report.
	479
	480	</para>
	481
	482	</listitem>
	483
	484	</itemizedlist>
	485
	486	</sect1>
	487
	488
	489	<sect1 xml:id="sec_loaded-ms-run-data-sets">
	490
	491	<title>The Loaded MS Run Data Sets</title>
	492
	493	<indexterm>
	494
	495	<primary>information</primary>
	496
	497	<secondary>dissemination</secondary>
	498
	499	<tertiary>oral</tertiary>
	500
	501	</indexterm>
	502
	503	<para>
	504
	505	Each time a new MS run data set is loaded from disk or from clipboard,
	506	a corresponding <emphasis>MS run data set</emphasis> item is added to
	507	the <guilabel>Open MS run data sets</guilabel> dialog window (see
	508	<xref linkend="fig_minexpert-open-ms-run-data-sets-dlg"/>).
	509
	510	</para>
	511
	512
	513	<figure xml:id="fig_minexpert-open-ms-run-data-sets-dlg">
	514
	515	<title>The open MS run data sets</title>
	516
	517	<mediaobject>
	518
	519	<imageobject role="fo"> <imagedata
	520	fileref="print-minexpert-open-ms-run-data-sets-dlg.png" format="PNG"
	521	scale="100"/> </imageobject>
	522
	523	<imageobject role="html"> <imagedata
	524	fileref="web-minexpert-open-ms-run-data-sets-dlg.png" format="PNG"/>
	525	</imageobject>
	526
	527	<caption>
	528
	529	<para>
	530
	531	Each time a new MS run data set is loaded, a corresponding item is
	532	added to the list widget. The drop-down menu lists a number of actions
	533	that can be performed with these items.
	534
	535	</para>
	536
	537
	538	</caption>
	539
	540	</mediaobject>
	541
	542	</figure>
	543
	544	<para>
	545
	546	One of the most useful menu items available from the drop-down menu of <xref
	547	linkend="fig_minexpert-open-ms-run-data-sets-dlg"/> is the <guimenuitem>Show
	548	MS run data set table view</guimenuitem> item. That menu item triggers the
	549	display of a window containing a table view, like in a spreadsheet, that shows
	550	the data of each scan contained in the MS run data set loaded from file. This
	551	window is described in the following section (see <xref
	552	linkend="fig_minexpert-ms-run-data-set-table-view-wnd"/>).
	553
	554	</para>
	555
	556	</sect1>
	557
	558
	559	<sect1 xml:id="sec_mass-spectral-data-listing-table-view">
	560
	561	<title>Mass Spectral Data Listing in a Table View</title>
	562
	563	<para>
	564
	565
	566
	567	From the <guilabel>Open MS run data sets</guilabel> dialog window, it is
	568	possible to select one list widget item corresponding to the data set of
	569	interest and select the <guimenuitem>Show MS run data set table
	570	view</guimenuitem> menu item that opens the <guilabel>MS run data set table
	571	view</guilabel> window shown in <xref
	572	linkend="fig_minexpert-ms-run-data-set-table-view-wnd"/>.
	573
	574	</para>
	575
	576	<figure xml:id="fig_minexpert-ms-run-data-set-table-view-wnd">
	577
	578	<title>The table view-based scrutiny of one MS run data set</title>
	579
	580	<mediaobject>
	581
	582	<imageobject role="fo"> <imagedata
	583	fileref="print-minexpert-ms-run-data-set-table-view-wnd.png" format="PNG"
	584	scale="80"/> </imageobject>
	585
	586	<imageobject role="html"> <imagedata
	587	fileref="web-minexpert-ms-run-data-set-table-view-wnd.png" format="PNG"/>
	588	</imageobject>
	589
	590	<caption>
	591
	592	<para>
	593
	594	Each MS run data set might be scrutinized through the use of this table
	595	view. Each filtering criterion has a number of data insertion modalities,
	596	described in the text. In this example, the user has set a number of values
	597	in the <guilabel>Filtering options</guilabel> group box but has not yet
	598	executed the filtering, so the full mass spectral data set is listed in the
	599	table view.
	600
	601	</para>
	602
	603
	604	</caption>
	605
	606	</mediaobject>
607	607
608	608	</figure>
609	609

1589	1589	fragmentation specification setting dialog window (<xref
1590	1590	linkend="fig_minexpert-ms-fragmentation-dlg"/> at <xref
1591	1591	linkend="sec_set-msn-fragmentation-parameters"/>).
1592
	1592
1593	1593	</para>
1594	1594
1595	1595	</listitem>

1977	1977	<para>
1978	1978
1979	1979	<guimenuitem>Set Z axis scale to log10</guimenuitem>: Recompute all
1980		the intensities by calculating thew intensity as the log10 of the
	1980	the intensities by calculating the new intensity as the log10 of the
1981	1981	original intensity.
1982	1982
1983	1983	</para>
1984	1984
	1985	<para>
	1986
	1987	When the log10 scale is applied to the intensities of the previous color
	1988	map plot, where almost no signal was visible, then the signal is made
	1989	perfectly visible."
	1990
	1991	</para>
	1992
	1993	<figure xml:id="fig_minexpert-dt-mz-colormap-widget-log10-z-scale">
	1994
	1995	<title>Color map plot widget main menu</title>
	1996
	1997	<mediaobject>
	1998
	1999	<imageobject role="fo">
	2000	<imagedata fileref="print-minexpert-dt-mz-colormap-widget-log10-z-scale.png" format="PNG" scale="50"/>
	2001	</imageobject>
	2002	<imageobject role="html">
	2003	<imagedata fileref="web-minexpert-dt-mz-colormap-widget-log10-z-scale.png" format="PNG" scale="50"/>
	2004	</imageobject>
	2005
	2006	<caption>
	2007
	2008	<para>
	2009
	2010	The switch to a log10 scale for the intensities might reveal a
	2011	lot of missing signal when the intensities are used in a linear
	2012	scale. The drawback is that noise can be hugely enhanced. See
	2013	below for a way to reduce that noise.
	2014
	2015	</para>
	2016
	2017
	2018	</caption>
	2019
	2020	</mediaobject>
	2021
	2022	</figure>
	2023
	2024
1985	2025	</listitem>
1986	2026
1987	2027	<listitem>
1988	2028
1989	2029	<para>
1990	2030
1991		<guimenuitem>Reset Z axis scale to original</guimenuitem>: Reset the
1992		intensities of the color map to the original values that the color map
1993		had when it was first created. </para>
	2031	<guimenuitem>Low pass-filter Z axis data</guimenuitem>: The value that
	2032	is entered in the spin box widget is a <emphasis>percentage</emphasis>
	2033	of the maximum intensity over the whole map. The function first
	2034	computes a threshold using the formula
	2035	threshold = percentage * max_int / 100.
	2036	All the cells having an intensity value above that threshold have
	2037	their value set to that threshold value. All other cells are
	2038	unchanged. This function is used to reduce the dynamic range of the
	2039	map and potentially enhance features of interest.
	2040
	2041	</para>
1994	2042
1995	2043	</listitem>
1996	2044
	2045	<listitem>
	2046
	2047	<para>
	2048
	2049	<guimenuitem>High pass-filter Z axis data</guimenuitem>: The value
	2050	that is entered in the spin box widget is a
	2051	<emphasis>percentage</emphasis> of the maximum intensity over the
	2052	whole map. The function first computes a threshold using the formula
	2053	threshold = percentage * max_int / 100.
	2054	All the cells having an intensity value below that threshold have
	2055	their value set to that threshold value. All other cells are
	2056	unchanged. This function is typically used for removing noise.
	2057
	2058	</para>
	2059
	2060	</listitem>
	2061
1997	2062	</itemizedlist>
1998
1999
2000		<para>
2001
2002		When the log10 scale is applied to the intensities of the previous color
2003		map plot, where almost no signal was visible, then the signal is made
2004		perfectly visible."
2005
2006		</para>
2007
2008		<figure xml:id="fig_minexpert-dt-mz-colormap-widget-log10-z-scale">
2009
2010		<title>Color map plot widget main menu</title>
2011
2012		<mediaobject>
2013
2014		<imageobject role="fo">
2015		<imagedata fileref="print-minexpert-dt-mz-colormap-widget-log10-z-scale.png" format="PNG" scale="50"/>
2016		</imageobject>
2017		<imageobject role="html">
2018		<imagedata fileref="web-minexpert-dt-mz-colormap-widget-log10-z-scale.png" format="PNG" scale="50"/>
2019		</imageobject>
2020
2021		<caption>
2022
2023		<para>
2024
2025		The switch to a log10 scale for the intensities might reveal a lot
2026		of missing signal when the intensities are used in a linear scale.
2027
2028		</para>
2029
2030
2031		</caption>
2032
2033		</mediaobject>
2034
2035		</figure>
2036	2063
2037	2064	</sect3>
2038	2065

+113

-4

doc/user-manual/xml/mass-data-integrations.xml less more

1175	1175
1176	1176	<para>
1177	1177
1178		The first step in the definition of a skewed selection rectangle is to
	1178	The first step in the definition of a skewed selection rectangle is to
1179	1179	right-button-drag the mouse along the X axis in order to draw a
1180	1180	selection line that has the final skewed rectangle width. Once the
1181	1181	width is properly defined, the user presses the <keycap>S</keycap>

1220	1220
1221	1221	<para>
1222	1222
1223		The last step in the definition of a skewed selection rectangle is to
	1223	The last step in the definition of a skewed selection rectangle is to
1224	1224	drag the right mouse button over a bi-dimensional space (that is, also
1225	1225	along the Y axis) while maintaining the <keycap>Alt</keycap>
1226	1226	modifier key pressed. The rectangle that is drawn is now skewed, in
1227	1227	contrast to a normal square-corner rectangle.
1228
	1228
1229	1229	</para>
1230	1230
1231	1231	</caption>

1264	1264
1265	1265	<para>
1266	1266
1267		The result of a skewed selection rectangle-based integration is
	1267	The result of a skewed selection rectangle-based integration is
1268	1268	inherently of the shape of the selection.
1269	1269
1270	1270	</para>

1274	1274	</mediaobject>
1275	1275
1276	1276	</figure>
	1277
	1278	</sect1>
	1279
	1280
	1281	<sect1 xml:id="sec_noise-reduction-in-color-map-plots">
	1282
	1283	<title>Noise Reduction in Color Map Plots</title>
	1284
	1285	<para>
	1286
	1287	The signal obtained in ion mobility–mass spectrometry experiments may
	1288	be of a very wide dynamics, which hamper proper visualization of details.
	1289	One solution is to run a Z axis scale (the axis holding intensity values)
	1290	conversion from linear scale to log10 scale (see <xref
	1291	linkend="fig_minexpert-dt-mz-colormap-widget-log10-z-scale"/>). While this
	1292	has the benefit of highlighting details, it also has the drawback of
	1293	potently enhancing noise. As of version 8.1.0, &mineXp2; provides means to
	1294	signal-to-noise ratio tweaking as detailed below.
	1295
	1296	</para>
	1297
	1298	<para>
	1299
	1300	There are two different approaches to signal-to-noise ratio enhancement:
	1301
	1302	</para>
	1303
	1304	<itemizedlist>
	1305
	1306	<listitem>
	1307
	1308	<para>
	1309
	1310	<guimenuitem>Low pass-filter Z axis data</guimenuitem>: The value that is
	1311	entered in the spin box widget is a <emphasis>percentage</emphasis> of the
	1312	maximum intensity over the whole map. The function first computes a
	1313	threshold using the formula
	1314	threshold = percentage * max_int / 100. All
	1315	the cells having an intensity value above that threshold have their value
	1316	set to that threshold value. All other cells are unchanged. This function
	1317	is used to reduce the dynamic range of the map and potentially enhance
	1318	features of interest.
	1319
	1320	</para>
	1321
	1322	</listitem>
	1323
	1324	<listitem>
	1325
	1326	<para>
	1327
	1328	<guimenuitem>High pass-filter Z axis data</guimenuitem>: The value
	1329	that is entered in the spin box widget is a
	1330	<emphasis>percentage</emphasis> of the maximum intensity over the
	1331	whole map. The function first computes a threshold using the formula
	1332	threshold = percentage * max_int / 100.
	1333	All the cells having an intensity value below that threshold have
	1334	their value set to that threshold value. All other cells are
	1335	unchanged.
	1336
	1337	</para>
	1338
	1339	<para>
	1340
	1341	This function is typically used for removing noise. Indeed, by setting
	1342	the percentage value to 5, for example, all the cells having a pretty
	1343	low intensity value (that is, below 5 % of the maximum intensity
	1344	value in the whole map data) will be set to that value. An example is
	1345	provided in <xref linkend="fig_minexpert-colormap-noise-reduction"/>.
	1346
	1347	</para>
	1348
	1349	</listitem>
	1350
	1351	</itemizedlist>
	1352
	1353	<figure xml:id="fig_minexpert-colormap-noise-reduction">
	1354
	1355	<title>Example of signal-to-noise ratio enhancement</title>
	1356
	1357	<mediaobject>
	1358
	1359	<imageobject role="fo">
	1360	<imagedata fileref="print-minexpert-colormap-noise-reduction.png"/>
	1361	</imageobject>
	1362
	1363	<imageobject role="html">
	1364	<imagedata fileref="web-minexpert-colormap-noise-reduction.png"/>
	1365	</imageobject>
	1366
	1367	</mediaobject>
	1368
	1369	<caption>
	1370
	1371	<para>
	1372
	1373	The top left vignette shows the colormap as it is computed. The top right
	1374	vignette show that colormap after a log10 recomputation has been
	1375	performed. The remaining vignettes correspond to the application of a
	1376	high pass filter with percentage values increasing from 10 to 40 in
	1377	10&nbps;% increments.
	1378
	1379	</para>
	1380
	1381
	1382	</caption>
	1383
	1384	</figure>
	1385
1277	1386
1278	1387	</sect1>
1279	1388

+22

-0

doc/user-manual/xml/revision-history.xml less more

14	14
15	15	<revision>
16	16
	17	<revnumber>8.1.0</revnumber>
	18	<date>21 April 2021</date>
	19	<authorinitials>fr</authorinitials>
	20
	21	<revdescription>
	22
	23	<itemizedlist>
	24
	25	<listitem><para>
	26
	27	Update the user manual with the description of the new color map filters used to enhance the signal-to-noise ratio.
	28
	29	</para></listitem>
	30
	31	</itemizedlist>
	32
	33	</revdescription>
	34
	35	</revision>
	36
	37	<revision>
	38
17	39	<revnumber>8.0.1</revnumber>
18	40	<date>24 march 2021</date>
19	41	<authorinitials>fr</authorinitials>