Parameter types

Times Square notebooks use parameters to pass inputs into the notebook. Different types of parameters are supported, and these types inform the interface for users to enter values and the validation that’s performed on those values. You define parameters in a notebook’s sidecar YAML-formatted metadata file and their values are assigned in the notebook’s parameters cell, which is always the first code cell in the notebook. This page lists the different types of parameters that are supported.

Strings

A string is the most basic parameter type that supports any kind of text. There isn’t any validation performed on the string.

Notebook YAML sidecar
parameters:
  message:
    type: string
    description: A message to display.
    default: "Hello world"
Notebook parameters cell
message = "Hello world"

Dates

Dates (without times) are a format of the basic string type. Users enter dates in the format YYYY-MM-DD (ISO 8601) and your notebook receives the date as a datetime.date object.

Notebook YAML sidecar
parameters:
  start_date:
    type: string
    format: date
    description: An ISO8601 date
    default: "2024-01-01"
Notebook parameters cell
import datetime

start_date = datetime.date.fromisoformat("2024-01-01")

Note how Times Square automatically imports the datetime module for you in the parameters cell to parse the date into a datetime.date object. Replicate this pattern in the default parameters cell of your notebook.

Instead of a fixed default date, you can also set a dynamic default that is relative to the date the notebook is viewed:

Notebook YAML sidecar
parameters:
  start_date:
    type: string
    format: date
    dynamic_default: "today"

See Setting dynamic defaults for date and dayobs parameters for more information about the syntax for dynamic_default.

DayObs

Rubin Observatory uses DayObs to identify an observing night since the DayObs is consistent over the course of a night. DayObs is defined as the date formatted as a natural number in the UTC-12 timezone, and is represented as a string with eight digits: YYYYMMDD.

Notebook YAML sidecar
parameters:
  start_dayobs:
    type: string
    format: dayobs
    description: A DayObs date
    default: "20240101"
Notebook parameters cell
start_dayobs = 20240101

In the notebook, the dayobs format parameter is assigned as an integer.

Instead of a fixed default DayObs, you can also set a dynamic default that is relative to the date the notebook is viewed:

Notebook YAML sidecar
parameters:
  start_dayobs:
    type: string
    format: dayobs
    dynamic_default: "yesterday"

See Setting dynamic defaults for date and dayobs parameters for more information about the syntax for dynamic_default.

DayObs-Date

The dayobs-date format is similar to the dayobs format, but assigned as a datetime.date object in the notebook. The parameter value strings also contain dashes, like a regular date format: YYYY-MM-DD.

Notebook YAML sidecar
parameters:
  start_dayobs_date:
    type: string
    format: dayobs-date
    description: A DayObs date
    default: "2024-01-01"
Notebook parameters cell
import datetime

start_dayobs_date = datetime.date.fromisoformat("2024-01-01")

dayobs-date parameters also support dynamic defaults, which are relative to the date the notebook is viewed:

Notebook YAML sidecar
parameters:
  start_dayobs_date:
    type: string
    format: dayobs-date
    dynamic_default: "yesterday"

Date and time

Dates and times are another format of the basic string type that specify a precise moment in time. Date and time parameters are entered in the format YYYY-MM-DDTHH:MM:SS+HH:MM (ISO 8601) and your notebook receives the date as a datetime.datetime object. Note that a time zone is required. Besides specifying a time zone offset, you can also use the Z suffix to indicate UTC.

Notebook YAML sidecar
parameters:
  start_time:
    type: string
    format: date-time
    description: An ISO8601 date and time
    default: "2024-01-01T12:00:00Z"
Notebook parameters cell
import datetime

start_time = datetime.datetime.fromisoformat("2024-01-01T12:00:00Z")

Note how Times Square automatically imports the datetime module for you in the parameters cell to parse the date into a datetime.datetime object. Replicate this pattern in the default parameters cell of your notebook.

Integers

For whole numbers, use the integer type. In your code, these values are Python int objects.

Notebook YAML sidecar
parameters:
  number:
    type: integer
    description: An integer
    default: 42
Notebook parameters cell
number = 42

Validation constraints

The integer type supports validation constraints. You can specify minimum values and maximum values (both or either):

Notebook YAML sidecar
parameters:
  number:
    type: integer
    description: An integer
    default: 42
    minimum: 0
    maximum: 100

Floating point numbers

For floating point numbers, use the number type. In your code, these values are Python float objects.

Notebook YAML sidecar
parameters:
  number:
    type: number
    description: A number
    default: 27.5
Notebook parameters cell
number = 27.5

Validation constraints

Like the integer type, the number type supports validation constraints. You can specify minimum values and maximum values (both or either):

Notebook YAML sidecar
parameters:
  number:
    type: number
    description: A number
    default: 27.5
    minimum: 0
    maximum: 100

Booleans

Boolean (true/false) values are supported with the boolean type. The string representation is based on JSON’s true and false values. In your code, these values are Python bool (True / False) objects.

Notebook YAML sidecar
parameters:
  switch_param:
    type: boolean
    description: A boolean
    default: true
Notebook parameters cell
switch_param = True