Overview
MATLAB is a popular tool for water science, which can be accessed through the MATLAB Online web application to execute code, live scripts, and work with other MATLAB files directly from a web browser. CUAHSI hosts an instance of MATLAB Online for access by HydroShare users to facilitate collaboration and allow for publication of MATLAB based repositories. The web application enables interactive data exploration and visualization with MATLAB using the HydroShare “Open With” functionality.
Getting Started
This section uses prepared data and code stored on HydroShare to demonstrate the MATLAB Online environment. First, log into HydroShare and navigate to this resource, a simple rainfall interpolation Live Script example. This HydroShare resource includes three files: ghcn-precip.dat, ghcn-sites.dat, and rainfall_interopolation.mlx. The *.dat files contain precipitation and site data for Global Historical Climatology Network sensors in and around Seattle, WA. The *.mlx (MATLAB Live Script) is an interactive notebook that performs the interpolation. To run this example, select ”MATLAB Online” from the “Open With” menu in the top right of the resource landing page (shown below).
This will take you to the MATLAB Online landing page. After agreeing to the terms of use, an isolated computational environment is created for you. The files from the HydroShare resource where you opened MATLAB Online will be automatically downloaded into your workspace.
The standard view of the MATLAB Online environment consists of a directory panel for navigating directories and opening files, an editor panel for interacting with code, a workspace panel for inspecting variables, and a command panel for running MATLAB commands. Double-click on the folder named “Interpolating-GHCN-Timeseries…” in the Directory panel. Next, double-click on rainfall_interpolation.mlx to open the Live Script.
Step through each section of the MATLAB Live Script by clicking the “Run and Advance” button on the ribbon toolbar. You can also add breakpoints and step through the code line-by-line just like in MATLAB Desktop. As you step through each section of the code, variables appear in the Workspace panel, as shown below. Explore the contents of these variables by double clicking the name. Variables values can also be displayed in the Command Window.
By default, figures appear to the right of the Live Script code, as shown below. You can toggle to inline mode (also shown below) via the output buttons located in the upper right window.
At the end of the script, you are presented with instructions for saving the results back to HydroShare. The code snippet below is the basic syntax for creating a HydroShare resource from the MATLAB Online web application. Paste the code snippet into the Command Window, edit it to match your desired save parameters, and then run the code.
After editing and executing the code, a HydroShare URL is returned. Navigate to this URL to see your new HydroShare resource. This syntax can be used to create a HydroShare resource from the MATLAB web application for any MATLAB code.
Launching the Web Application
There are multiple ways to access the MATLAB Online web application from HydroShare. The simplest is from the HydroShare Apps library. This will launch an isolated, customized, cloud computing environment. In this app, you can create files and execute code. Any data you upload, download, and create is associated with your HydroShare account and will persist between sessions, meaning that it will be there next time you log in.
Another way to access the MATLAB Online web application is using the HydroShare “Open with …” button in the top right corner of any HydroShare resource landing page. After selecting “MATLAB Online”, a computing environment will be prepared with the content of the current HydroShare resource as illustrated in the “Getting Started” section . This is a convenient method for executing code, data, and workflows that have been published in the HydroShare repository.
Access and Authentication
Access to the MATLAB Online environment is currently available to all HydroShare users.
Interacting with HydroShare
The MATLAB Online web application comes preinstalled with the HS_MTools, a set of tools for interacting with HydroShare via REST web service calls in MATLAB. . The functions are intended to be called from the Command Window, but can be included in scripts as well. Capabilities include downloading, creating, renaming, and adding files to a HydroShare resource, as shown below.
hs_get : Downloads HydroShare resource data into the current directory. This function takes a HydroShare unique resourceid as input. Type help hs_get in the command window for more details.
>> help('hs_get')
HS_GET is a utility function for downloading HydroShare resources into your MATLAB workspace.
Usage: hs_get(<resource_id>, <pretty_name>, <replace>)
Args:
resource_id The GUID of the Hydroshare resource to download (string)
pretty_naming Renames the download using the resource title, default=false (boolean)
replace Flag indicating if existing data will be replaced, default=false (boolean)
Returns:
path to downloaded resource
hs_create : Creates a new HydroShare resource. This function takes a title, abstract, keywords, and an array of file paths as input. Type help hs_create in the command window for more details.
>>help('hs_create')
HS_CREATE is a utility function for creating new HydroShare resources from content in your MATLAB Online workspace.
Usage: hs_create(<title>, <abstract>, <keywords>, <filepaths>)
Args:
title The title for the new resource (string)
abstract The abstract for the new resource (string)
keywords Keywords that will be added to the new resource (string array)
filepaths Paths of files to add to the new resource (string array)
Returns:
url of the newly created HydroShare resource
hs_addfile : Adds a file to an existing HydroShare resource. This function takes resourceid, filepath, overwrite (optional, default=FALSE) as input. Type help hs_addfile in the command window for more details.
>>help('hs_addfile')
HS_ADDFILE is a utility function for adding content from the MATLAB Online environment to existing HydroShare resources.
Usage: hs_addfile(<resourceid>, <filepaths>, <overwrite>)
Args:
resourceid Unique GUID of the target HydroShare resource (string)
filepaths Paths of files that will be added to the resource (string array)
overwrite Flag that indicates if existing files will be overwritten (boolean, default=false, optional)
Takes a resourceid, filepath, overwrite (optional, default=FALSE)
hs_rename : Renames all HS resources in a given directory to the resource's title instead of the resource identifier. This function takes a directory as input. Type hs_rename in the command window for more details.
>> help('hs_rename')
HS_RENAME is a utility function for renaming downloaded HydroShare resources from the standard GUID naming convention to the resource's title.
Usage: hs_rename(<directory>)
Args:
directory The directory of the HydroShare resource that will be renamed (string)
Toolboxes and Libraries
The MATLAB Online web application comes with a variety of libraries and toolboxes. For a complete list of which are supported, see https://www.mathworks.com/products/matlab-online/limitations.html.
Credits, Authors, Contributors and Contacts
For questions, please contact help@cuahsi.org
CUAHSI: Tony Castronova, Dan Palmer
MathWorks: Lisa Kempler, Chandani Madnani