This project started many years ago to standardize the way that I read in microscope data. This project has expanded to include many helpful functions and scripts when manipulating data from microscopes, namely high dimensional ones. Many modern microscopes are capable of capturing three-dimensional data with separate channels over time, or what I'll be calling 5-D data.
I hope that you find this repository as useful as I have. Please let me know if you have additions that you find useful that others will too.
These tools have been written with MATLAB's package paradigm.
This allows for a convenient grouping of similar functions.
This also keeps directories well organized.
There are two ways that you can make these packages available for MATLAB to use regardless of the current workspace directory.
One way (not recommended) is to just copy any directory with a + sign to your MATLAB folder in your user space.
For example, on windows this would be C:\Users\myuser\Documents\MATLAB
.
However, doing so will break the whole point of putting these functions in a git repository.
The recommend way is to add the packages to your MATLAB path.
This can be done with an addition to your startup.m file located in your user space.
The root_programs.m
function is used to determine the root directory for MATLAB programs based on the operating system.
This function is crucial for defining a consistent starting point for package paths.
-
Create the Function:
- Create a file named
root_programs.m
. - Copy the provided
root_programs
function code into this file. - Save the file in a directory that is in your MATLAB path, or add its directory to the MATLAB path.
- Create a file named
-
Function Usage:
- This function returns the root directory path for your MATLAB programs.
- On Windows, it derives the path from the MATLAB
userpath
. - On other operating systems, it defaults to the home directory.
The startup.m
script automatically runs each time MATLAB starts, setting up the environment, including adding necessary paths for your packages.
-
Create the Script:
- Create a file named
startup.m
. - Place this file in the directory that MATLAB checks upon startup. This is usually the MATLAB root directory.
- Create a file named
-
Script Setup:
- Copy the provided
startup.m
script code into this file. - Modify the
pkgList
array to include the names of your MATLAB packages.
- Copy the provided
-
Adding Package Paths:
- The script uses the
root_programs
function to find the base directory. - It then adds paths for each package listed in
pkgList
. - Packages are expected to be in the
src/MATLAB
orsrc/matlab
subdirectories.
- The script uses the
Once you have set up the root_programs.m
function and the startup.m
script, MATLAB will automatically configure the paths to your packages each time it starts.
This setup simplifies the management of multiple MATLAB projects and packages, ensuring that all necessary files and directories are easily accessible.
- Keep your package directories organized and consistent with the naming conventions used in
pkgList
. - Regularly update your
startup.m
script as you add or remove packages. - Use version control (like Git) to track changes in your
startup.m
androot_programs.m
files, especially if working in a team environment.
By following these instructions, you can streamline your MATLAB environment setup, making it easier to work with multiple projects and packages.
function str = root_programs()
% root_programs - Determines the root directory for programs.
%
% This function computes the root directory for storing or accessing
% programs. The path is determined based on the operating system.
% For Windows, it derives the path from the user's MATLAB userpath.
% For non-Windows systems, it defaults to the user's home directory.
%
% Output:
% str - A string representing the computed root directory path.
% Check if the operating system is Windows
if ispc
% Obtain the user's MATLAB userpath
usr_path = userpath;
% Split the userpath to extract components
path_comp = split(usr_path, filesep); % Using filesep for OS compatibility
% Construct the root path from the first three components
% This assumes the userpath follows a specific structure
str = fullfile(path_comp{1}, path_comp{2}, path_comp{3});
else
% For non-Windows systems, use the user's home directory
str = '~';
end
end
% Check if the script is running in a deployed (compiled) environment
% If so, skip the rest of the script as path additions are not necessary
if isdeployed
return
end
% Set a breakpoint for all errors - MATLAB will pause execution whenever an error occurs
dbstop if error
% Define the root directory for programming projects
rootProgramming = fullfile(root_programs, 'git', 'programming');
% List of packages to be added to MATLAB's path
% These are assumed to be subdirectories within the rootProgramming directory
pkgList = {...
'hydra-image-processor';
'matlab-utilities';
'direct-5D-viewer';
'hmm-bayes'
};
% Call the function to add specified paths to MATLAB's search path
addPaths(rootProgramming, pkgList);
% Function to add paths
function addPaths(rootProgramming, pkgList)
% Subdirectory names within each package where MATLAB files are located
matlabDir = fullfile('src','MATLAB');
matlabDir_l = fullfile('src','matlab');
% Loop through each package in the list
for i = 1:length(pkgList)
% Construct the full path to the MATLAB directory in the package
pkgPath = fullfile(rootProgramming, pkgList{i}, matlabDir);
% Add the path if it exists
if exist(pkgPath, 'dir')
addpath(pkgPath);
else
% Check for an alternate path (lowercase 'matlab')
pkgPath = fullfile(rootProgramming, pkgList{i}, matlabDir_l);
if exist(pkgPath, 'dir')
addpath(pkgPath);
end
end
end
end
I put all of my git repositories in a master directory, which is stated in the first line.
I have many different packages that I use, so a list of the repository names goes in the package list.
If you have looked at any of my other repositories, I like to have a standard subdirectory hierarchy.
The folder named src
indicates where source code goes.
the second folder MATLAB
indicates that this is MATLAB code.
I then go through all of my packages and add them to my MATLAB path.
This allows me to have access to each of the packages from the MATLAB command line regardless of which directory I'm currently in.
I highly recommend this method. It also helps when you use some of my other various repositories that depend on this one 😃.
This package includes the jar
file for Bioformats that has been tested.
This is only used in the MicroscopeData.Original
package and is not strictly needed for this repository to be useful.
If you would like to use a newer version of the Bioformats functions or would like to compile your own version, please visit their website.
Also, a version of the Keller Lab Block Format is included. If you would like versions for you particular operating system or would just like to compile the most current version, please visit their website.
The most heavily used package in this repository is MicroscopeData.
This package is how I read and write microscope image data where my other repositories can read them in a predictable way.
MicroscopeData.Original
wraps the MATLAB version of Bioformats in such a way that the image and meta-data are returned exactly as the ones written by the MicroscopeData
writers.
The main idea is to read and write 5-D image dataset in multiple file formats with the same MATLAB commands. For example:
[im,imMeta] = MicroscopeData.Reader();
Or alternatively:
[im,imMeta] = MicroscopeData.Reader('C:\pathToJsonFile');
This is the hallmark function of this repository.
Many different file types can be written out by the included code using the particular writers, but reading is as simple as calling the Reader
command.
This is accomplished by having a set of minimal meta-data stored in a json file that is in the same directory as the image files.
The contents of this json file is enough to know how to read the files and reconstruct the data.
The reader will always return the image data as a 5-D matrix where unused dimensions are singleton.
The ordering of this matrix is always (y,x,z,λ,t), where λ is the discrete channels.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
-
Eric Wait -- Architect and maintainer -- Eric Wait.com
-
Andrew Cohen -- Initial Funder and contributor -- Bioimage
-
Mark Winter -- Contributor and consultant
-
Blair Rossetti -- Contributor
See also the list of contributors who participated in this project.
This project is licensed under the BSD License - see the LICENSE.md file for details
- Thanks to Bioformats for doing the impossible task of reading data from multiple microscope manufactures.
- Keller Lab for creating a modern file format that has high compression and parallelized for high throughput.