Launchers

Launchers are simple web forms that allow users to run templatized scripts. They are especially useful if your script has command line arguments that dynamically change the way the script executes. For heavily customized scripts, those command line arguments can quickly get complicated. Launchers allow you to expose all of that as a simple web form.

To do this with MATLAB, we will refactor the .m file we used in our scheduled job as a function, and give Launcher users the ability to specify two parameters:

  • The NOAA station ID (station IDs are listed here: GHCND Stations
  • A “hot day” temperature threshold



Step 7.1: Refactor the .m file

  1. Start a new MATLAB Workspace. We’ll update our scheduled job code.
  2. Open the file we previously created, predictWeatherReport.m, and save it as predictWeatherReportLauncher.m.
  3. Start by wrapping the script with a function statement. The function statement requires and end statement as well. To avoid confusion with code placement, we’ll add the end statement as the last step of this walkthrough.
function result = predictWeatherReport(weatherStationId, hotDayThreshold)
  1. Let’s refactor the first section of our code:
result = struct;

%% Download data file
baseUrlString = "https://www.ncei.noaa.gov/data/global-historical-climatology-network-daily/access/";

% compose the URL for the NOAA station ID specified as an input parameter
urlString = sprintf("%s%s%s", baseUrlString, weatherStationId, ".csv");
% save the data into the /data subfolder
savedFileName = sprintf("%s%s%s%s",data, filesep, weatherStationId, ".csv");
websave(savedFileName, urlString);
  1. The next section of code should remain unchanged. For reference, here it is again:
%% Read the downloaded file
opts = detectImportOptions(savedFileName);
opts.SelectedVariableNames = {'DATE', 'PRCP', 'TMIN', 'TMAX'};
opts = setvartype(opts, {'DATE','PRCP','TMIN','TMAX'},{'datetime','double', 'double', 'double'});
stationWeatherTbl = readtable(savedFileName, opts);

%%
[stationWeatherTbl.year, stationWeatherTbl.month, stationWeatherTbl.day] = ymd(stationWeatherTbl.DATE);
% MATLAB strength
stationWeatherTbl = stationWeatherTbl(stationWeatherTbl.year > 1999 & stationWeatherTbl.year < max(stationWeatherTbl.year), :);
stationWeatherTbl.TMAX = stationWeatherTbl.TMAX/10;
stationWeatherTbl.TMIN = stationWeatherTbl.TMIN/10;
stationWeatherTbl = fillmissing(stationWeatherTbl, 'linear');

%% check if there is enough data for prediction
dataRows = size(stationWeatherTbl, 1);
if dataRows < 1000
  disp('Not enough data for prediction')
  result.error = 'Not enough data for prediction';
  return;
end
  1. Since Launcher users will be able to request predictions for any weather station, we’ll first need to check whether a model for that station exists. If a model does not exist, we will train a model using the file we saved earlier, trainRegressionModel (in Step 5), along with the data we downloaded. Models will have a filename format of <station ID>.mat.
%% Check if we have a model for this weather station
modelFileName = sprintf("%s%s%s%s", "models", filesep, ...
    weatherStationId, ".mat");

% make sure we have a folder for the models
if ~isfolder('models')
    mkdir('models')
end

if ~isfile(modelFileName)
  disp('Training model for weather station...')
  cv = cvpartition(stationWeatherTbl.year, 'Holdout', 0.3);
  dataTrain = stationWeatherTbl(cv.training, :);

  [weatherModel, validationRMSE] = trainRegressionModel(dataTrain);

  % display prediction precision
  doneMessage = sprintf('%s%d', "Done. Model RMSE:", validationRMSE);
  disp(doneMessage);
  save(modelFileName, 'weatherModel');
else
  load(modelFileName, 'weatherModel');
end
  1. Let’s re-use the code we previously had for creating the data table to drive the prediction model.
%% Create table for future date prediction

todayDate = datetime('today');
daysIntoFuture = 365;
endDate = todayDate + days(daysIntoFuture);
predictedMaxTemps = table('Size', [daysIntoFuture+1 7], 'VariableTypes', ...
    {'datetime', 'double', 'double', 'double', 'double', 'double', 'double'}, ...
    'VariableNames', stationWeatherTbl.Properties.VariableNames);
x=1;


for i=todayDate:endDate
    % get the average perception and minimum temps on this date
    [y, m, d] = ymd(i);

    minTemps = stationWeatherTbl.TMIN(stationWeatherTbl.month == m & stationWeatherTbl.day == d);
    prcps = stationWeatherTbl.PRCP(stationWeatherTbl.month == m & stationWeatherTbl.day == d);

    curMinTemp = NaN;
    [historicalRowCount z] = size(minTemps);
    randomRow = randi([1 historicalRowCount]);
    curMinTemp = minTemps(randomRow);
    predictedMaxTemps.TMIN(x) = curMinTemp;
    randomRow = randi([1 historicalRowCount]);
    predictedMaxTemps.PRCP(x) = prcps(randomRow);
    predictedMaxTemps.DATE(x) = i;
    predictedMaxTemps.year(x) = y;
    predictedMaxTemps.month(x) = m;
    predictedMaxTemps.day(x) = d;
    predictedMaxTemps.TMAX(x) = 0;
    x = x+1;
end
  1. Keep the rest of the file as-is. Here is the code again for reference:
%% run model with future data
yFit = weatherModel.predictFcn(predictedMaxTemps);
predResult = table(predictedMaxTemps.DATE, yFit, 'VariableNames', {'Date', 'Predicted TMAX'});
result.predictedTemps = predResult;
hotWeatherDaysIdx = predResult(predResult.("Predicted TMAX") > hotDayThreshold, :);
result.hotDayCountPrediction = height(hotWeatherDaysIdx);

%% save data to file
dominoRunId = getenv('DOMINO_RUN_NUMBER');
outputFileName = sprintf('%s%s%s', 'results', filesep, 'predictData_', string(dominoRunId));
save(outputFileName, 'result');

%% publish to report
pub_options.format = 'pdf';
pub_options.showCode = false;
pub_options.outputDir = sprintf('%s%s%s', 'results', filesep, dominoRunId);
doc = publish('predictWeatherReportTemplate.m', pub_options);
  1. Don’t forget to add the end statement for our function.
%% Function end
end % This is the end of the function
  1. Click the Save & Push All button to save your work. Stop the workspace.



Step 7.2: Set up the shell script for the Launcher

  1. Close the workspace tab in your browser and expand the “Publish” menu in Domino.
  2. Next, we’ll need to create a shell script that will specify to the Launcher which MATLAB script should run, along with which parameters should be passed to the script from the launcher. Navigate to the “Files” section under your project in Domino.

Image-7-2-8

  1. Click the new file icon to create a new file. Name the file weather_launcher.sh.

Image-7-2-9

Image-7-2-10

  1. Add the following code starting on line 1 of the file:
matlab -nodisplay -nodesktop -nosplash -r " predictWeatherReportLauncher('$1', $2)"

This line of code instructs Domino to run MATLAB from the command line and execute the script called predictWeatherReportLauncher with two arguments. MATLAB will look for the function in an .m file with the same name as the function being called.

  1. Click the Save button to save your work.

Image-7-2-11




Step 7.3: Create the Launcher

  1. Click “Launchers” from inside the “Publish” menu, then click the New Launcher button.

Image-7-2-12

Image-7-2-13

  1. Give the launcher a descriptive title (e.g., “Weather Predictor”), a description, and select a hardware tier. In the “Command to run” section, enter weather_launcher.sh.

Image-7-2-14

  1. Click the Add Parameter button. This section of the modal will expand to show parameter options.

Image-7-2-15

Image-7-2-16

  1. In the “Command to run” field, replace parameter1 with station_id. You’ll notice that the parameter’s name in the form below will update. Ensure that the parameter name remains enclosed within ${}, such that the parameter is formatted as such: ${name_of_the_parameter}.

Image-7-2-17

  1. Let’s give this parameter a default value for the station ID. We’ll use MXM00076680 (for Mexico City). In the description, enter “The ID of the station to predict weather for”. The default value will be used if the user does not enter any value in the Launcher form.

Image-7-2-18

6. Click the Add Parameter button once again and enter hot_temp as the parameter’s name. This parameter will represent the hot temperature threshold. Keep the parameter’s type as “Text” and enter a default value (e.g., 30) and a description for the parameter.

Image-7-2-19

  1. Finally, click Save Launcher and click the Back to Launchers link on the upper left corner of the form. You should see your launcher in the launcher list.

Image-7-2-20

  1. Click the Run button. The launcher form will appear. Enter a title for your run (e.g., “First launcher run”) and click Run.

Image-7-2-21

  1. You should see the “Jobs” view in Domino while your launcher executes the selected job. Note the job number (in this example, job number 61). Expand the “User Output” by clicking on the toggle next to it. You should see the results as Domino run the job.

Image-7-2-22

Image-7-2-23

  1. Running this job will produce a PDF report. To access the PDF report, navigate to “Files” within Domino, open the “Results” folder, open the folder created by your job (in this example, it is folder 61/), and click on the PDF file to open and display it.

Image-7-2-24

Image-7-2-25

Image-7-2-26

Image-7-2-27

Image-7-2-28