Week 13a: MATLAB Scripts, Documentation, and File I/O

Contents

Week 13a: MATLAB Scripts, Documentation, and File I/O#

Learning Objectives#

By the end of this prereading, you should be able to:

  • Create and run MATLAB script files

  • Document your code with comments and function headers

  • Read data from and write data to text files

  • Load and save MATLAB data files

1. MATLAB Scripts#

What is a Script?#

A script is a file containing a sequence of MATLAB commands that execute together. Scripts are similar to Python .py files but use the .m extension in MATLAB.

Creating a Script#

To create a new script:

  1. Click New Script in the MATLAB toolbar, or

  2. Type edit scriptname.m in the command window

Running a Script#

There are three ways to run a script:

  1. Click the Run button in the editor

  2. Press F5 while in the editor

  3. Type the script name (without .m) in the command window

Key Differences from Python#

  • MATLAB scripts share the workspace with the command window (no explicit if __name__ == "__main__" needed)

  • All variables created in a script remain in the workspace after execution

  • Scripts don’t require special syntax to run; just save and execute

Example Script#

% data_analysis.m
% This script analyzes temperature data

temperatures = [72, 75, 78, 73, 71, 74, 76];
avg_temp = mean(temperatures);
max_temp = max(temperatures);

fprintf('Average temperature: %.2f°F\n', avg_temp);
fprintf('Maximum temperature: %.2f°F\n', max_temp);

2. Documenting Your Code#

Single-Line Comments#

Use the % symbol for comments (similar to # in Python):

% This is a comment
x = 5;  % Inline comment

Multi-Line Comments (Block Comments)#

Use %{ and %} for block comments:

%{
This is a multi-line comment.
It can span several lines.
Useful for longer explanations.
%}

Header Documentation#

Always include a header at the top of your scripts with:

  • Purpose of the script

  • Author and date

  • Input requirements

  • Output description

% ANALYZE_GRADES - Calculate statistics for student grades
%
% Author: Your Name
% Date: November 2025
%
% Description:
%   This script reads grade data, calculates mean and median,
%   and generates a histogram of the distribution.
%
% Inputs: grades.txt (text file with one grade per line)
% Outputs: Grade statistics printed to console and histogram figure

The help Command#

When you type help scriptname, MATLAB displays the first contiguous comment block. This makes good header documentation essential for code reusability.

3. Importing Data from Different File Types#

MATLAB can work with many file formats. Choosing the right import function depends on your data structure and file type.

CSV Files (Comma-Separated Values)#

CSV files are common for spreadsheet data and data exchange between programs.

Using readmatrix (Numeric Data Only)#

data = readmatrix('grades.csv');  % Returns numeric array

Handling Headers and Options#

% Skip header rows, specify delimiter
data = readmatrix('data.csv', 'NumHeaderLines', 1);

% Read table with specific options
opts = detectImportOptions('data.csv');
opts.VariableTypes(3) = {'double'};  % Force column 3 to be numeric
dataTable = readtable('data.csv', opts);

Excel Files (.xlsx, .xls)#

Excel files can contain multiple sheets and mixed data types.

Reading Excel Data#

% Read numeric data from first sheet
data = readmatrix('experiment.xlsx');

% Read as table (preserves headers and data types)
dataTable = readtable('experiment.xlsx');

% Read specific sheet
dataTable = readtable('experiment.xlsx', 'Sheet', 'Results');

% Read specific range
data = readmatrix('experiment.xlsx', 'Range', 'B2:D10');

Writing Excel Data#

% Write matrix to Excel
results = [1, 2, 3; 4, 5, 6];
writematrix(results, 'output.xlsx');

% Write table to Excel (includes headers)
T = table([1; 2; 3], [4; 5; 6], 'VariableNames', {'A', 'B'});
writetable(T, 'output.xlsx');

Text Files with Delimiters#

For tab-delimited or other custom formats:

% Tab-delimited file
data = readmatrix('data.txt', 'Delimiter', '\t');

% Space-delimited file
data = readmatrix('data.txt', 'Delimiter', ' ');

% Custom delimiter
data = readmatrix('data.txt', 'Delimiter', '|');

Image Files#

MATLAB can read and write various image formats and handles color images as 3D arrays.

Understanding Image Data Structure#

% Read image
img = imread('photo.jpg');  % Works with .jpg, .png, .tif, etc.

% Check image dimensions
size(img)  % Returns [height, width, channels]
% Grayscale: [rows, cols] - 2D array
% Color (RGB): [rows, cols, 3] - 3D array with red, green, blue layers

Working with Color Images#

Color images in MATLAB are stored as 3D arrays where:

  • 1st dimension = height (rows)

  • 2nd dimension = width (columns)

  • 3rd dimension = color channels (3 layers: Red, Green, Blue)

% Read a color image
colorImg = imread('sunset.jpg');

% Access individual color channels
redChannel = colorImg(:, :, 1);    % All red values
greenChannel = colorImg(:, :, 2);  % All green values
blueChannel = colorImg(:, :, 3);   % All blue values

% Display original and channels
figure;
subplot(2,2,1); imshow(colorImg); title('Original');
subplot(2,2,2); imshow(redChannel); title('Red Channel');
subplot(2,2,3); imshow(greenChannel); title('Green Channel');
subplot(2,2,4); imshow(blueChannel); title('Blue Channel');

Converting Between Color and Grayscale#

% Convert color to grayscale
grayImg = rgb2gray(colorImg);

% Convert grayscale to "color" (3 identical channels)
colorFromGray = cat(3, grayImg, grayImg, grayImg);

Creating Modified Color Images#

% Create a copy and modify specific channel
modifiedImg = colorImg;
modifiedImg(:, :, 1) = modifiedImg(:, :, 1) * 1.5;  % Boost red channel

% Set a channel to zero (remove that color)
noRed = colorImg;
noRed(:, :, 1) = 0;  % Remove all red

Image Data Types#

% Most images are uint8 (0-255)
class(img)  % Usually returns 'uint8'

% Convert to double for calculations (0.0-1.0 range)
imgDouble = im2double(img);

% Convert back to uint8 for display/saving
imgUint8 = im2uint8(imgDouble);

Saving Images#

% Write image
imwrite(colorImg, 'output.png');

% Write with quality setting (for JPEG)
imwrite(colorImg, 'output.jpg', 'Quality', 95);

4. Saving Data for Reuse#

8. Saving Data for Reuse#

.mat files are MATLAB’s native format and the most efficient way to save workspace data.

Advantages of .mat Files#

  • Fast to read and write

  • Preserves variable names and data types

  • Can store any MATLAB data type (matrices, tables, structures, cell arrays)

  • Compressed by default to save space

Saving to .mat Files#

% Save specific variables
temperature = [72, 75, 78, 73];
pressure = [1013, 1015, 1012, 1014];
save('experiment_data.mat', 'temperature', 'pressure');

% Save all workspace variables
save('my_workspace.mat');

% Save with version compatibility (for older MATLAB versions)
save('data.mat', 'x', 'y', '-v7.3');

Loading from .mat Files#

% Load all variables from file
load('experiment_data.mat');  % Variables appear in workspace

% Load specific variables only
load('experiment_data.mat', 'temperature');

% Load into a structure (avoids overwriting existing variables)
data = load('experiment_data.mat');
temp = data.temperature;

CSV Files - Best for Data Exchange#

Use CSV when sharing data with other programs (Excel, Python, R) or for human-readable output.

Writing CSV Files#

% Write matrix to CSV
data = [1, 2, 3; 4, 5, 6; 7, 8, 9];
writematrix(data, 'results.csv');

% Write table to CSV (includes column headers)
T = table([10; 20; 30], [40; 50; 60], 'VariableNames', {'Time', 'Value'});
writetable(T, 'results.csv');

Excel Files - Best for Reports and Sharing#

Excel files are ideal when you need formatting or want non-technical users to view your data.

% Write to specific sheet
writematrix(data, 'report.xlsx', 'Sheet', 'Raw Data');
writematrix(summary, 'report.xlsx', 'Sheet', 'Summary');

% Write table with headers
writetable(dataTable, 'report.xlsx', 'Sheet', 'Results');

Text Files - For Custom Formats#

Use fprintf when you need complete control over formatting:

fileID = fopen('report.txt', 'w');
fprintf(fileID, '=== Experimental Results ===\n\n');
fprintf(fileID, 'Average: %.2f\n', mean(data));
fprintf(fileID, 'Std Dev: %.2f\n', std(data));
fclose(fileID);

Choosing the Right Format#

Format

Use When

Advantages

Disadvantages

.mat

Working within MATLAB

Fast, preserves types

MATLAB-specific

.csv

Sharing with other programs

Universal, readable

Numeric/text only

.xlsx

Creating reports

Formatted, familiar

Slower, requires Excel

.txt

Custom formatting needed

Full control

Manual parsing

5. Working with Directories and File Paths#

Understanding how to navigate directories and manage file paths is essential for organizing your projects and working with data files.

Current Directory Operations#

Checking and Changing Directories#

% Show current directory
currentDir = pwd

% Change directory (absolute path)
cd('C:\Users\YourName\Documents\MATLAB')

% Change to parent directory
cd ..

% Change to subdirectory
cd('Data')

% Return to previous directory
cd(currentDir)

Listing Directory Contents#

% List all files and folders in current directory
dir

% List specific file types
dir('*.csv')  % All CSV files
dir('*.mat')  % All MAT files
dir('Data/*.txt')  % All text files in Data subdirectory

% Store directory listing in variable
files = dir('*.csv');
% Access properties
firstFile = files(1).name;  % Name of first file
fileSize = files(1).bytes;  % Size in bytes

Building File Paths#

Path Separators#

% Windows uses backslash
windowsPath = 'C:\Users\Data\file.csv';

% Mac/Linux use forward slash
unixPath = '/home/user/Data/file.csv';

% filesep gives the correct separator for your system
separator = filesep;  % '\' on Windows, '/' on Mac/Linux

% Manual path building (not recommended)
manualPath = ['Data', filesep, 'results.csv'];

Relative vs Absolute Paths#

Absolute Paths#

Full path from the root of your file system:

% Windows absolute path
data = readmatrix('C:\Users\YourName\Documents\data.csv');

% Mac/Linux absolute path
data = readmatrix('/home/username/Documents/data.csv');

Relative Paths#

Path relative to your current directory:

% File in current directory
data = readmatrix('data.csv');

% File in subdirectory
data = readmatrix('Data\experiment1.csv');
% Or better (cross-platform):
data = readmatrix(fullfile('Data', 'experiment1.csv'));

% File in parent directory
data = readmatrix('..\data.csv');
% Or better:
data = readmatrix(fullfile('..', 'data.csv'));

% File two levels up
data = readmatrix(fullfile('..', '..', 'shared_data.csv'));

Creating and Managing Directories#

Creating Directories#

% Create single directory
mkdir('Results')

% Create nested directories
mkdir('Data\Processed')
% Or cross-platform:
mkdir(fullfile('Data', 'Processed'))

% Check if directory exists before creating
if ~isfolder('Results')
    mkdir('Results')
end

Checking Existence#

% Check if file exists
if isfile('data.csv')
    data = readmatrix('data.csv');
else
    error('File not found!');
end

% Check if directory exists
if isfolder('Data')
    cd('Data')
else
    mkdir('Data')
end

Deleting Files and Directories#

% Delete a file
delete('old_results.txt')

% Delete directory (must be empty)
rmdir('OldData')

% Delete directory and all contents
rmdir('OldData', 's')  % 's' flag for recursive deletion

Working with Multiple Files#

Processing All Files in a Directory#

% Get list of all CSV files
fileList = dir('*.csv');

% Loop through each file
for i = 1:length(fileList)
    filename = fileList(i).name;
    filepath = fullfile(fileList(i).folder, filename);
    
    % Read and process each file
    data = readmatrix(filepath);
    avgValue = mean(data, 'all');
    
    fprintf('File: %s, Average: %.2f\n', filename, avgValue);
end

Pattern Matching with dir#

% Find all files starting with "exp"
files = dir('exp*.csv');

% Find all files containing "2024"
files = dir('*2024*.txt');

% Find files in subdirectories (R2016b and later)
files = dir('**/*.csv');  % Recursive search for all CSV files

Organizing Project Files#

Example: Saving Results to Organized Folders#

% Set up project structure
projectRoot = pwd;
resultsFolder = fullfile(projectRoot, 'Results');
figuresFolder = fullfile(resultsFolder, 'Figures');

% Create folders if they don't exist
if ~isfolder(resultsFolder)
    mkdir(resultsFolder);
end
if ~isfolder(figuresFolder)
    mkdir(figuresFolder);
end

% Save figure to organized location
plot(x, y);
saveas(gcf, fullfile(figuresFolder, 'plot1.png'));

% Save data to organized location
save(fullfile(resultsFolder, 'analysis_results.mat'), 'results');

Getting File Information#

% Get detailed file information
fileInfo = dir('data.csv');
fileName = fileInfo.name;
fileSize = fileInfo.bytes;
dateModified = fileInfo.date;

fprintf('File: %s\n', fileName);
fprintf('Size: %d bytes\n', fileSize);
fprintf('Modified: %s\n', dateModified);

% Extract parts of file path
[filepath, name, ext] = fileparts('Data\experiment1.csv');
% filepath = 'Data'
% name = 'experiment1'
% ext = '.csv'

Best Practices for File Paths#

  1. Use fullfile for portability - Your code will work on any operating system

  2. Use relative paths when possible - Makes projects easier to share

  3. Check for existence before operations - Use isfile and isfolder

  4. Organize with subdirectories - Separate raw data, processed data, and results

  5. Use meaningful directory names - Clear structure helps with project management

  6. Avoid spaces in file/folder names - Use underscores instead: my_data.csv not my data.csv

Common Pitfalls#

% DON'T: Hardcode full paths
data = load('C:\Users\John\Documents\MATLAB\data.csv');  % Won't work on other computers

% DO: Use relative paths
data = load(fullfile('Data', 'data.csv'));

% DON'T: Use system-specific separators
path = 'Data\Raw\experiment.csv';  % Breaks on Mac/Linux

% DO: Use fullfile
path = fullfile('Data', 'Raw', 'experiment.csv');

7. File Input/Output - Basic Operations#

Reading Text Files#

Method 1: load for Simple Numeric Data#

The load command reads numeric data from text files:

data = load('numbers.txt');  % Creates variable with file data

Method 3: Reading Line by Line with fopen, fgetl, fclose#

For more control:

fileID = fopen('data.txt', 'r');  % 'r' means read mode
line = fgetl(fileID);  % Get one line
fclose(fileID);  % Always close files!

Reading All Lines from a File#

fileID = fopen('data.txt', 'r');
data = [];
while ~feof(fileID)  % while not end-of-file
    line = fgetl(fileID);
    value = str2double(line);  % Convert string to number
    data = [data; value];
end
fclose(fileID);

Writing Text Files#

Method 1: save for Simple Numeric Data#

results = [1, 2, 3; 4, 5, 6];
save('results.txt', 'results', '-ascii');

Method 2: fprintf for Formatted Output#

fileID = fopen('output.txt', 'w');  % 'w' means write mode
fprintf(fileID, 'Temperature: %.2f\n', temp);
fprintf(fileID, 'Pressure: %.2f\n', pressure);
fclose(fileID);

Common format specifiers:

  • %d - integer

  • %f - floating point

  • %.2f - floating point with 2 decimal places

  • %s - string

  • \n - newline

9. File Management Best Practices#

Check if Files Exist#

if isfile('data.txt')
    data = load('data.txt');
else
    error('File not found!');
end

File Modes#

When using fopen, remember these modes:

  • 'r' - read only

  • 'w' - write (overwrites existing file)

  • 'a' - append (adds to end of existing file)

Always Close Files#

Forgetting to close files can cause problems. Always use fclose(fileID) after opening files with fopen.

Contents