Merge pull request #214 from MilesCranmer/organize-params-list

docs/_api.md

@@ -0,0 +1,64 @@
+# PySRRegressor Reference
+
+`PySRRegressor` has many options for controlling a symbolic regression search.
+Let's look at them below.
+
+PARAMSKEY
+
+## PySRRegressor Functions
+        
+::: pysr.PySRRegressor.fit
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.predict
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.from_file
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.sympy
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.latex
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.pytorch
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.jax
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.latex_table
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+::: pysr.PySRRegressor.refresh
+    options:
+        show_root_heading: true
+        heading_level: 3
+        show_root_full_path: false
+
+

docs/api.md

@@ -1,16 +0,0 @@
-# PySRRegressor Reference
-
-::: pysr.PySRRegressor
-    options:
-        members:
-            - fit
-            - predict
-            - from_file
-            - sympy
-            - latex
-            - pytorch
-            - jax
-            - latex_table
-            - refresh
-        show_root_members_full_path: true
-        heading_level: 2

docs/gen_docs.sh

@@ -1,8 +1,8 @@
 #!/bin/bash -e
 
 # Generate home page using README.md:
-echo '<div style="width:100%;height:0px;position:relative;padding-bottom:56.250%;"><iframe src="https://streamable.com/e/ncvqhy" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe></div>' > index.md
-cat ../README.md | grep -v 'user-images' | grep -E -v '\<.*div.*\>' >> index.md
+echo '<div style="width:100%;height:0px;position:relative;padding-bottom:56.250%;"><iframe src="https://streamable.com/e/ncvqhy" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe></div>' >index.md
+cat ../README.md | grep -v 'user-images' | grep -E -v '\<.*div.*\>' >>index.md
 
 # Transform "### Test status" to "**Test status**":
 sed -i.bak 's/\#\#\# Test status/**Test status**/g' index.md
@@ -10,4 +10,10 @@ sed -i.bak 's/\#\#\# Test status/**Test status**/g' index.md
 sed -i.bak '10,$s/^\# /## /g' index.md
 
 # Create papers.md
-python generate_papers.py
+python generate_papers.py
+
+# Copy _api.md up to but not including PARAMSKEY and all tex after:
+cat _api.md | sed -n '1,/PARAMSKEY/p' | sed '$d' >api.md
+python gen_param_docs.py >> api.md
+# Copy _api.md after PARAMSKEY:
+cat _api.md | sed -n '/PARAMSKEY/,$p' | sed '1d' >>api.md

docs/gen_param_docs.py

@@ -0,0 +1,67 @@
+# Load YAML file param_groupings.yml:
+from pathlib import Path
+from yaml import safe_load
+import sys
+
+sys.path.append("..")
+from pysr import PySRRegressor
+import pysr
+import re
+from docstring_parser import parse
+
+found_params = []
+
+
+def str_param_groups(param_groupings, params, cur_heading=2):
+    global found_params
+    # Recursively print the parameter descriptions, defaults,
+    # with headings from the param groupings dict.
+    if isinstance(param_groupings, list):
+        return "\n\n".join(
+            str_param_groups(param, params, cur_heading) for param in param_groupings
+        )
+    elif isinstance(param_groupings, dict):
+        for heading, param_grouping in param_groupings.items():
+            return (
+                f"{'#' * cur_heading} {heading}"
+                + "\n\n"
+                + str_param_groups(param_grouping, params, cur_heading + 1)
+            )
+    elif isinstance(param_groupings, str):
+        found_params.append(param_groupings)
+
+        clean_desc = re.sub(r"Default is .*", "", params[param_groupings].description)
+        default_value = re.search(
+            r"Default is `(.*)`", params[param_groupings].description
+        )
+        return (
+            f"**`{param_groupings}`**"
+            + "\n\n"
+            + clean_desc
+            + ("\n" + f"*Default:* `{default_value.group(1)}`" if default_value else "")
+        )
+    else:
+        raise TypeError(f"Unexpected type {type(param_groupings)}")
+
+
+if __name__ == "__main__":
+    # This is the path to the param_groupings.yml file
+    # relative to the current file.
+    path = "param_groupings.yml"
+    with open(path, "r") as f:
+        param_groupings = safe_load(f)
+
+    # This is basically a dict of lists and dicts.
+
+    # Let's load in the parameter descriptions from the docstring of PySRRegressor:
+    raw_params = parse(PySRRegressor.__doc__).params
+    params = {
+        param.arg_name: param
+        for param in raw_params
+        if param.arg_name[-1] != "_" and param.arg_name != "**kwargs"
+    }
+
+    output = str_param_groups(param_groupings, params, cur_heading=3)
+    assert len(set(found_params) ^ set(params.keys())) == 0
+    print("## PySRRegressor Parameters")
+    print(output)

docs/param_groupings.yml

@@ -0,0 +1,89 @@
+- The Algorithm:
+  - Creating the Search Space:
+    - binary_operators
+    - unary_operators
+    - maxsize
+    - maxdepth
+  - Setting the Search Size:
+    - niterations
+    - populations
+    - population_size
+    - ncyclesperiteration
+  - The Objective:
+    - loss
+    - model_selection
+    - Working with Complexities:
+      - parsimony
+      - constraints
+      - nested_constraints
+      - complexity_of_operators
+      - complexity_of_constants
+      - complexity_of_variables
+      - warmup_maxsize_by
+      - use_frequency
+      - use_frequency_in_tournament
+  - Mutations:
+    - weight_add_node
+    - weight_insert_node
+    - weight_delete_node
+    - weight_do_nothing
+    - weight_mutate_constant
+    - weight_mutate_operator
+    - weight_randomize
+    - weight_simplify
+    - crossover_probability
+    - annealing
+    - alpha
+    - perturbation_factor
+    - skip_mutation_failures
+  - Tournament Selection:
+    - tournament_selection_n
+    - tournament_selection_p
+  - Constant Optimization:
+    - optimizer_algorithm
+    - optimizer_nrestarts
+    - optimize_probability
+    - optimizer_iterations
+    - should_optimize_constants
+  - Migration between Populations:
+    - fraction_replaced
+    - fraction_replaced_hof
+    - migration
+    - hof_migration
+    - topn
+- Data Preprocessing:
+  - denoise
+  - select_k_features
+- Stopping Criteria:
+  - max_evals
+  - timeout_in_seconds
+  - early_stop_condition
+- Performance and Parallelization:
+  - procs
+  - multithreading
+  - cluster_manager
+  - batching
+  - batch_size
+  - precision
+  - fast_cycle
+  - turbo
+  - random_state
+  - deterministic
+  - warm_start
+- Monitoring:
+  - verbosity
+  - update_verbosity
+  - progress
+- Environment:
+  - temp_equation_file
+  - tempdir
+  - delete_tempfiles
+  - julia_project
+  - update
+- Exporting the Results:
+  - equation_file
+  - output_jax_format
+  - output_torch_format
+  - extra_sympy_mappings
+  - extra_torch_mappings
+  - extra_jax_mappings