parsnip extract_parameter_dials() in R: Get Tuning Ranges

The parsnip extract_parameter_dials() function in R returns a single dials parameter object, such as trees() or mtry(), pulled from one tunable argument of a model specification, recipe, or workflow.

extract_parameter_dials(spec, "trees")        # one param from a model spec
extract_parameter_dials(rec, "num_comp")      # one param from a recipe
extract_parameter_dials(wf, "penalty")        # one param from a workflow
extract_parameter_dials(pset, "min_n")        # one param from a parameter set
finalize(extract_parameter_dials(spec, "mtry"), df)  # resolve a [1, ?] range
extract_parameter_set_dials(spec)             # every tunable param at once

What extract_parameter_dials() does

extract_parameter_dials() returns the dials object that controls one tunable argument. When you tag a model argument with tune(), parsnip records that the argument is unknown and must be searched. extract_parameter_dials() looks up which dials parameter governs that argument and hands it back, ready to inspect or modify.

A dials parameter object carries the search space for tuning: a numeric range, a scale (linear or log), and a human-readable label. For trees that is the integer range [1, 2000]. For penalty it is a log-scaled range. You reach for this object whenever you want to see, or change, the values a tuning grid will draw from.

The function is an S3 generic from the hardhat package. The tune package supplies the methods for model_spec, recipe, workflow, and parameters objects, so the same call works at every layer of a tidymodels pipeline. Because this page is parsnip-focused, the examples below pass a parsnip model_spec.

extract_parameter_dials() syntax and arguments

The signature has two arguments because the function locates one parameter and returns it unchanged. It is an S3 generic, so the method that runs depends on the class of x.

The return value is one dials parameter object whose class is quant_param (numeric) or qual_param (categorical). If x has no tunable parameter with that id, the function returns a logical NA rather than raising an error.

The argument must already be tagged with tune(). A fully specified spec has nothing to extract, because extract_parameter_dials() reads the tuning tags, not the engine defaults. See the official hardhat extract reference for the full method list.

Extract tuning parameters: four examples

Each example below uses a built-in dataset and a different kind of parameter. Start by tagging two arguments of a boosted tree for tuning, then pull one of them out.

Some parameters have a range that depends on the data. mtry cannot exceed the number of predictors, so its upper bound prints as ? until you resolve it with finalize().

Parameters can also live on a transformed scale. A regularization penalty is searched on a log-10 scale, which the returned object reports directly.

Because the result is a real dials object, you can edit its range and feed it straight into a grid builder.

extract_parameter_dials() vs extract_parameter_set_dials()

Use extract_parameter_dials() for one parameter and extract_parameter_set_dials() for all of them. The plural function returns the whole tuning blueprint; the singular function drills into one row of it.

The set is what you finalize and pass to tune_grid(). The single object is what you inspect or hand-tune when one parameter needs a custom range.

Common pitfalls

Most failures trace back to a parameter that was never tagged for tuning. These three mistakes account for nearly every confusing result.

Extracting an argument that holds a fixed value returns NA, because there is no tuning tag to read.

When you give tune() a custom id, you must extract by that id, not the argument name.

Building a grid from a parameter with an unresolved range fails. Call finalize() first.

Try it yourself

Related parsnip and tune functions

These functions sit next to extract_parameter_dials() in a tidymodels tuning workflow. Reach for them when you need a whole set, a finalized range, or the fitted model.

• extract_parameter_set_dials(): returns every tunable parameter as one parameters set.
• finalize(): resolves data-dependent ranges such as mtry to concrete bounds.
• grid_regular(): turns parameter objects into a tuning grid.
• extract_fit_engine(): pulls the raw engine model from a fitted object, not a tuning range.
• set_engine() and boost_tree(): build the spec you extract parameters from.

FAQ

What does extract_parameter_dials() return?

It returns one dials parameter object describing the search space for a single tunable argument. The object holds a range, a label, and a scale, and prints as something like Trees (quantitative) Range: [1, 2000]. The class is quant_param for numeric parameters and qual_param for categorical ones. You can inspect it, edit its range with range_set(), or pass it to a grid function.

Why does extract_parameter_dials() return NA?

A logical NA means the object has no tunable parameter with the id you asked for. The usual cause is an argument that holds a fixed value instead of a tune() tag, so there is nothing to extract. The second cause is an id mismatch: if you wrote tune("my_id"), you must extract by "my_id", not the argument name. Check the spec with extract_parameter_set_dials() to see the valid ids.

What is the difference between extract_parameter_dials() and extract_parameter_set_dials()?

extract_parameter_dials() returns one parameter object and needs a parameter id. extract_parameter_set_dials() returns the whole parameters set and takes no id. Use the set to build or finalize a complete tuning grid, and use the single object when one parameter needs a hand-tuned range before it joins the grid.

Do I need the tune package to use extract_parameter_dials()?

Yes, for parsnip objects. The generic is defined in hardhat, but the method for a model_spec is registered by tune. Load library(tune) or library(tidymodels) before calling it on a parsnip spec, otherwise R cannot find the method and falls back to a default that returns NA.