Configuration Guide

Master parameter persistence, configuration files, and value priority in EZInput

Value Persistence Basics

EZInput automatically remembers widget values between sessions. This is perfect for iterative workflows where you're tuning parameters. 

from ezinput import EZInput

# First run - user enters values
gui = EZInput("my_analysis")
threshold = gui.add_float_range("thresh", "Threshold:", 0.0, 1.0)
iterations = gui.add_int_range("iter", "Iterations:", 10, 1000)
gui.show()

# User enters: threshold=0.75, iterations=500

# --------------------------------------------------

# Second run (next day) - values are remembered!
gui = EZInput("my_analysis")  # Same title = same config
threshold = gui.add_float_range("thresh", "Threshold:", 0.0, 1.0)
iterations = gui.add_int_range("iter", "Iterations:", 10, 1000)
gui.show()

# Defaults are now: threshold=0.75, iterations=500 ✨

🔑 Key Points

  • Persistence is based on the GUI title (first parameter to EZInput())
  • Values are stored in ~/.ezinput/{title}.yml
  • Each widget is identified by its unique_tag
  • Works across both Jupyter and terminal environments

Controlling Value Memory

Use the remember_value parameter (defaults to True) to control which values persist: 

gui = EZInput("preprocessing")

# These values change frequently (don't remember)
input_file = gui.add_text("input", "Input file:", remember_value=False)
output_dir = gui.add_text("output", "Output directory:", remember_value=False)

# These are stable parameters (remember them - this is the default)
method = gui.add_dropdown("method", ["watershed", "otsu"], "Method:", 
                          remember_value=True)
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, 
                                remember_value=True)

gui.show()

# Next time: method and threshold are remembered, 
# but input/output need to be re-entered

When to use remember_value=True (default):

When to use remember_value=False:

Configuration Files

Saving Configurations

gui = EZInput("cell_segmentation")

# Add widgets
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)
min_size = gui.add_int_range("min_size", "Min size:", 10, 1000)
method = gui.add_dropdown("method", ["otsu", "adaptive"], "Method:")

gui.show()

# User enters optimal values...

# Save current configuration
gui.save_parameters("optimal_settings.yml")

# Or specify full path
gui.save_parameters("/path/to/configs/experiment1.yml")

Loading Configurations

gui = EZInput("cell_segmentation")

# Load saved configuration
gui.load_parameters("optimal_settings.yml")

# Add widgets (values from file will be used)
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)
min_size = gui.add_int_range("min_size", "Min size:", 10, 1000)
method = gui.add_dropdown("method", ["otsu", "adaptive"], "Method:")

gui.show()

# Widgets now have values from optimal_settings.yml!

📁 Default Configuration Location

Configuration files are stored in:

~/.ezinput/{title}.yml

Where {title} is the name you passed to EZInput().

Example:

gui = EZInput("image_analysis_v2")
# Config saved to: ~/.ezinput/image_analysis_v2.yml

Configuration File Format

EZInput uses YAML format for configuration files. Here's what a config file looks like:

# ~/.ezinput/my_analysis.yml

thresh:
  value: 0.75
  type: float

method:
  value: watershed
  type: str

min_size:
  value: 250
  type: int

use_gpu:
  value: true
  type: bool

You can manually edit these files or share them with colleagues!

Value Priority Order

When multiple sources provide values for a widget, EZInput follows this priority:

  1. Loaded parameters (highest priority)
    Values from load_parameters()
  2. Remembered values
    From previous sessions using remember_value=True parameter
  3. Explicit defaults
    Passed to widget methods (e.g., default=0.5)
  4. Widget defaults (lowest priority)
    Built-in fallback values

Priority Examples

# Example 1: Loaded parameters override everything
gui = EZInput("test")
gui.load_parameters("config.yml")  # Contains thresh=0.9

# This default is ignored because config.yml has thresh=0.9
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, default=0.5)

gui.show()
# Result: threshold defaults to 0.9 (from config.yml)
# Example 2: Remembered values override explicit defaults
# Previous run: user entered thresh=0.75
gui = EZInput("test")
gui.remember_value("thresh")

# This default is ignored because remembered value exists
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, default=0.5)

gui.show()
# Result: threshold defaults to 0.75 (remembered from before)
# Example 3: Explicit defaults override widget defaults
gui = EZInput("test")

# Uses your explicit default (no config file, not remembered)
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, default=0.8)

gui.show()
# Result: threshold defaults to 0.8 (explicit default)
# Example 4: Widget defaults (last resort)
gui = EZInput("test")

# No config, not remembered, no explicit default
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)

gui.show()
# Result: threshold defaults to 0 (min_val is the widget default)

Sharing Configuration Files

Configuration files are perfect for sharing parameter sets with collaborators or across projects.

Workflow Example

# Researcher 1: Find optimal parameters
gui = EZInput("cell_analysis")
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)
min_size = gui.add_int_range("min_size", "Min size:", 10, 1000)
gui.show()

# After experimentation, save optimal settings
gui.save_parameters("optimal_cell_params.yml")

# Share optimal_cell_params.yml with team

# --------------------------------------------------

# Researcher 2: Use the optimal parameters
gui = EZInput("cell_analysis")
gui.load_parameters("optimal_cell_params.yml")
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)
min_size = gui.add_int_range("min_size", "Min size:", 10, 1000)
gui.show()

# Automatically starts with optimal values! 🎉

Version Control Best Practices

  • Commit configuration files to git for reproducibility
  • Use descriptive names: optimal_params_v2.yml, production_config.yml
  • Document what each config is for in comments or README
  • Keep separate configs for different experiments/datasets
  • Add ~/.ezinput/ to .gitignore (personal settings)
  • Store shared configs in your project directory

Managing Multiple Configurations 

from ezinput import EZInput

# Different configs for different scenarios
configs = {
    "fast": "fast_preview.yml",
    "balanced": "balanced_quality.yml",
    "high_quality": "high_quality.yml"
}

# Let user select config
gui = EZInput("config_selector")
config_choice = gui.add_dropdown("config", list(configs.keys()), 
                                 "Quality preset:")
gui.show()

# Load selected config
analysis_gui = EZInput("image_analysis")
analysis_gui.load_parameters(configs[config_choice.value])

# Add widgets (values from selected config)
threshold = analysis_gui.add_float_range("thresh", "Threshold:", 0, 1)
iterations = analysis_gui.add_int_range("iter", "Iterations:", 10, 1000)
analysis_gui.show()

Resetting to Default Values

The restore_defaults() method clears all remembered values, returning widgets to their original defaults.

⚠️ Important: Re-execution Required

In Jupyter: You must re-run the cell containing your widgets after calling restore_defaults().
In Terminal: You must re-run your script after calling restore_defaults().

The method removes the memory file (~/.ezinput/{title}.yml), but the widgets won't visually change until you re-execute the code that creates them.

Basic Usage

from ezinput import EZInput

gui = EZInput("my_analysis")

# Add widgets with remember_value=True parameter
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, 
                                default=0.5, remember_value=True)
method = gui.add_dropdown("method", ["A", "B", "C"], "Method:", 
                          default="A", remember_value=True)

gui.show()

# After user runs multiple times with different values...
# Clear all remembered values
gui.restore_defaults()

print("✓ Remembered values cleared!")
print("🔄 Re-run this cell/script to see default values restored.")

Workflow Example (Jupyter)

# Cell 1: Initial setup with remembered values
from ezinput import EZInput

gui = EZInput("experiment")
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, 
                                default=0.5, remember_value=True)
gui.show()

# User sets threshold=0.8, runs analysis multiple times...
# threshold.value is now remembered as 0.8

# Cell 2: Reset to defaults
gui.restore_defaults()  # Deletes ~/.ezinput/experiment.yml

# Cell 3: Re-run Cell 1 to see defaults
# NOW when you re-run Cell 1, threshold will default to 0.5 again!

Workflow Example (Terminal Script)

# analyze.py
from ezinput import EZInput
import sys

if len(sys.argv) > 1 and sys.argv[1] == "--reset":
    # User ran: python analyze.py --reset
    gui = EZInput("analysis")
    gui.restore_defaults()
    print("✓ Defaults restored!")
    print("🔄 Run 'python analyze.py' again to use default values.")
    sys.exit(0)

# Normal execution
gui = EZInput("analysis")
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1, 
                                default=0.5, remember_value=True)
gui.show()

# Run analysis with threshold.value...

# Usage:
# python analyze.py          # Normal run (uses remembered values)
# python analyze.py --reset  # Clear remembered values
# python analyze.py          # Next run uses defaults again

💡 When to Use restore_defaults()

  • Starting a fresh experiment with clean parameters
  • Testing your GUI with original default values
  • Removing accumulated remembered values from development
  • Providing a "reset" option in your scripts
  • Debugging when values seem stuck at unexpected defaults

Configuration Best Practices

✅ Do

  • Use descriptive GUI titles
  • Version your configurations
  • Document what configs are for
  • Use remember_value=True parameter for stable params
  • Share configs in version control
  • Test loaded configs before using

❌ Don't

  • Use generic titles like "test" or "gui"
  • Remember file paths (they change)
  • Hardcode config paths
  • Forget to handle missing config files
  • Mix different GUIs with same title
  • Ignore value priority rules

Advanced: Programmatic Configuration Access 

from ezinput import EZInput

gui = EZInput("advanced")

# Add widgets
threshold = gui.add_float_range("thresh", "Threshold:", 0, 1)
method = gui.add_dropdown("method", ["A", "B"], "Method:")

gui.show()

# Get all current values as dict
values = gui.get_values()
print(f"Threshold: {values['thresh'].value}")
print(f"Method: {values['method'].value}")

# Access individual widgets
threshold_widget = gui["thresh"]
print(f"Current threshold: {threshold_widget.value}")

# Update values programmatically
gui["thresh"].value = 0.8

# Save current state
gui.save_parameters("current_state.yml")