Selectable Types
The select
and multi_select
methods enable categorical parameter configuration. These methods support both single and multiple value selection with flexible validation options.
I'll help improve the documentation for the select and multi_select parameters by adding the requested information. Here's the enhanced version:
Select & Multi_select Parameters
The select
and multi_select
methods enable categorical parameter configuration using either lists or dictionaries. These methods support both single and multiple value selection with flexible validation options.
Function Signatures
select
def select(
options: Union[Dict[ValidKeyType, Any], List[ValidKeyType]],
*,
name: str,
default: Optional[ValidKeyType] = None,
options_only: bool = False
) -> Any
multi_select
def multi_select(
options: Union[Dict[ValidKeyType, Any], List[ValidKeyType]],
*,
name: str,
default: List[ValidKeyType] = None,
options_only: bool = False
) -> List[Any]
Parameters
options
: Either a list of valid values or a dictionary mapping keys to valuesdefault
: Default value(s) if none provided (single value for select, list for multi_select)options_only
: When True, only allows values from the predefined options
Pre-defined Parameter Forms
List Form
Use when the parameter keys and values are identical:
from hypster import HP, instantiate
def model_config(hp: HP):
# Single selection from list
model_type = hp.select(["haiku", "sonnet"], name="model_type", default="haiku")
# Multiple selection from list
features = hp.multi_select(["price", "size", "color"], name="features", default=["price", "size"])
return {
"model_type": model_type,
"features": features
}
# Usage
cfg = instantiate(model_config, values={"model_type": "sonnet", "features": ["price", "color"]})
Dictionary Form
Use when parameter keys need to map to different values:
from hypster import HP, instantiate
def llm_config(hp: HP):
# Single selection with value mapping
model = hp.select({
"haiku": "claude-3-haiku-20240307",
"sonnet": "claude-3-sonnet-20240229"
}, name="model", default="haiku")
# Multiple selection with object mapping
callbacks = hp.multi_select({
"cost": cost_callback,
"runtime": runtime_callback
}, name="callbacks", default=["cost"])
return {
"model": model,
"callbacks": callbacks
}
# Usage
cfg = instantiate(llm_config, values={"model": "sonnet", "callbacks": ["cost", "runtime"]})
Value Resolution
When using dictionary form, the configuration system maps input keys to their corresponding values:
from hypster import HP, instantiate
def my_config(hp: HP):
# Configuration definition with dictionary mapping
model = hp.select({
"haiku": "claude-3-haiku-20240307",
"sonnet": "claude-3-sonnet-20240229"
}, name="model", default="haiku")
return {"model": model}
# Usage - keys are mapped to their values
config1 = instantiate(my_config, values={"model": "haiku"})
# config1 -> {"model": "claude-3-haiku-20240307"}
config2 = instantiate(my_config, values={"model": "sonnet"})
# config2 -> {"model": "claude-3-sonnet-20240229"}
When to Use Dictionary Form?
Dictionary form is recommended when working with:
Long string values:
{"haiku": "claude-3-haiku-20240307"}
Precise numeric values:
{"small": 1.524322}
Object references:
{"rf": RandomForest(n_estimators=100)}
None values:
{"none": None}
Complex objects like tuples:
{"small": (1, 2)}
Special Value Examples
Dictionary form enables you to define None values and complex objects that cannot be easily represented in list form:
from hypster import HP, instantiate
def nlp_config(hp: HP):
# None values - useful for optional parameters
tokenizer = hp.select({
"none": None,
"basic": "basic_tokenizer",
"advanced": "advanced_tokenizer"
}, name="tokenizer", default="none")
# N-gram ranges as tuples
ngram_range = hp.select({
"unigram": (1, 1),
"bigram": (1, 2),
"trigram": (1, 3)
}, name="ngram_range", default="bigram")
# Complex objects like lists or dicts
model_params = hp.select({
"small": {"layers": 2, "units": [64, 32]},
"large": {"layers": 4, "units": [256, 128, 64, 32]}
}, name="model_params", default="small")
return {
"tokenizer": tokenizer,
"ngram_range": ngram_range,
"model_params": model_params
}
# Usage examples
cfg1 = instantiate(nlp_config)
# cfg1 -> {"tokenizer": None, "ngram_range": (1, 2), "model_params": {"layers": 2, "units": [64, 32]}}
cfg2 = instantiate(nlp_config, values={"tokenizer": "advanced", "ngram_range": "trigram"})
# cfg2 -> {"tokenizer": "advanced_tokenizer", "ngram_range": (1, 3), "model_params": {"layers": 2, "units": [64, 32]}}
Default Values
The default
parameter must be a valid option from the predefined choices. For dictionary form, the default must be one of the keys (not values).
List Form Defaults
When using list form, the default must be one of the items in the list:
# Valid defaults
model = hp.select(["haiku", "sonnet"], default="haiku") # OK: "haiku" is in list
features = hp.multi_select(["price", "size"], default=["price", "size"]) # OK: "price" and "size" are in list
# Invalid defaults - will raise errors
model = hp.select(["haiku", "sonnet"], default="opus") # Error: "opus" not in list
features = hp.multi_select(["price", "size"], default=["color"]) # Error: "color" not in list
Dictionary Form Defaults
When using dictionary form, the default must be one of the dictionary keys:
# Valid defaults
model = hp.select({
"haiku": "claude-3-haiku-20240307",
"sonnet": "claude-3-sonnet-20240229"
}, default="haiku") # OK: "haiku" is a key
callbacks = hp.multi_select({
"cost": cost_callback,
"runtime": runtime_callback
}, default=["cost"]) # OK: "cost" is a key
# Invalid defaults - will raise errors
model = hp.select({
"haiku": "claude-3-haiku-20240307",
"sonnet": "claude-3-sonnet-20240229"
}, default="claude-3-haiku-20240307") # Error: using value instead of key
callbacks = hp.multi_select({
"cost": cost_callback,
"runtime": runtime_callback
}, default=["timing"]) # Error: "timing" is not a key
Instantiating With Missing Default Values
If no default is provided, a value must be specified during configuration:
# No default provided
model = hp.select(["haiku", "sonnet"])
# Must provide value during configuration
config = my_config(values={"model": "haiku"}) # OK
config = my_config() # Error: no default and no value provided
Value Validation
The options_only
parameter determines how strictly values are validated:
# Flexible validation - allows any value (default)
model = hp.select(["haiku", "sonnet"], options_only=False)
# Strict validation - only predefined options allowed
model = hp.select(["haiku", "sonnet"], options_only=True)
Valid Instantiation Examples
from hypster import HP, instantiate
def my_config(hp: HP):
model_type = hp.select(["haiku", "sonnet"], name="model_type", options_only=False)
return {"model_type": model_type}
# Using predefined values
cfg1 = instantiate(my_config, values={"model_type": "haiku"})
# Using custom values (when options_only=False)
cfg2 = instantiate(my_config, values={"model_type": "claude-3-opus-20240229"})
Invalid Instantiation Examples
def strict_config(hp: HP):
model_type = hp.select(["haiku", "sonnet"], name="model_type", options_only=True)
return {"model_type": model_type}
# This will raise an error - value not in options list when options_only=True
cfg = instantiate(strict_config, values={"model_type": "claude-3-opus-20240229"})
Required Name Parameter
All hp.*
calls that you want to be overrideable must include an explicit name="..."
argument.
# Correct usage - explicit names
model_type = hp.select(["haiku", "sonnet"], name="model_type")
features = hp.multi_select(["price", "size", "color"], name="features")
# Incorrect usage - missing names (will raise error)
model_type = hp.select(["haiku", "sonnet"]) # Error: missing name
features = hp.multi_select(["price", "size", "color"]) # Error: missing name
Last updated
Was this helpful?