<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.Matlab03}
\wikidoc{auth=mikerb@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Matlab Plotting Lab 03 - Scatter Plots}
\vspace{0.2in}
\labcourse{Pavlab: Matlab Bar Plotting}
\vspace{0.5in}
\labpng{0.25}{figures/matlab.png}
\vspace{0.25in}
\labdate{Jan 6th, 2023}
\vspace{0.23in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\labtocdepth{2}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage

%===================================================================
% Begin the body of the text
%===================================================================
\section{Overview and Objectives}
%===================================================================

Scatter plots are especially useful for representing results of an
autonomous vehicle. Performance of an autonomous system is often
evaluated as a tradeoff between efficiency and safety. Efficiency may
take on the form of minimizing time or distance in transiting, or
other tasks such as visiting the most number of sites within a given
time and so on. Safety often means avoiding collisions with obstacles
or other platforms. In any event, the 2D scatter plot is useful since
each experimental run can be rendered as a single point on the plot on
the x-y axes representing a safety and efficiency score. The cluster
of points can quickly provide a visual assessment of a large set of
experiments and whether any outliers occurred beyond acceptable levels
of safety, or efficiency. 

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Goal - Make a plot with manually entered data
\item Goal - Plotting data from a file
\item Goal - Running a matlab script 
\item Goal - Plot two datasets into one plot
\end{packed_itemize}
\end{labinfo}

%=======================================================================
\subsection*{Preliminaries}

Make sure that Matlab is installed on your computer. On Linux or MacOS systems
you should be able to confirm from the command line:

\vspace{0.1in}
\begin{consoleverb}
$ which matlab
/Applications/MATLAB_R2022b.app/bin/matlab     (or similar depending on your install)
\end{consoleverb}

\vspace{0.1in}
\noindent
After launching matlab, a window like the below should open:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.9\textwidth]{figures/matlab_main.png}
  \caption{The initial Matlab window upon launch}
  \label{fig_matlab_main}
\end{figure}
\vspace{0.1in}

\noindent
Assuming thing look like the above, you should be good to proceed.

%=======================================================================
\section{Simple Plotting}
%=======================================================================

%=======================================================================
\subsection{A First Scatter Plot with Labels}

In the Command Window of Matlab a first simple plot can be generated with
the following commands. 

\vspace{0.1in}
\begin{consoleverb}
;; wget https://oceanai.mit.edu/matlab/examples/3/example3A.m
x=0:1:20;      % Plot from [0,20] sampling at each integer
y=x.^2;
hold on;
xlabel('x');
ylabel('x^2');
scatter(x,y,50,'b','filled','MarkerFaceAlpha',0.2);
hold on;
scatter(x(4),y(4),'r','filled','MarkerFaceAlpha',0.9)
\end{consoleverb}

\vspace{0.1in}
\noindent
In the first invocation of \var{scatter()}, the marker size is set to
50, the color is set to blue (\var{'b'}). Markers by default are empty
circles. The \var{'filled'} parameter changes this. And the
transparency of each marker is set to be $0.2$. This will be useful
when the scatter plot has many overlaying points.

\vspace{0.1in}
\noindent
The second incocation of \var{scatter()} renders a single point rather
than the vector of points. This will be useful when points need to
be rendered with different shaped or colored markers. This may be the
case for example if there are multiple sets of points related to different
missions with different parameters. Or if a point represents some other
aspect of an experiment.

\vspace{0.1in}
\noindent
A separate pop-up window should appear looking something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\textwidth]{figures/plot3A.png}
  \caption{A scatter bar plot of $y=x^2$}
  \label{fig_plot3A}
\end{figure}
\vspace{0.1in}

%=======================================================================
\subsection{Multiple Clusters in a Single Plot}

Multiple plots may be overlayed in the same graph. Below is a simple example
that extends the first example.

\vspace{0.1in}
\begin{consoleverb}
% wget https://oceanai.mit.edu/matlab/examples/example3B.m
% open example3B.m
% &gt;&gt; example3B
x=0:1:20;      % Plot from [0,20] sampling at each integer
y=x.^2;
z=400-x.^2
hold on;
xlabel('x');
ylabel('x^2');
scatter(x,y,50,'b','filled','MarkerFaceAlpha',0.2);
hold on;
zcolor=[0 0.5 1];
scatter(x,z,50,zcolor,'filled','MarkerFaceAlpha',0.5);
\end{consoleverb}

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\textwidth]{figures/plot3B.png}
  \caption{A scatter plot of $f(x)=x^2$ and $f(x)=10000 - x^{2}$}
  \label{fig_plot2B}
\end{figure}
\vspace{0.1in}


%=======================================================================
\section{Plotting Scatter Data from a File}
%=======================================================================

%=======================================================================
\subsection{Preliminaries}

In the cases where we expect to generate scatter plots from mission data,
the data is typically generated to an alog file in the form:

\vspace{0.1in}
\begin{fileverb}
428.02774    EVALUATION    pEvaluator    w=18.4,x=179.293,y=56.66,z=22.43
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Presumably an app like the fictional \var{pEvaluator} is monitoring
the mission and assessing performance with the result posted in a
variable like \mvar{EVALUATION}. Typically this value is in a
comma-separated list of param=value pair like the example above.  In
the case above, the value has four components (\var{w,x,y,z}). To
generate a scatter plot, we will be interested in isolating two of
those components, and will need a tool (\app{aloggrep}) for doing so.

\vspace{0.1in}
\noindent
We use the example mission, \var{plotview}, found in the MOOS-IvP example
missions folder, \var{moos-ivp/ivp/missions} to explore the process of
grabbing data for scatter plots. 

\vspace{0.1in}
\noindent
The pipeline will happen in three steps:

\vspace{0.1in}
\begin{packed_itemize}
\item Run the mission while creating an alog file of data
\item Pruned the alog file to isolate the relevant data
\item Modify the pruned data into a plottable form
\item Plot the data with Matlab
\end{packed_itemize}

\vspace{0.1in}
\noindent
The plotview mission is shown in Figure \ref{fig_plotview}.

\vspace{0.1in}
\noindent
This mission can be run with:

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp/ivp/missions/plotview
  $ ./launch.sh 
\end{consoleverb}
\vspace{0.1in}

\noindent
In this mission there is no simulated vehicle or autonomy. The primary
process running is \app{uTimerScript} which is repeatedly generating
values for three random variables. Two of them have a gaussian
distribution, and one has a uniform distribution. The GUI running
during this mission is the app \app{uPlotView}, which is configured to
just plot these values live in a bar graph as shown in the figure.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\textwidth]{figures/plotview.png}
  \caption{The uPlotView GUI running while updating with values from
    three random variables. Two have a gaussian distribution, rendered
    in blue and green in the figure. One variable has a uniform
    distribution, rendered in red in the figure. The GUI is not Matlab
    based. It is OpenGL/FLTK based like other MOOS-IvP GUI apps.}
  \label{fig_plotview}
\end{figure}
\vspace{0.1in}

\noindent
In this mission, \app{uTimerScript} is generating four variables, all logged
and found in the alog file. An example of each is shown below:

\vspace{0.1in}
\begin{fileverb}
78.57245   ALL_VALS        uTimerScript    w=238.6,x=174.199,y=62.453 
78.57310   GAUSS_VAL_A     uTimerScript    174.19900    
78.57371   GAUSS_VAL_B     uTimerScript    62.45300     
78.57431   UNIFORM_VAL     uTimerScript    238.60000    
\end{fileverb}
\vspace{0.1in}

\noindent
In this mission, \app{uPlotViewer} is configured to plot
\mvar{GAUSS\_VAL\_A}, \mvar{GAUSS\_VAL\_B}, and \mvar{UNIFORM\_VAL},
as shown in Figure \ref{fig_plotview}. The fourth variable contains
all three values and we will use this variable to create our scatter
plot.

%=======================================================================
\subsection{Extracting the Data}

After the mission is run, and the corresponding alog file has been
created, the following three steps are taken:

\begin{packed_itemize}
\item The alog file is reduced to a smaller alog file with isolated data
  with just postings to the MOOS variable \mvar{ALL\_VARS}.
\item The \var{x} and \var{y} values are isolated to create points in our
  scatter plot and stored in a separate file.
\end{packed_itemize}

\vspace{0.1in}
\noindent
After the plotview completes, find the alog file generated by the
mission. We'll call this \var{data.alog}. The first step, a step of
convenience, is just to prune the alog file down to contain only
the logged values for variable \mvar{ALL\_VALS}. We'll call this new
file \var{data\_pruned.alog}.

\vspace{0.1in}
\begin{consoleverb}
$ aloggrep data.alog ALL_VALS data_pruned.alog
\end{consoleverb}
\vspace{0.1in}

\noindent
In the next step we isolate the \var{x} and \var{y} components of each
posting to \mvar{ALL\_VARS}. The goal is to have each line in the file
contain only this information. A line in \var{data\_pruned.alog} will
look like:

\vspace{0.1in}
\begin{fileverb}
174.199 62.453 
\end{fileverb}

\vspace{0.1in}
\noindent
This is done with the command:

\vspace{0.1in}
\begin{consoleverb}
$ aloggrep data_pruned.alog ALL_VALS --subpat=x --subpat=y --format=val
\end{consoleverb}
\vspace{0.1in}

\noindent
The below command does the same thing, but we'll use shorthand options for
some of the arguments, and the output of the file will be redirected to a
new file \var{scatter\_xy\_01.txt}:

\vspace{0.1in}
\begin{consoleverb}
$ aloggrep data_pruned.alog ALL_VALS --subpat=x:y --v &gt; scatter_xy_01.txt
\end{consoleverb}
\vspace{0.1in}

\noindent
This format of data is ripe for plotting with a scatter plot, shown next.


%=======================================================================
\subsection{A Scatter Plot from Data Read from a File}
In most cases plotted data will be read in from a file. In this example
the data from the plotview mission described above will be plotted as
a scatter plot. Namely the file:

\begin{packed_itemize}
\item \var{scatter\_xy.txt}
\end{packed_itemize}


\vspace{0.1in}
\begin{consoleverb}
% wget https://oceanai.mit.edu/matlab/examples/example3C.m
% open example2C.m
% &gt;&gt; example3C
function example3C()
A=load('scatter_xy_01.txt');
scatter(A(:,1),A(:,2),'b','filled', 'MarkerFaceAlpha',0.2);
%axis([0 200 0 200]);
xlabel('x');
ylabel('x^2');
end
\end{consoleverb}

\vspace{0.1in}
\noindent
The result is in Figure \ref{fig_plot3C} below.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.9\textwidth]{figures/plot3C.png}
  \caption{Scatter plots showing the randomly generated x-y pairings
    from the plotview mission. The figure on the right is the result
    of fixing the axes to have the range $[0,200]$ by uncommenting the
    \var{axis([0 200 0 200]);} line in this example.}
  \label{fig_plot3C}
\end{figure}
\vspace{0.1in}

%=======================================================================
\subsection{A Scatter Plot from Data Read from Multiple Files}

Our anticipation is that, in testing autonomy algorithms, a scatter plot will
be the result of many instances of a vehicle simulation while holding constant
certain parameters of the autonomy behaviors, or certain parameters of the
simulation environment. Some example "knobs" in include:

\begin{packed_itemize}
\item The number of vehicles
\item The speed of the vehicles
\item The sensor range of the vehicles
\item The priority weight for collision avoidance
\item The collision tolerance for a given mission
\end{packed_itemize}

\noindent
There are virtually unlimited ways to vary a simulation or autonomy
configuration. Each cluster represents a many simulations holding everything
constant except for random starting positions and random variations injected
into the simulation. As an example of the latter, consider a random generation
of simulated obstacle placements. 

\vspace{0.1in}
\noindent
In any event, we are keenly interested in the generation of multiple
clusters of data, each representing a single scatter plot cluster in our plots.
In this we, we can visualize the effect of the change configurations on
a large set of data. Lastly, we may also want to consider data sets of two
identically configured autonomy missions, with identically configured simulation
parameters when we are testing new versions of the algorithms running under
the hood.

\vspace{0.1in}
\noindent
A second dataset can be generated, \var{scatter\_xy\_02.txt} by returning
to the plotview mission and relaunching. In this case, different values for
mu and sigma are passed at launch time to generate different scatter data:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch.sh --mua=100 --mub=100 --siga=15 --sigb=15
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
As before, find the alog file, which will have timestamped name, but we'll
say it is called \var{data.alog}. A second dataset suitable for plotting can
again be obtained with:

\vspace{0.1in}
\begin{consoleverb}
$ aloggrep data.alog ALL_VALS --subpat=x:y --v &gt; scatter_xy_02.txt
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Armed with this second data file, both datasets can be ploted with:

\vspace{0.1in}
\begin{consoleverb}
% wget https://oceanai.mit.edu/matlab/examples/example2D.m
% open example2D.m
% &gt;&gt; example3D
function example3D()
A=load('scatter_xy_01.txt');
B=load('scatter_xy_02.txt');
scatter(A(:,1),A(:,2),'b','filled', 'MarkerFaceAlpha',0.2);
hold on
scatter(B(:,1),B(:,2),'r','filled', 'MarkerFaceAlpha',0.2);
xlabel('x');
ylabel('y');
end
\end{consoleverb}

\vspace{0.1in}
\noindent
The result is in Figure \ref{fig_plot2D} below.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.6\textwidth]{figures/plot3D.png}
  \caption{Scatter plots showing the randomly generated x-y pairings
    from two runs of the plotview mission with different parameter
    settings for generating the two clusters of data.}
  \label{fig_plot3D}
\end{figure}
\vspace{0.1in}

%=======================================================================
\subsection{Plotting Data from a File Named as Matlab Argument}

In this next example, the previous example is expanded to define a
Matlab function that accepts two data files as arguments. We also
provide a first example how to change the properties of a single
marker in a scatter plot.

\vspace{0.1in}
\begin{consoleverb}
function example3E(arg1, arg2)
A=load(arg1);
B=load(arg2);
scatter(A(:,1),A(:,2),'b','filled', 'MarkerFaceAlpha',0.2);
hold on
scatter(B(:,1),B(:,2),'r','filled', 'MarkerFaceAlpha',0.2);
hold on
scatter(B(5,1),B(5,2),120,'d','filled',...
        'MarkerFaceColor', 'w', ...
        'MarkerFaceAlpha', 1, ...
        'MarkerEdgeColor', 'm', ...
        'MarkerEdgeAlpha', 1, ...
        'LineWidth', 3)
xlabel('x');
ylabel('y');
\end{consoleverb}

\vspace{0.1in}
\noindent
The previous plot can then be generated as below. In this example,
a single chosen marker from the second (red) cluster is isolated and
drawn differently in the second invocation of \var{scatter()}. In this
second invocation, \var{'d'} denotes a diamond marker, and $120$ denotes
the larger size. 

\vspace{0.1in}
\begin{consoleverb}
&gt;&gt; example3E scatter_xy_01.txt scatter_xy_02.txt
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.65\textwidth]{figures/plot3E.png}
  \caption{Scatter plots showing the randomly generated x-y pairings
    from two runs of the plotview mission with different parameter
    settings for generating the two clusters of data. A single point
    from the red cluster is re-plotted with different shape and color
    properties.}
  \label{fig_plot3E}
\end{figure}
\vspace{0.1in}


%=======================================================================
\subsection{Plotting Data from a File Named as Linux Shell Argument}

In our final example, we extend the previous example by showing how we can
invoke Matlab from the Linux/MacOS command line, passing in arguments
naming both data files to be plotted, and the image file to be created.
In this example, interactive Matlab will not be launched. The goal is to
be able to invoke examples like this from within a bash script at the
culmination of an automated experiment. We're looking for a line as
simple as:

\vspace{0.1in}
\begin{consoleverb}
$ matlab plotfile.m datafile1.txt datafile2.txt image.jpg
\end{consoleverb}

\noindent
The below example has three additions over the previous example:

\begin{packed_itemize}
\item The main function \var{example2F} now accepts three
  arguments. The first two arguments are the data files to be plotted,
  and the third argument names the image file to be created from the
  plotted data.
\item It contains a line of the form \var{saveas(gcf,file.png)} which
  will save the plot image to a file, named in the function argument
  \var{arg3}.
\item The final addition is to add the \var{exit} line immediately
  after the plot file has been saved. This automatic exit is needed to
  bring down Matlab automatically and return to the shell command
  line.
\end{packed_itemize}

\vspace{0.1in}
\begin{fileverb}
% wget https://oceanai.mit.edu/matlab/examples/example3F.m
% matlab example3F.m -r "example3F(\"scatter_xy_01.txt\", \"scatter_xy_02.txt\", \"image.png\")"
function example3F(arg1, arg2, arg3)
clf
A=load(arg1);
B=load(arg2);
scatter(A(:,1),A(:,2),'b','filled', ...
	'MarkerFaceAlpha', 0.2, ...
	'DisplayName', 'Group 1');

hold on
scatter(B(:,1),B(:,2),'r','filled', ...
	'MarkerFaceAlpha', 0.2, ...
	'DisplayName', 'Group 2');

legend('Location', 'best', 'FontSize', 12);
xlabel('x');
ylabel('y');

hold off
saveas(gcf, arg3)
exit
end
\end{fileverb}

\vspace{0.1in}
\noindent
To invoke this on the command line, run:

\vspace{0.1in}
\begin{consoleverb}
$ matlab example3F.m -r "example3F(\"scatter_xy_01.txt\", \"scatter_xy_02.txt\", \"image.png\")"
\end{consoleverb}

\vspace{0.1in}
\noindent
This invokes matlab, reading in the function defined in \var{example3F.m}.
The \var{-r cmd} component will invoke the \var{example3F} function with
two arguments surrounded by parentheses. The double-quotes around the whole
part is to shield the parenthesis from the command-line shell. 

\vspace{0.1in}
\noindent
The above example code and command line invocation should produce
plots exactly as in Figure \ref{fig_plots3F}.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.65\textwidth]{figures/plot3F.png}
  \caption{Scatter plots showing the randomly generated x-y pairings
    from two runs of the plotview mission with different parameter
    settings for generating the two clusters of data. In this example,
    legend information is added for the two clusters.}
  \label{fig_plot3F}
\end{figure}
\vspace{0.1in}

\vspace{0.1in}
\noindent
In the final part of this example, we would like to disable the launch
of the Matlab interactive GUI and splash window normally displayed
upon launch. Two more command line args are added:

\vspace{0.1in}
\begin{consoleverb}
$ matlab -nodisplay -nosplash example3F.m -r  \
  "example3F(\"scatter_01.txt\", \"scatter_02.txt\", \"image.png\")"
\end{consoleverb}

\vspace{0.1in}
\noindent
Notes:

\begin{packed_itemize}
\item The arguments \var{-nodisplay} and \var{-nosplash} come {\em before}
  \var{example3F.m}.
\item The argument \var{-r} comes {\em after} \var{example3F.m}.
\end{packed_itemize}

% what happens when/if the function doesn't match the filename?


\end{document}

</pre></body></html>