05-cond.md references the word "colormap", but the corresponding entry is actually "additive color model". The connection is difficult to make.

Prior to the Research Bazaar Conference (16-18 Feb, 2015), which is where the next MATLAB workshop will take place (see workshop website here), it would be great to get the MATLAB novice lessons up on the Software Carpentry lessons page.

@gvwilson will be able to advise on how to do this - so long as the MATLAB lessons conform to the lesson template I think it's a fairly simple process and the lessons page will automatically update whenever you make changes to the lesson materials on GitHub.

I don't think this is covered - that only the first conditional statement which is true runs, even though subsequent conditionals might also be true.

I think this would add only 5 minutes including a reading comprehension exercise.

This might also serve as a good opportunity to introduce stepping with the debugger?

Commit 140de3e adds conflict markers to 04-cond.html and 05-func.md (which gets rendered as HTML in 05-func.html).

I have raised this on the python lesson, but it applies here too.
swcarpentry/python-novice-inflammation#534

Understanding what we should expect from the data and why would help to motivate the lesson a bit better, IMO.

MATLAB (and most other languages in the C family) provides in-place operators that work like this:

x = 1;
x += 1;
x *= 3;

Um, no it doesn't ;)

>> x = 1;
>> x += 1;
Error: "x" was previously used as a variable, conflicting with its use here as the name of a function or command.
See "How MATLAB Recognizes Command Syntax" in the MATLAB documentation for details.
 
Did you mean:
>> x  = x +  1;

This repo needs to conform to the lesson template. Here are files/directories that need to be created or need fixing:

• README.md
• code/
• data/
• img/
• fig/
• Makefile
• index.md
• motivation.md
• reference.md
• discussion.md
• instructors.md

Information about all of this is available here:
https://github.com/swcarpentry/lesson-template/blob/gh-pages/LAYOUT.md

Some scripts have a comment e.g. % Demo script to illustrate use of conditionals in ep4, but no name for the script. It would make the lesson easier to follow if every function and script had a consistent H1 line following the guidance from MathWorks.

For the example above it would look like
% CONDITIONAL_DEMO A demo script to illustrate conditionals

We have already introduced the concept of help before scripts, so this might just bring forward the explanation of how to write your own help lines, which currently isn't covered until 05-func.

What do you think?

Many of the episodes are something of a wall of text. I think it would make navigating the lesson for both teaching and learning that much easier if there were some extra headings. Does that sound ok?

Shape seems to be used as a synonym for size, but I don't think shape is a concept within MATLAB?

Please use this issue for discussion of changes we should make by mid-August 2015.

At last debriefing session instructors commented that

listing files at the end of the loops lesson is done with the system command "ls", which gives platform dependent output. On our university clusters, using "ls" results in a mess of unusable output. In the lesson I used the matlab function "dir" instead, which gives a struct array (e.g., problem described here: http://www.mathworks.com/matlabcentral/newsreader/view_thread/289558)

This command isn't explained. I'm not in favour of explaining it, but I think it would be better to avoid it instead of simply glossing over it. So, using two disp commands instead.

Thoughts?

http://swcarpentry.github.io/python-novice-inflammation/05-cond/index.html#checking-our-data
http://swcarpentry.github.io/python-novice-inflammation/06-func/index.html#tidying-up

I like these as examples of using conditionals. Let's include them in the MATLAB lesson?

If time/space is a concern we could swap out the plot switch example?

The challenge titled 'True and false statements' has formatting problems.

Under the heading 'Writing MATLAB Scripts', given that we are focusing of software/data carpentry, I feel it is essential we include a more detailed example for plotting data. While the current example takes the user through the very basics of plotting in MATLAB, instructions on how to co-plot data, specify line styles, and basic manipulation of other plotting parameters will be very useful.

An example code that can introduce the above mentioned concepts using data from 'inflammation-01.csv' is given below:

% script analyze.m

patient_data = csvread('inflammation-01.csv');

disp(['Maximum inflammation: ', num2str(max(patient_data(:)))]);
disp(['Minimum inflammation: ', num2str(min(patient_data(:)))]);
disp(['Standard deviation: ', num2str(std(patient_data(:)))]);

ave_inflammation = mean(patient_data, 1);

%% Find the number of rows
no_of_patients = size(patient_data,1);
arr_of_patients = [1:1:no_of_patients]; % This can introduce the concept of building sequential arrays

%% Plot
% Open figure
figure()
hold all
grid on

% Plot data
plot(arr_of_patients,ave_inflammation,'-');
plot(arr_of_patients,max(patient_data, [], 1),'--','linewidth',2);
plot(arr_of_patients,min(patient_data, [], 1),'-.','color','r');

% Label axis
xlabel('Patient Number')
ylabel('Degree of Inflammation')

% Scale axis
set(gca,'xlim',[0 6])
set(gca,'xtick',[0:1:6])
set(gca,'ylim',[0 20])
set(gca,'ytick',[0:4:20])

% Legend
plen = legend('Average Inflammation','Max. Inflammation','Min. Inflammation')
set(plen,'location','NorthEast')

% save plot to disk as png image:
print ('patient_data-01','-dpng','-r400') % Example to specify type and quality of image

There's no answer to this challenge. I'm happy to make a PR, but I don't understand what the question is asking

Why do our graphs stop just short of 0 at their left edge?

I guess this is referring to the traces rather than the axis limits, but is it asking

Why is the first x-value = 1?

Taking inspiration from the python inflammation lesson, how about a short episode on error messages?

data/*.csv vs data/inflammation-*.csv
Both work, but let's be consistent.

The setup suggests the zip file extracts into a data folder. It doesn't: we just get the csv files.
The lesson (ep1) starts by adding the location of the data files to the MATLAB path. But ep2 uses a relative path data/inflammation-01.csv in the first script. This implies that we're in the directory above, but I can't find where this is set - I think it's missing from the lesson.

I think it would be useful (and not add much time to the lesson) to suggest some good practice of creating a new directory for this 'project' with a src directory and a data directory, and maybe a results directory. We could then set the current directory as the project directory, and use the relative paths to load and save data, with scripts and functions saved to src.

What do you think?

@IsaKiko @ashwinsrnth Hi guys. For our instructor training event starting on Wednesday (Feb 11) in Melbourne we have told participants to read up on the lesson materials prior to attending. One of those participants (@andreabedini) just alerted me to the fact that the links to lesson 2, 3 and 4 are broken at this page: http://swcarpentry.github.io/matlab-novice-inflammation/

See swcarpentry/shell-novice#552

01-intro
Shows averaging across rows but refers to this as axis 0. Similarly averaging across columns should be axis 2 rather than axis 1. The commands which follow are correct - just the diagram which looks to be wrong.

I'm also not sure about this section:

MATLAB stores all data in the form of arrays. For example:

Numbers, or scalars are arrays of zero dimensions, as are single characters,
Lists of numbers, or vectors are arrays of one dimension,
Tables of numbers, or matrices are arrays of two dimensions,
Even character strings, like sentences, are stored as an “array of characters”.

Surely a scalar is a 1*1 array?
I would probably explain these in terms of a scalar is represented in MATLAB as a 1*1 array, a 1*n array for vectors, n*n array for matrices ...

Brought up in #72 (bullet 2)
Containers is a better analogy, if one is required at all.

Every episode is 30 mins teaching and 0 mins exercises, even though the length of the episodes varies, as does the number of exercises.

In various episodes, argument and parameter are used interchangeably. It's a minor point, but we should refer to arguments passed to functions, and parameters in the function definition.

I'll submit a PR.

This one is my bad :(
PR incoming.

In the analyzing patient data section, char(10) was used within the disp function without any explanation of what char(10) is/does. char(10) works as an end of line marker, starting a new line, equivalent to sprintf('\n'). If using fprintf, '\n' can be used to end one line and start the next line. I think the concept of displaying multiple lines within one disp function is useful. I would recommend adding a comment after char(10) was used in the example with "disp(['Weight in kg: ', num2str(weight_kg), char(10), 'Weight in pounds: ', num2str(weight_lb)]);" saying char(10) can be used within a disp function to start a new line. This makes highlights what char(10) does in that statement, and this feature may be useful for students to know about.

The lesson infrastructure committee unanimously approved the proposal of using the same set of labels across all our repositories during its last meeting on May 23rd, 2018.

This repository has now been converted to use the standard set of labels.

If this repository used the previous set of recommended labels by Software Carpentry, they have been converted to the new one using the following rules:

The label instructor-training was removed as it is not used in the workflow of certifying new instructors anymore. The label question was left as is when it was in use, and removed otherwise. If your repository used custom labels (and issues were flagged with these labels), they were left as is.

The lesson infrastructure committee hopes the standard set of labels will make it easier for you to manage the issues you receive on the repositories you manage.

The lesson infrastructure committee will evaluate how the labels are being used in the next few months and we will solicit your feedback at this stage. In the meantime, if you have any questions or concerns, please leave a comment on this issue.

-- The Lesson Infrastructure subcommittee

PS: we will close this issue in 30 days if there is no activity.

Explain why variables should be initialized using actual data values rather than arbitrary constants.
Apologies if I missed it, but is this actually addressed anywhere in the lesson?

In a discussion with Ken Deeley and Jos Martin from Mathworks, and @gvwilson, the following improvements to the SWC MATLAB material have been suggested:

1. MATLAB environment - the lessons don't have, for instance, screenshots of the MATLAB environment. While this reduces maintenance costs, it might also make learning more difficult for beginners. Greg's suggestion: short GIFs/videos of the MATLAB environment
2. Vectorization - effective use of MATLAB entails familiarity with the idea of vectorization. We should introduce this in some depth in our lesson.

At last debriefing session someone mention that

defensive programming lesson as written takes a big leap from the previous lessons; the normalize_rectangle and range_overlap code would be tough for beginners to jump into. Maybe instead of starting with that tough new code we could throw some "assert" commands into their run_analysis function (for the inflammation data) to make sure the loaded datasets have the correct number of lines.

and

lesson going back to simpler code (maybe the temperature functions) would be helpful.

I will be teaching MATLAB/Octave at an upcoming workshop. Installing MATLAB can be taken care of participants with help from their university. But, is there detailed instruction for installing Octave across different operating systems the one for Python?

I'm in the process of writing a big PR with lots of solutions to exercises. Standby ;)

Ep05 has a run_analysis exercise to write a function to do the analysis for one file. My suggestions (I'll later modify the solution once I've address #108):

• write a function to process one file (this is the current exercise)
• call the function from a script to process multiple/all data files
• have a plot_switch parameter for the function

This would automate processing everything, which should be the ultimate aim, right?

When saving plots to disk, it’s a good idea to turn off their visibility as MATLAB plots them. Let’s add a couple of lines of code to do this:

This is simply stated without explanation. Reasons might include:

• efficiency (it takes time to display the figure windows in MATLAB)
• to save you having to close the figure windows afterwards
• some other reason?

It would be good to give some short explanation rather than just stating it (implication being that the reason is obvious). I can submit a PR --- are there any reasons not listed above?

Episode 5 has a section which looks like it was started then abandoned.

Let’s take a closer look at what happens when we call fahr_to_celsius(32.0). To make things clearer, we’ll start by putting the initial value 32.0 in a variable and store the final result in one as well:

original = 32.0;
final = fahr_to_celsius(original);

But then it moves onto the center example.

I was already considering where to talk about variable scope, and this seems like the right place. Would you agree? Commit e255f87 looks like where this paragraph came from - do you recall what you were going to include or should I just draft a PR to discuss?

Semicolons at the end of a line suppress output from a command. However, there are multiple instances of this being used after disp where the command's only job is to print some output, and after plotting commands. In neither case does the semicolon serve a purpose, so I propose only using them after e.g. variable assignments.

I'll submit a PR, but after the current ones have been merged so things don't get too confusing.

In episode 1, this term refers to the command window. I've not encountered this terminology elsewhere; indeed Google doesn't throw up anything useful.

Is this official terminology? Could you point me to a reference?

Otherwise I'm happy to make a PR changing it to 'Command Window'. The fewer terms a novice has to deal with the better.

A less known capability of matlab is c/c++ and fortran interoperability with mex functions to interface other languages. This can be added as a part of the course and I found this an extremely powerful tool, this can be a short introduction with a simple example as follow:
Following is a demonstration of how this would work,
Assuming the mex command is configured correctly (following documentation, you need a c or fortran compiler and need to use mex -setup); do the following

mex dist.c
Building with 'gcc'.
MEX completed successfully.
[[You should now have a dist.mexa64 in linux or dist.dll in windows]]

x=rand(3,5)
x =
0.1190 0.3404 0.7513 0.6991 0.5472
0.4984 0.5853 0.2551 0.8909 0.1386
0.9597 0.2238 0.5060 0.9593 0.1493
y=dist(x)
y =
0 0.3481 0.4431 0.3244 0.5328
0.3481 0 0.3411 0.4666 0.2427
0.4431 0.3411 0 0.3804 0.2257
0.3244 0.4666 0.3804 0 0.5714
0.5328 0.2427 0.2257 0.5714 0

the required c file (copy and paste in dist.c, this calculates a distance but the for loop can be simplified to something like just squaring elements or something similar), this can be provided for the students.

#include "mex.h"
#include "math.h"

void mexFunction(int nlhs,mxArray* plhs[], int nrhs, const mxArray* prhs[])
{
	int i,j,k;
        double *dist,sum;
        /* Check for proper number of arguments. */
 	if(nrhs!=1) {
    	mexErrMsgTxt("One input required.");
  	} else if(nlhs>1) {
    	mexErrMsgTxt("Too many output arguments.");
  	}

	/*Find number of rows and columns in input data and get a pointer to the first input*/
        double* x = mxGetPr(prhs[0]);
	int rows = mxGetM(prhs[0]);
	int cols = mxGetN(prhs[0]);		
    
        plhs[0] = mxCreateDoubleMatrix(cols, cols, mxREAL);
        dist = (double *)mxGetData(plhs[0]);
    
        for(i=0;i<cols;i++)
             for(j=0;j<cols;j++){
                  sum=0.0;
                  for(k=0;k<rows;k++)sum+=fabs(x[i*rows+k]-x[j*rows+k]);
                  dist[i*cols+j]=sum/(double)rows;
              }

}

I am surprised with the fact that GNU Octave does not appear during the lessons. As a perfect free an open source alternative, I would like to know if there is an special reason for this :)

Specially since:

• GNU Octave has a GUI see some screenshots and review
• Topic 1 (Intro: Analyzing patient data) uses GNU Octave documentation when prints the help mean command!
• Figures seem to be also obtained with GNU Octave.

Note: I am reviewing the lessons and still not sure whether these are 100% compatible with GNU Octave

Minor Bug. The README links to the python website https://swcarpentry.github.io/python-novice-inflammation/ instead of the matlab website https://swcarpentry.github.io/matlab-novice-inflammation/.

The gh-pages branch build has failed, and also fails locally with this error message:

Liquid Exception: Could not find document 'aio.md' in tag 'link'. Make sure the document exists and the path is correct. in /_layouts/base.html
jekyll 3.6.2 | Error: Could not find document 'aio.md' in tag 'link'.

MATLAB comes with a fantastic debugger - should we teach it in our workshops? @IsaKiko, @gvwilson, thoughts?

Apologies if I've overlooked something, but going through this MATLAB lesson, I got to the "Fixing code through testing" exercise section where it instructs the user to:

"Fix range_overlap. Uncomment the two commented lines in test_range_overlap. "

It looks like these two lines are missing from the "test_range_overlap" script?

Episode 1 talks about assigning the data from the csv file to a variable. Then it gives some examples of assigning variable, only to repeat the command as if it were introduced for the first time:

Now that we know how to assign things to variables, let’s re-run csvread and save its result.
patient_data = csvread('inflammation-01.csv');

It would make more sense not to show the final command (above) before the explanation and examples of assigning variables, but to introduce it after the explanation:

Getting back to loading data from the csv file, we can assign the result to a variable, patient_data
patient_data = csvread('inflammation-01.csv');

Alternatively we could show the command, then explain it (this is what we currently have) - but reword the quoted text along the lines of

Now we understand how to assign values to variables, let's have a look at the variables in the current workspace
who ...

There's too much whitespace in the figure below the illustration. It would really benefit from cropping.

Hi @ashwinsrnth
I've just spent a good while writing a solution to this exercise in lesson 3.

Using dir, rewrite the analyze script to analyze all csv files in the current directory.

I'm fairly new to MATLAB myself so might have missed something, but I found it a non-trivial exercise so I wouldn't expect any real novices to be able to do it within a reasonable time frame while I'm teaching. Is there a simpler way than the code I've written?

% Solution to analyse all files in directory.

% Use dir as the exercise directs, to get a structure array for the 'data'
% directory.
dir_list=dir('data');

for idx = 1:size(dir_list,1)
    % Read file names from file struct instead of generating them according
    % to the known file name pattern.
    file_name=dir_list(idx).name

    % Exclude . and .. directories - just want data files
    if(strcmp(file_name,'.') || strcmp(file_name,'..'))
        continue
    end

    % Reformat dir_list entries to get required file paths to load and new
    % file names to write.
    img_name = strrep(file_name, '.csv', '');
    img_name = strrep(img_name,'inflammation','patient_data');
    file_name=strcat('data/',file_name);

    % Resume original code
    patient_data = csvread(file_name);

    disp(['Maximum inflammation: ', num2str(max(patient_data(:)))]);
    disp(['Minimum inflammation: ', num2str(min(patient_data(:)))]);
    disp(['Standard deviation: ', num2str(std(patient_data(:)))]);

    ave_inflammation = mean(patient_data, 1);

    figure('visible', 'off')

    subplot(2, 2, 1);
    plot(ave_inflammation);
    ylabel('average')

    subplot(2, 2, 2);
    plot(max(patient_data, [], 1));
    ylabel('max')

    subplot(2, 2, 3);
    plot(min(patient_data, [], 1));
    ylabel('min')

    print(img_name,'-dpng');
    close();

end

What is the learning objective for this section? It seems rather clunky and hard to motivate.

A neater solution is suggested in the following exercise, but no solution is given, and subsequent episodes use the sprintf script.
In order to achieve the same task, I suggest using the dir command to generate a list of files to load, then use the replace command twice to generate the image file names.

I'm happy to submit a PR, but also want to check that it won't remove a learning objective. All I can think of is that sprintf won't have been covered.

@zghasemahmad reported that there is no link to inflammation-01.csv at https://swcarpentry.github.io/matlab-novice-inflammation/01-intro.html.

@ashwinsrnth and @IsaKiko could handle this issue?