LabPal User Manual
  • Easily run experiments on a computer
  • A quick tutorial
    • Creating an experiment
    • Creating a lab
    • Creating a lab
    • Adding a table
    • Adding a plot
    • Wrapping up
    • Advanced functionalities
  • Using the web console
    • Typical usage of the web console
    • The elements of the web console
    • Running a lab on a remote machine
    • Changing the server port
    • Changing the color scheme
  • Using the text console
  • Experiments: advanced features
    • Use multiple types of experiments in the same lab
    • Use table transformations
    • Make experiments that depend on external resources
    • Dealing with errors
    • Update a progress indicator for long experiments
    • Guess the execution time of an experiment
    • Generate multiple data points in a single experiment
    • Group experiments
  • Creating and transforming tables
  • Creating plots
    • Plot libraries
    • Two-dimensional plots
    • Customizing GRAL plots
    • Palettes
  • Managing files
    • Using the FileHelper
    • Bundling external resources
  • Saving, loading, merging labs
    • Save a lab
    • Load a lab
    • Merge labs
    • Preload a lab with results stored internally
    • Export a lab notebook
    • Be careful with serialization
  • Adding metadata
    • To the lab
    • To each experiment group
    • To each experiment
    • To each parameter
  • Creating regions
    • Iterating over regions
    • Irregular regions
    • Regions are objects
    • Filtering experiments
    • Counting points
  • Calling external commands
  • Including external results
    • By hand
    • Automatically from a file
  • Running LabPal on multiple machines
    • Auto-reporting
    • Filtering
    • Auto-start
  • Data Provenance and Traceability
  • Verifying claims on experiments
    • The Claim object
    • Viewing claims
    • Explaining violations
    • Claims as integrity checks
  • Playing with the lab's parameters
    • Change the code
    • Edit experiments in the web console
  • Other features
    • Passing command-line parameters
    • Customizing the web console
    • Checking the environment
    • Creating a lab in Python
Powered by GitBook
On this page
  • Passing command-line parameters
  • Customizing the web console
  • Checking the environment
  • Creating a lab in Python

Other features

PreviousEdit experiments in the web consoleNextPassing command-line parameters

Last updated 6 years ago

Passing command-line parameters

It may be desirable to make the lab depend on settings that are decided by the user when it is launched. For example, in our running example comparing sorting algorithms, one could wish to have control on the increment step for the size of the array. Our had a hard-coded increment step of 100 elements.

It is possible for a lab to declare command-line arguments, that the lab can then retrieve in its setup method. To this end, one must implement a method called setupCli. When called, this method is given an instance of a object, which will be used to parse the command-line arguments. Method setupCli can add new arguments to this parser. For example, let us add an argument called step, which will define the increment step to use when creating the experiments:

public void setupCli(CliParser parser) {
  parser.add(new Argument().withLongName("step").withArgument("n")
    .withDescription("Increment array sizes by n"));
}

To retrieve the value of step when the lab is setup, one can call getCliArguments:

public void setup() {
  int step = 100;
  ArgumentMap map = getCliArguments();
  if (map.hasOption("step")) {
    step = Integer.parseInt(map.getOptionValue("step"));
  }
  ... (Rest of setup code)
}

In the above snippet, the value of step is set to 100; if a command line argument has been given, then step is replaced by the value passed at the command line. This can be done when starting the lab:

$ java -jar my-lab.jar --step 200

Customizing the web console

public class HelloCallback extends WebCallback {
  public HelloCallback(Laboratory lab, LabAssistant assistant) {
    super("/hello", lab, assistant);
  }
  public CallbackResponse process(HttpExchange t) {
    CallbackResponse r = new CallbackResponse(t);
    response.setContentType(ContentType.HTML);
    response.setCode(CallbackResponse.HTTP_OK);
    response.setContents("<html><body>Hello world!</body></html>");
    return response;
  }
}

Once this callback is defined, the lab can register it in setupCallbacks:

public Collection<WebCallback> setupCallbacks(Laboratory lab, LabAssistant assistant) {
  List<WebCallback> list = new ArrayList<WebCallback>();
  list.add(new HelloCallback(lab, assistant));
  return list;
}

When started, the web console now has a new page, http://localhost:21212/hello which, when called, returns the "Hello world" page defined in the corresponding callback.

Checking the environment

There exist situations, however, where this is not possible, and the lab has requirements with respect to the environment in which it is meant to be executed. For example, your experiments may require the use of an external database, some minimum amount of memory or disk space, or some other program that needs to be installed and called from inside the experiments. If these requirements are not met, the lab cannot run or produce meaningful results.

It is possible to verify these conditions at startup by adding to the lab a method called isEnvironmentOk. Insert there any code that can check that the conditions for running the lab are met. For example, the following method checks if a program called "foo" is installed by attempting to run it from the command line:

public String isEnvironmentOk() {
  CommandRunner runner = new CommandRunner(new String[]{"foo"});
  runner.run();
  if (runner.getExitCode() != 0)
    return "Command foo cannot be called at the command line";
  return null;
}

Creating a lab in Python

Please refer to the API documentation of for precisions on its usage.

LabPal's web console can be customized to some extent. One needs to add method setupCallbacks to the lab. This method must return a collection (typically a list or a set) of objects of type . A web callback is an object that is called when a given URL is requested to the server. It has a method called process, which creates an HTTP response from the request. As an example, here is a simple callback that prints a dummy HTML page:

LabPal and its encourage the production of a single, stand-alone, runnable environment that includes all its necessary libraries and input files. This way, a lab can easily be copied around and run without any setup.

An error is detected by checking that the exit code is different from 0. (See .)

You must return null if everything is OK. As a rule, returning a non-null value (typically an error message) means that something external to the lab must be fixed before running the experiments; hence LabPal will simply quit. If your experiments have they can generate by themselves, don't use this method.

LabPal is implemented as a Java library, and is especially suited for labs and experiments written as Java classes. However, it is also possible to write experiments and labs using Python, thanks to the library.

To this end, you can use our , which contains a Python lab and a Python experiment class. Please refer to that project's README file for more information on how to create a lab in Python.

CliParser
WebCallback
template project
CommandRunner
Jython
template project
quick tutorial
CliParser
Passing command-line parameters
Customizing the web console
Checking the environment
Creating a lab in Python
prerequisites