From: Jérôme Benoit Date: Tue, 7 Oct 2025 19:31:54 +0000 (+0200) Subject: docs(README.md): improve tunables documentation X-Git-Url: https://git.piment-noir.org/?a=commitdiff_plain;h=4aacaca2f5606f118afb53a7a89a8a26a77de94d;p=freqai-strategies.git docs(README.md): improve tunables documentation Signed-off-by: Jérôme Benoit --- diff --git a/README.md b/README.md index af07e45..c182672 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,53 @@ Then build and start the container: docker compose up -d --build ``` +### Configuration tunables + +| Path | Default | Type / Range | Description | +|------|---------|-------------|-------------| +| estimated_trade_duration_candles | 48 | int >= 1 | Heuristic for StoplossGuard tuning. | +| _Exit pricing_ | | | | +| exit_pricing.trade_price_target | `moving_average` | enum {`moving_average`,`interpolation`,`weighted_interpolation`} | Trade NATR computation method. | +| exit_pricing.thresholds_calibration.decline_quantile | 0.90 | float (0,1) | PNL decline quantile threshold. | +| _Extrema smoothing_ | | | | +| freqai.extrema_smoothing | `gaussian` | enum {`gaussian`,`kaiser`,`triang`,`smm`,`sma`} | Extrema smoothing kernel (smm=simple moving median, sma=simple moving average). | +| freqai.extrema_smoothing_window | 5 | int >= 1 | Window size for extrema smoothing. | +| freqai.extrema_smoothing_beta | 8.0 | float > 0 | Kaiser kernel shape parameter. | +| _Feature parameters_ | | | | +| freqai.feature_parameters.label_period_candles | 24 | int >= 1 | Zigzag NATR horizon. | +| freqai.feature_parameters.label_natr_ratio | 9.0 | float > 0 | Zigzag NATR ratio. | +| freqai.feature_parameters.min_label_natr_ratio | 9.0 | float > 0 | Minimum NATR ratio bound used by label HPO. | +| freqai.feature_parameters.max_label_natr_ratio | 12.0 | float > 0 | Maximum NATR ratio bound used by label HPO. | +| freqai.feature_parameters.label_frequency_candles | 12 | int >= 2 | Reversals labeling frequency. | +| freqai.feature_parameters.label_metric | `euclidean` | string (supported: `euclidean`,`minkowski`,`cityblock`,`chebyshev`,`mahalanobis`,`seuclidean`,`jensenshannon`,`sqeuclidean`,...) | Metric used in distance calculations to ideal point. | +| freqai.feature_parameters.label_weights | [0.5,0.5] | list[float] | Per-objective weights used in distance calculations to ideal point. | +| freqai.feature_parameters.label_p_order | `None` | float | p-order used by Minkowski / power-mean calculations (optional). | +| freqai.feature_parameters.label_medoid_metric | `euclidean` | string | Metric used with `medoid`. | +| freqai.feature_parameters.label_kmeans_metric | `euclidean` | string | Metric used for k-means clustering. | +| freqai.feature_parameters.label_kmeans_selection | `min` | enum {`min`,`medoid`} | Strategy to select trial in the best kmeans cluster. | +| freqai.feature_parameters.label_kmedoids_metric | `euclidean` | string | Metric used for k-medoids clustering. | +| freqai.feature_parameters.label_kmedoids_selection | `min` | enum {`min`,`medoid`} | Strategy to select trial in the best k-medoids cluster. | +| freqai.feature_parameters.label_knn_metric | `minkowski` | string | Distance metric for KNN. | +| freqai.feature_parameters.label_knn_p_order | `null` | float | p-order for KNN Minkowski metric distance. | +| freqai.feature_parameters.label_knn_n_neighbors | 5 | int >= 1 | Number of neighbors for KNN. | +| _Prediction thresholds_ | | | | +| freqai.prediction_thresholds_smoothing | `mean` | enum {`mean`,`isodata`,`li`,`minimum`,`otsu`,`triangle`,`yen`,`soft_extremum`} | Thresholding method for prediction thresholds smoothing. | +| freqai.prediction_thresholds_alpha | 12.0 | float > 0 | Alpha for `soft_extremum`. | +| freqai.outlier_threshold | 0.999 | float (0,1) | Quantile threshold for predictions outlier filtering. | +| _Optuna / HPO_ | | | | +| freqai.optuna_hyperopt.enabled | true | bool | Enables HPO. | +| freqai.optuna_hyperopt.n_jobs | CPU threads / 4 | int >= 1 | Parallel HPO workers. | +| freqai.optuna_hyperopt.storage | `file` | enum {`file`,`sqlite`} | HPO storage backend. | +| freqai.optuna_hyperopt.continuous | true | bool | Continuous HPO. | +| freqai.optuna_hyperopt.warm_start | true | bool | Warm start HPO with previous best value(s). | +| freqai.optuna_hyperopt.n_startup_trials | 15 | int >= 0 | HPO startup trials. | +| freqai.optuna_hyperopt.n_trials | 50 | int >= 1 | Maximum HPO trials. | +| freqai.optuna_hyperopt.timeout | 7200 | int >= 0 | HPO wall-clock timeout in seconds. | +| freqai.optuna_hyperopt.label_candles_step | 1 | int >= 1 | Step for Zigzag NATR horizon search space. | +| freqai.optuna_hyperopt.train_candles_step | 10 | int >= 1 | Step for training sets size search space. | +| freqai.optuna_hyperopt.expansion_ratio | 0.4 | float [0,1] | HPO search space expansion ratio. | +| freqai.optuna_hyperopt.seed | 1 | int >= 0 | HPO random seed. | + ## ReforceXY ### Quick start @@ -42,7 +89,11 @@ Then build and start the container: docker compose up -d --build ``` -[Reward Space Analysis](./ReforceXY/reward_space_analysis/README.md) +### Configuration tunables + +The documented list of model tunables is at the top of the [ReforceXY.py](./ReforceXY/user_data/freqaimodels/ReforceXY.py) file. + +The rewarding logic and tunables are documented in the [reward space analysis](./ReforceXY/reward_space_analysis/README.md). ## Common workflows diff --git a/ReforceXY/reward_space_analysis/README.md b/ReforceXY/reward_space_analysis/README.md index 83c351a..05c1e4e 100644 --- a/ReforceXY/reward_space_analysis/README.md +++ b/ReforceXY/reward_space_analysis/README.md @@ -700,7 +700,7 @@ Before simulation (early in `main()`), `validate_reward_parameters` enforces num | `holding_penalty_power` | 0.0 | — | Power exponent ≥ 0 | | `exit_linear_slope` | 0.0 | — | Slope ≥ 0 | | `exit_plateau_grace` | 0.0 | — | Plateau grace boundary (full strength until this duration ratio) | -| `exit_power_tau` | 1e-6 | 1.0 | Mapped to alpha = -ln(tau) | +| `exit_power_tau` | 1e-6 | 1.0 | Mapped to alpha = -ln(tau)/ln(2) | | `exit_half_life` | 1e-6 | — | Half-life in duration ratio units | | `efficiency_weight` | 0.0 | 2.0 | Blend weight | | `efficiency_center` | 0.0 | 1.0 | Linear pivot (efficiency ratio center) |