* Bug 6070 fixed [doc]: Documenting How to make multiscaled plots
[scilab.git] / scilab / modules / graphics / help / en_US / plot_multiscaled.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2019 - Samuel GOUGEON
5  *
6  * This file is hereby licensed under the terms of the GNU GPL v2.0,
7  * pursuant to article 5.3.4 of the CeCILL v.2.1.
8  * This file was originally licensed under the terms of the CeCILL v2.1,
9  * and continues to be available under such terms.
10  * For more information, see the COPYING file which you should have received
11  * along with this program.
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
16         xmlns:db="http://docbook.org/ns/docbook"  xmlns:scilab="http://www.scilab.org"
17         version="5.0-subset Scilab" xml:lang="en" xml:id="plot_multiscaled">
18     <refnamediv>
19         <refname>multiscaled plots</refname>
20         <refpurpose>How to set several axes for one curve or for curves with distinct scales</refpurpose>
21     </refnamediv>
22     <refnamediv xml:id="plotyy"/>
23     <refnamediv xml:id="yyaxis"/>
24     <refsection>
25         <title>Description</title>
26         <para>
27             Several situations may need to use and set several cartesian X axes or several
28             cartesian Y axes, as for instance:
29             <orderedlist>
30                 <listitem>
31                     We want to read the same curve according to distinct scales along
32                     multiple X or Y axes:
33                     <itemizedlist>
34                         <listitem>
35                             <para>
36                             If the relationship between both scales is affine (such as y'=a.y+b)
37                             and linear axes must be rendered,
38                             <link linkend="drawaxis">drawaxis</link>() can be used.
39                             </para>
40                         </listitem>
41                         <listitem>
42                             <para>
43                             If the relationship between both scales is a power law (such as y'=a.y^b),
44                             using logarithmic axes and <link linkend="newaxes">newaxes</link>()
45                             will be required.
46                             </para>
47                         </listitem>
48                     </itemizedlist>
49                     Anyway, both scales are here tightly related. In order to insure that
50                     it's also the case for their drawing, the <literal>gca().tight_limits</literal>
51                     property will have to be set to "on" in the considered direction
52                 </listitem>
53                 <listitem>
54                     <para>
55                     We want to overplot several curves sharing the same X abscissae but according
56                     to distinct uncorrelated Y scales. Then, one or several overlaying axes will
57                     be set using <link linkend="newaxes">newaxes</link>().
58                     </para>
59                 </listitem>
60             </orderedlist>
61         </para>
62     </refsection>
63     <refsection role="examples">
64         <title>Examples</title>
65         <para>
66             Water density: Two X linear scales for the same curve
67         </para>
68         <programlisting role="example"><![CDATA[
69 t = linspace(0,10,100);
70 tf = t*1.8+32;
71 d = -6.863e-3*t.^2 + 0.05463*t + 999.84;
72 clf
73 // Main plot
74 plot(t,d)
75 xgrid(color("grey70")*[1 1],[1 1], [7 7])
76 title("Water density","fontsize",3)
77 xlabel("Temperature [°C]")
78 ylabel("$kg.m^{-3}$", "fontsize",3)
79
80 // Making some space for the 2nd X-label
81 ax = gca();
82 ax.margins(3) = 0.2;
83 ax.title.position(2) = 1000.0;
84
85 // Drawing the 2nd temperature axis in °F, + labelling it:
86 xf = 32:50;
87 atf = drawaxis(dir='u', tics="v", x=(xf-32)/1.8, y=999.96, val=msprintf("%d\n",xf') )
88 c = color("magenta");
89 set(atf, "tics_color",c, "labels_font_color",c)
90 xstring(5,999.99,"Temperature [°F]")
91 set(gce(), "clip_state", "off", "text_box_mode", "centered","font_foreground",c);
92 gcf().axes_size = [610 510];
93      ]]></programlisting>
94         <scilab:image>
95             t = linspace(0,10,100);
96             tf = t*1.8+32;
97             d = -6.863e-3*t.^2 + 0.05463*t + 999.84;
98             clf
99             // Main plot
100             plot(t,d)
101             xgrid(color("grey70")*[1 1],[1 1], [7 7])
102             xlabel("Temperature [°C]")
103             ylabel("$kg.m^{-3}$", "fontsize",3)
104
105             // Making some space for the 2nd X-label
106             ax = gca();
107             ax.margins(3) = 0.2;
108             ax.title.position(2) = 1000.0;
109
110             // Drawing the 2nd temperature axis in °F, + labelling it:
111             xf = 32:50;
112             atf = drawaxis(dir='u', tics="v", x=(xf-32)/1.8, y=999.96, val=msprintf("%d\n",xf') )
113             c = color("magenta");
114             set(atf, "tics_color",c, "labels_font_color",c)
115             xstring(5,999.99,"Temperature [°F]")
116             set(gce(), "clip_state", "off", "text_box_mode", "centered","font_foreground",c);
117             title("Water density","fontsize",3)
118             gcf().axes_size = [610 510];
119         </scilab:image>
120         <para/>
121         <para>
122             Light spectrum, versus both wavelengths and frequencies: two correlated logarithmic X scales.
123         </para>
124         <programlisting role="example"><![CDATA[
125 function r = Planck(T, lambda)
126     h = 6.626e-34;        // Planck constant    [J.s]
127     c = 298792458;        // light speed [m/s]
128     k = 1.381e-23;        // Boltzmann constant [J/K]
129     // stef = 5.670374e-8 // Stefan constant [W/m2/K4]
130     r = 2*h*c^2 ./ lambda.^5 ./ (exp(h*c./(lambda*k*T))-1);
131 endfunction
132
133 clf
134 lambda = (100:10000);
135 plot2d("ll", lambda, Planck(5700, lambda*1e-9)*1e-6)
136 xlabel("Wavelength [nm]", "fontsize",2)
137 ylabel("$\text{Luminance }[W.m^{-2}.sr^{-1}.µm^{-1}]$", "fontsize", 2)
138 xgrid(color("grey70")*[1 1],[1 1],[7 7])
139 a1 = gca();
140 a1.margins(3) = 0.20;
141 a1.sub_tics(2) = 8;
142
143 // 2nd axes, superimposed to the first one
144 a2 = newaxes();
145 a2.data_bounds = [3e13,0;3e15 ,1];
146 a2.Axes_reverse(1) = "on";
147 a2.axes_visible(1) = "on";
148 set(a2, "filled", "off", "log_flags","lnn", "x_location","top")
149 a2.tight_limits(1) = "on";
150 a2.margins(3) = 0.20;
151 xlabel("Wave frequency [Hz]", "fontsize",2)
152 title("Black Body spectrum : Planck law (T = 5700 K)", "fontsize",3)
153      ]]></programlisting>
154         <scilab:image>
155             function r = Planck(T, lambda)
156                 h = 6.626e-34;        // Planck constant    [J.s]
157                 c = 298792458;        // light speed [m/s]
158                 k = 1.381e-23;        // Boltzmann constant [J/K]
159                 // stef = 5.670374e-8 // Stefan constant [W/m2/K4]
160                 r = 2*h*c^2 ./ lambda.^5 ./ (exp(h*c./(lambda*k*T))-1);
161             endfunction
162
163             clf
164             lambda = (100:10000);
165             plot2d("ll", lambda, Planck(5700, lambda*1e-9))
166             xlabel("Wavelength [nm]", "fontsize",2)
167             ylabel("$\text{Luminance }[W.m^{-2}.sr^{-1}.m^{-1}]$", "fontsize", 2)
168             xgrid(color("grey70")*[1 1],[1 1],[7 7])
169             a1 = gca();
170             a1.margins(3) = 0.20;
171             a1.sub_tics(2) = 8;
172
173             // 2nd axes, superimposed to the first one
174             a2 = newaxes();
175             a2.data_bounds = [3e13,0;3e15 ,1];
176             a2.Axes_reverse(1) = "on";
177             a2.axes_visible(1) = "on";
178             set(a2, "filled", "off", "log_flags","lnn", "x_location","top")
179             a2.tight_limits(1) = "on";
180             a2.margins(3) = 0.20;
181             xlabel("Wave frequency [Hz]", "fontsize",2)
182             title("Black Body spectrum : Planck law (T = 5700 K)", "fontsize",3)
183         </scilab:image>
184         <para/>
185         <para>
186             pH: A single curve, with two correlated Y scales: one linear, one logarithmic.
187         </para>
188         <programlisting role="example"><![CDATA[
189 pH1 = 1.5;      // v1 = 10 mL of acid solution
190 pH2 = 12.5;     // v2 mL of basic solution
191 v2 = logspace(0,4,200);
192 // naive raw pH estimation after mixing
193 pH = -log10((10*(10.^-pH1) + v2*(10.^-pH2))./(10+v2));
194
195 clf
196 plot2d("ln",v2, pH)
197 ax1 = gca();
198 ax1.tight_limits(2) = "on";
199 ax1.sub_ticks(1) = 8;
200 xgrid(color("grey70")*[1 1],[1 1],[7 7])
201 title("Acidity after mixing V mL of pH=13.5 to 10 mL of pH=1.5", "fontsize",3)
202 xlabel("V (mL)", "fontsize",3)
203 ylabel("pH", "fontsize",3);
204
205 // [H^+] logarithmic 2nd scale
206 ax2 = newaxes();
207 ax2.data_bounds([4 3]) = 10.^(-ax1.data_bounds([3 4]));
208 set(ax2, "filled","off", "y_location","right", "log_flags","nln")
209 ax2.tight_limits(2) = "on";
210 ax2.axes_visible(2) = "on";
211 ax2.axes_reverse(2) = "on";
212 ylabel("$[H^+]\text{ concentration }(mol.L^{-1})$","fontsize",3)
213 ax2.y_label.font_angle = 90;
214      ]]></programlisting>
215         <scilab:image>
216             pH1= 1.5;       // v1 = 10 mL of acid solution
217             pH2 = 12.5;     // v2 mL of basic solution
218             v2 = logspace(0,4,200);
219             // naive raw pH estimation after mixing
220             pH = -log10((10*(10.^-pH1) + v2*(10.^-pH2))./(10+v2));
221
222             clf
223             plot2d("ln",v2, pH)
224             ax1 = gca();
225             ax1.tight_limits(2) = "on";
226             ax1.sub_ticks(1) = 8;
227             xgrid(color("grey70")*[1 1],[1 1],[7 7])
228             title("Acidity after mixing V mL of pH=13.5 to 10 mL of pH=1.5", "fontsize",3)
229             xlabel("V (mL)", "fontsize",3)
230             ylabel("pH", "fontsize",3);
231
232             // [H^+] logarithmic 2nd scale
233             ax2 = newaxes();
234             ax2.data_bounds([4 3]) = 10.^(-ax1.data_bounds([3 4]));
235             set(ax2, "filled","off", "y_location","right", "log_flags","nln")
236             ax2.tight_limits(2) = "on";
237             ax2.axes_visible(2) = "on";
238             ax2.axes_reverse(2) = "on";
239             ylabel("$[H^+]\text{ concentration }(mol.L^{-1})$","fontsize",3)
240             ax2.y_label.font_angle = 90;
241         </scilab:image>
242         <para/>
243         <para>
244             Three overplotted curves sharing the same X axis, with 3 independent Y scales:
245         </para>
246         <programlisting role="example"><![CDATA[
247 // Preparing data
248 x  = linspace(1,30,200);
249 y2 = exp(x/6).*(sin(x)+1.5);
250 y3 = 1+x.^2;
251
252 clf
253
254 // Black curve => y1 scale (left axis)
255 y1 = sin(x/2);
256 plot2d(x, y1)
257 title(_("Plot with 3 independent Y scales at shared X"), "fontsize",3);
258 xlabel(_("Common X axis"), "fontsize",2);
259 ylabel(_("Scale #1"), "fontsize",2);
260 xgrid(color("grey70")*[1 1], [1 1], [7 7])
261
262 // Blue curve => y2 scale (middle axis)
263 c = color("blue");
264 ax2 = newaxes();
265 set(ax2, "filled", "off", "foreground", c, "font_color", c);
266 plot2d(x, y3, logflag="nl", style=c)
267 gce().children.thickness = 2;
268 ax2.axes_visible(1) = "off";
269 ax2.y_location = "middle";
270
271 // Red curve => y3 scale (right axis)
272 c = color("red");
273 ax3 = newaxes();
274 set(ax3, "filled", "off", "foreground", c, "font_color", c);
275 plot2d(x,y2,style=c);
276 ylabel(_("Scale #3"),"color",[1 0 0])
277 gce().children.thickness = 2;
278 ax3.axes_visible(1) = "off";
279 ax3.y_location = "right";
280      ]]></programlisting>
281         <scilab:image>
282             // Preparing data
283             x  = linspace(1,30,200);
284             y2 = exp(x/6).*(sin(x)+1.5);
285             y3 = 1+x.^2;
286
287             clf
288
289             // Black curve => y1 scale (left axis)
290             y1 = sin(x/2);
291             plot2d(x, y1)
292             title("Plot with 3 independent Y scales at shared X", "fontsize",3);
293             xlabel("Common X axis", "fontsize",2);
294             ylabel("Scale #1", "fontsize",2);
295             xgrid(color("grey70")*[1 1], [1 1], [7 7])
296
297             // Blue curve => y2 scale (middle axis)
298             c = color("blue");
299             ax2 = newaxes();
300             set(ax2, "filled", "off", "foreground", c, "font_color", c);
301             plot2d(x, y3, logflag="nl", style=c)
302             gce().children.thickness = 2;
303             ax2.axes_visible(1) = "off";
304             ax2.y_location = "middle";
305
306             // Red curve => y3 scale (right axis)
307             c = color("red");
308             ax3 = newaxes();
309             set(ax3, "filled", "off", "foreground", c, "font_color", c);
310             plot2d(x,y2,style=c);
311             ylabel("Scale #3", "color",[1 0 0])
312             gce().children.thickness = 2;
313             ax3.axes_visible(1) = "off";
314             ax3.y_location = "right";
315         </scilab:image>
316     </refsection>
317     <refsection role="see also">
318         <title>See also</title>
319         <simplelist type="inline">
320             <member>
321                 <link linkend="drawaxis">drawaxis</link>
322             </member>
323             <member>
324                 <link linkend="newaxes">newaxes</link>
325             </member>
326         </simplelist>
327     </refsection>
328 </refentry>