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.
parameters:
message:
type: string
description: A message to display.
default: "Hello world"
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.
parameters:
start_date:
type: string
format: date
description: An ISO8601 date
default: "2024-01-01"
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:
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
.
parameters:
start_dayobs:
type: string
format: dayobs
description: A DayObs date
default: "20240101"
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:
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
.
parameters:
start_dayobs_date:
type: string
format: dayobs-date
description: A DayObs date
default: "2024-01-01"
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:
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.
parameters:
start_time:
type: string
format: date-time
description: An ISO8601 date and time
default: "2024-01-01T12:00:00Z"
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.
parameters:
number:
type: integer
description: An integer
default: 42
number = 42
Validation constraints¶
The integer
type supports validation constraints.
You can specify minimum values and maximum values (both or either):
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.
parameters:
number:
type: number
description: A number
default: 27.5
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):
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.
parameters:
switch_param:
type: boolean
description: A boolean
default: true
switch_param = True