In many projects it is necessary to share the result of programming work with other colleagues – or to work together on these projects. In the MRDAES book, Chapter 2.8.5 describes how to collaborate on MATLAB projects with collaborators with four different levels of MATLAB skills: (1) no software installed and no experience with MATLAB, (2) software installed but only limited MATLAB skills, and (3) software installed and good MATLAB skills. Below you find an update of this chapter, which now also includes using (4) MATLAB Projects to organize and collaborate on large programming projects together with Git, the most popular version control system for programming projects.
To present MATLAB results to the first group of collaborators we use the MATLAB publishing feature that was introduced in the R2006a release. The second group of collaborators will appreciate the capabilities of the Live Editor. This editor displays MATLAB code in an attractive design, which is similar to the output from the Publish feature of MATLAB but can be edited and run. The third group of collaborators will will actually be able to collaborate on shared scripts and functions via the cloud storage service MATLAB Drive and using version comparison in MATLAB to track changes. The fourth group will be able to achieve the highest level of code editing, using MATLAB Projects shared via Git, a software for tracking changes in computer code. There are numerous platforms providing Internet hosting for software development and version control using Git, including GitHub, but universities also provide Git-based services, such as Git.UP by the University of Potsdam. In this exercise, we will set up a Git project as a MATLAB Project to combine the benefits of both ways of programming together. Similar to Git projects, MATLAB projects help collaborating, tracking and merging changes, and performing code reviews.
Exercise
1. Create a MATLAB script using the classic Editor to generate Gaussian-distributed data with a mean of 3.4 and a standard deviation of 1.2, and display the data in a histogram. Use the MATLAB Publish feature to generate a file that includes the MATLAB code, comments, and embedded images. Convert the output from Publish into a PDF file that you can send to a collaborator.
2. Use the Live Editor to generate a Live Script that includes MATLAB code, comments, and embedded images, which you can then send to a collaborator.
3. Store the MATLAB script created with the Editor in a new folder within the Shared directory in MATLAB Drive. Share the new folder with a collaborator by sending an email invitation to him/her with permission to view or edit the file.
4. Create a Git project for the script, link it to your MATLAB environment and, in a second step, make it a MATLAB project with extended functionality. Share the Git project and the MATLAB project with a collaborator by inviting him/her with permission to view or edit the file.
Solution
1. We first create a script called exercise_2_8_5_script_1.m. We then click on the Publish button in the Publish toolstrip. The entire script now runs and the Figure Windows pops up while the script is running. A window eventually opens up that shows the contents of the published M-file. The resulting HTML file and included graphics can be saved as a PDF file and shared with a collaborator.
2. After opening the M-file in the classic Editor, we click on the Save button, select Save As… and save the file in the MATLAB Live Code files (*.mlx) format. The appearance of the script immediately switches to the design known from that of the MATLAB Publish feature. At first no graphics appear, but if we click on Run in the toolbar of the Editor, the Live Script runs and all graphics appear embedded in the script. We can use Save As… to export the Live Script to a PDF file, which we can then share with a collaborator.
3. We now use MATLAB Drive to share and edit MATLAB M-files. We first have to download and install the MATLAB Drive Connector from the MathWorks webpage. The installation procedure also creates a directory called MATLAB Drive in the user’s home directory, which includes subdirectories such as Published and Shared. MATLAB Drive provides a common cloud-based storage location for MATLAB files. These files can be accessed on multiple devices, e.g. a desktop computer and a laptop, mobile devices and MATLAB Online to be used through a web browser.
4. We first create a subdirectory called Exercise_2_8_5 in the Shared directory. We then move the script exercise_2_8_5_script_1.m into this directory, after which it is automatically synchronized with MATLAB Drive in the cloud and thus made accessible to all devices. For example, we can log in to http://mathworks.com and view the file in MATLAB Drive, or edit it in MATLAB Online.
5. We next navigate to MATLAB Drive in our MathWorks account at http://mathworks.com. There we find the folder Exercise_2_8_5, which we mark using the mouse. We select Share in the MATLAB Drive menu and select Invite Members. We can now enter the email address of a collaborator and give him/her the opportunity to view or edit the script. After clicking on Send, the collaborator receives by email an invitation to view or edit the file.
6. We then go to GitHub or any other Git platform to create a new project, e.g. mrdeas_exercise_2_8_5. Using the upload feature of Git we then upload the script exercise_2_8_5_script_1.m to our project repository. We then use the Clone button to access the URL of the Git repository, e.g. https://gitup.uni-potsdam.de/trauth/mrdeas_exercise_2_8_5.git.
7. We next create a local directory on our harddrive, e.g. /users/trauth/MATLAB/GitUP/mrdaes_exercise_2_8_5. The directory needs to be empty, even hidden files would cause an error message and the directory has to be recreated.
8. Install Git on your computer using one of the methods explained on the https://git-scm.com website. Open the Current Folder panel in MATLAB, right-click in the panel, choose Source Control -> Manage Files, enter the URL of the Git repository as Repository Path, enter the path of the local directory, press Retrieve, enter your login and password in the pop-up window, and the files are transferred to your local directory. The Current Folder panel now has a Git column in the directory listing indicating whether files are up-to-date (green) or your collaborator(s) has/have edited the files (blue) and they need to be updated. You can again right-click in the panel or on specific files, again choose Source Control, and then you will find the Git commands such as Push and Pull.
9. You can now create another local directory, e.g. /users/trauth/MATLAB/GitUP/mrdaes_exercise_2_8_5_project on your computer. Choose New -> Project -> From Git from the Home Tab of MATLAB, again enter the URL of the Git repository and the path of the local directory and click on the Retrieve button. You get the message that there is no project file included in the directory but MATLAB will create it for you. You now have a Git project with MATLAB Project functionality. The Project tab shows the Project tools such as the Dependency Analyzer on the left together with the Git commands e.g. Branches, Push and Pull on the right. The Editor tab also has the Compare tool to track changes, in addition to the track changes tools of Git.
MATLAB Script
The script exercise_2_8_5_script_1.m used for this exercise generates Gaussian-distributed data with a mean of 3.4 and a standard deviation of 1.2, and displays the data in a histogram.
%% Exercise 2.8.5 Collaborative Coding with MATLAB % % by Martin H. Trauth, 3 August 2022 % http://mres.uni-potsdam.de %% clear, clc, close all %% data = 3.4 + 1.2*randn(60,1); %% histogram(data)
The script is stored as a file called exercise_2_8_5_script_1.m, which is stored in the search path of MATLAB on the computer for tasks 1 and 2 of the exercise. For task 3 the file is stored in a directory called Exercise_2_8_5, in the Shared folder of MATLAB Drive. For task 4 we first create a Git project on GitHub or any other Git platform, upload the file to the project repository and connect MATLAB Desktop with the respository to collaborate in the project.
References
Trauth, M.H. (2021) Signal and Noise in Geosciences, MATLAB Recipes for Data Acquisition in Earth Sciences. Springer International Publishing, 343 p., Supplementary Electronic Material, Hardcover, ISBN: 978-3-030-74912-5 (MRDAES)