# Adding metadata

An important part of creating experiments with LabPal is to enable an external user to re-run them easily. To this end, it is crucial to properly **document** your experimental setup, so that other people can understand what you are experimenting, and what all the values, tables and plots mean.

LabPal offers various ways to define *metadata* for your lab --that is, data about its data. You can set descriptions for:

* [The lab](/labpal-user-manual/metadata.md#lab)
* [Each experiment group](/labpal-user-manual/metadata.md#group)
* [Each experiment](/labpal-user-manual/metadata.md#experiment)
* [Each parameter](/labpal-user-manual/metadata.md#parameters)

## Lab description <a href="#lab" id="lab"></a>

A first metadata is about the lab itself. You can enter a textual description for the lab using method `setDescription`:

```java
public void setup() {
  ...
  setDescription("This is a lab for comparing sorting algorithms.");
}
```

If a description is defined, it will be displayed in the web console in the *Home* page, replacing the default help text that shows up otherwise. This description can include any valid HTML markup, and can be as long as you wish.

A recommended tip is to write the description in a separate HTML file that you place in the same folder as your source code. You can then use `FileHelper` to load that file's contents into the description:

```java
public void setup() {
  ...
  setDescription(FileHelper.internalFileToString("description.html",
    this.getClass());
}
```

## Group description <a href="#group" id="group"></a>

If the lab has any experiment [groups](https://github.com/liflab/labpal-user-manual/tree/76405492ae62bc932b890415fc7a035b6685ce27/markdown/experiment/README.md#groups), each group can be given a description using the `setDescription` method:

```java
public void setup() {
  ...
  Group g = new Group("Gnome Sort");
  g.setDescription("Experiments that use the Gnome sort algorithm");
  ...
}
```

The group description, if any, is displayed in the experiment list, under the group's name.

## Experiment description <a href="#experiment" id="experiment"></a>

A description can be entered for each experiment separately. This can be done in two ways:

* Using the experiment's `setDescription` method to set the text
* By overriding the `getDescription` method to return whatever text you want

In both cases, the description string should be valid HTML. This description is displayed in the Experiment page.

The description can be made dynamic, and depend on the experiment's input parameters. In the sorting example we used throughout this manual, one could hence write:

```java
public String getDescription() {
  return "Sorts an array of size " + readInt("Size") +
    " using " + readString("Algorithm");
}
```

## Parameter description <a href="#parameters" id="parameters"></a>

Each individual parameter (input and output) can also be given a description. To this end, an experiment can use the method `describe`:

```java
public abstract class SortExperiment extends Experiment {
  public SortExperiment(int n) {
    setInput("Size", n);
    describe("Size", "The size of the array to sort");
    describe("Time", "The time (in ms) it takes to sort the array");
    describe("Algorithm", "The algorithm used to sort the array");
  }
  ...
}
```

One can see how the `describe` method has been used to associate a short description of the input parameter "Size", as well as the output parameter "Time" and the input parameter "Algorithm". These last two parameters have not yet received a value, but they can already get a description.

In the web console, the description of parameters shows as tooltips wherever the parameter name appears (except in tables). Hovering the mouse over the name displays the description. This makes it easy for an external user to understand the meaning of each value, and in particular to know the units (if any) used for that value.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://liflab.gitbook.io/labpal-user-manual/metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.