Support algorithms

[yannrichet-asnr]

This commit adds support for using pandas DataFrames as input_variables,
enabling non-factorial parametric study designs alongside the existing
dict-based factorial (Cartesian product) approach.

Implementation (fz/helpers.py):

• Updated generate_variable_combinations() to detect DataFrame input
• DataFrame: each row represents one case (non-factorial design)
• Dict: existing Cartesian product behavior (factorial design)
• Added optional pandas import with HAS_PANDAS flag
• Enhanced type hints and docstring with examples
• Added informative logging when DataFrame detected
• Raises TypeError for invalid input types

Key features:

• Factorial design (dict): Creates ALL combinations (Cartesian product)
  Example: {"x": [1,2], "y": [3,4]} → 4 cases
• Non-factorial design (DataFrame): Only specified combinations
  Example: pd.DataFrame({"x":[1,2], "y":[3,4]}) → 2 cases (rows)

Use cases for DataFrames:

• Variables with constraints or dependencies
• Latin Hypercube Sampling, Sobol sequences
• Imported designs from DOE software
• Optimization algorithm sample points
• Sensitivity analysis (one-at-a-time)
• Sparse or adaptive sampling
• Any irregular design pattern

Tests (tests/test_dataframe_input.py):

• 12 comprehensive tests covering all scenarios
• Unit tests for generate_variable_combinations()
• Integration tests with fzr()
• Tests for DataFrame vs dict behavior comparison
• Tests for mixed types, constraints, repeated values
• Input validation tests
• All 12 tests pass successfully

Documentation:

• README.md: New "Input Variables: Factorial vs Non-Factorial Designs" section
  • Comparison of dict (factorial) vs DataFrame (non-factorial)
  • When to use each approach
  • Examples with LHS, constraint-based designs
• examples/dataframe_input.md: Comprehensive guide with:
  • 7 practical examples (constraints, LHS, Sobol, DOE import, etc.)
  • Comparison table
  • Tips and best practices
  • Common patterns and workflows
• Updated Features section to mention both design types
• Updated DataFrame I/O description

Backward compatibility:

• Existing dict-based code continues to work unchanged
• DataFrame support requires pandas (optional dependency)
• Graceful handling when pandas not installed

Example usage:

import pandas as pd
from fz import fzr

# Non-factorial: specific combinations only
input_variables = pd.DataFrame({
    "temp": [100, 200, 100, 300],
    "pressure": [1.0, 1.0, 2.0, 1.5]
})
# Creates 4 cases: (100,1.0), (200,1.0), (100,2.0), (300,1.5)

results = fzr(input_file, input_variables, model, calculators)

[Copilot]

Pull Request Overview

Adds support for pandas DataFrame input to enable non-factorial (row-wise) parametric designs alongside existing dict-based factorial Cartesian product generation.

• Extends generate_variable_combinations to accept DataFrames and return one case per row.
• Adds comprehensive tests and documentation/examples differentiating factorial dict vs non-factorial DataFrame usage.
• Updates README and adds a detailed example guide for DataFrame-driven designs.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
fz/helpers.py	Implements DataFrame handling in generate_variable_combinations with optional pandas import and logging.
tests/test_dataframe_input.py	Adds unit and integration tests for DataFrame vs dict behavior and input validation.
examples/dataframe_input.md	New extensive guide on using DataFrames for non-factorial designs with multiple sampling patterns.
README.md	Updates feature list and documents factorial vs non-factorial input variable formats with examples.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The type hint Union[Dict, Any] effectively collapses to Any and advertises acceptance of all types, while the function raises TypeError for non-dict/non-DataFrame inputs. Narrow the annotation to accepted types only, e.g. Union[Dict[str, Any], 'pd.DataFrame'] guarded by a TYPE_CHECKING block or a Protocol to improve static analysis.

[Copilot]

Using iterrows is relatively slow and may coerce dtypes; you can replace this block with var_combinations = input_variables.to_dict(orient='records') for a vectorized, faster conversion that preserves dtypes.

Suggested change

	var_combinations = []
	for _, row in input_variables.iterrows():
	var_combinations.append(row.to_dict())
	var_combinations = input_variables.to_dict(orient='records')

[Copilot]

Each line has a double leading pipe '||', which will render an extra empty column or break the table. Remove one leading pipe per line so the table starts with a single | (e.g. | Aspect | Dict (Factorial) | DataFrame (Non-Factorial) |).

Suggested change

[Copilot]

[nitpick] The same model dict is duplicated across multiple tests (e.g., lines 171–178, 201–208, 257–263). Consider extracting it into a fixture or a class attribute to reduce repetition and ease future changes.