.. image:: https://rbturnbull.github.io/psyop/_images/psyop-banner.jpg
.. start-badges
|testing badge| |coverage badge| |docs badge| |black badge|
.. |testing badge| image:: https://github.com/rbturnbull/psyop/actions/workflows/testing.yml/badge.svg
:target: https://github.com/rbturnbull/psyop/actions
.. |docs badge| image:: https://github.com/rbturnbull/psyop/actions/workflows/docs.yml/badge.svg
:target: https://rbturnbull.github.io/psyop
.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |coverage badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/rbturnbull/d3a9e5f1b7d7b8593c9df1cd46fe7557/raw/coverage-badge.json
:target: https://rbturnbull.github.io/psyop/coverage/
.. end-badges
.. start-quickstart
Installation
==================================
Install using pip:
.. code-block:: bash
pip install psyop
Or
.. code-block:: bash
pip install git+https://github.com/rbturnbull/psyop.git
.. warning::
Psyop is currently in alpha testing phase. More updates are coming soon.
Quick help
----------
.. code-block:: bash
psyop --help
psyop <command> --help
Model artifact
--------------
Most commands take a path to a ``.nc`` artifact produced by ``psyop model``.
The artifact bundles:
- raw columns (for plotting & metadata),
- standardized design matrices,
- per-feature transforms & standardization stats,
- two GP heads (success probability; expected target conditional on success),
- convenience predictions and metadata (direction, seed, etc.).
Constraint syntax (used by ``suggest``, ``optimal``, ``plot2d``, ``plot1d``)
-----------------------------------------------------------------------------
These commands accept **extra CLI options** that are *not predeclared*—they are parsed
into **feature constraints**. Constraints are always interpreted in **original units**
(before any internal log/standardization).
Pass any mix of:
- **Fixed value** *(number)* — clamp a feature at a single value and (for plots) remove it from the axes:
.. code-block:: bash
--epochs 20
--learning-rate 0.001
- **Range** *(slice)* — inclusive lower/upper bound:
.. code-block:: bash
--dropout 0.0:0.2
--x 0..2 # same as 0:2
--width 64:512:64 # optional step token; used where applicable
- **Choices** *(finite set)* — list/tuple or Python-like ``range()`` call:
.. code-block:: bash
--batch-size "(16, 32, 64)"
--optimizer "[adam, sgd, adamw]"
--layers "range(2,8,2)" # -> (2, 4, 6, 8)
Rules:
- Unknown keys are ignored with a warning (feature names are matched case-insensitively; hyphens/underscores are normalized).
- If you pass both a fixed value and a range/choices for the same feature, the **fixed value wins**.
- For **suggest**/**optimal**, bounds/choices are enforced strictly when sampling candidates.
- For **plot2d**/**plot1d**, fixed features are **clamped** and **not shown** on axes; range constraints **restrict the sweep domain** even if historical points exist outside the range.
Tip (shells): quote lists/tuples and anything that contains commas or parentheses to avoid shell expansion.
Commands
========
1) Fit a model
--------------
.. code-block:: bash
psyop model INPUT.csv OUTPUT.nc [OPTIONS]
**Arguments**
- ``INPUT`` *(CSV)* — your experiment log.
- ``OUTPUT`` *(.nc)* — where to save the model artifact.
**Options**
- ``--target, -t TEXT`` — target column name (default: ``loss``).
- ``--exclude TEXT`` — repeatable; columns to exclude from features.
- ``--direction, -d [min|max|auto]`` — optimization direction for the target (default: ``auto``).
- ``--success-column TEXT`` — optional boolean/int column; if omitted, success is inferred as ``~isna(target)``.
- ``--seed INTEGER`` — RNG seed (default: 0).
- ``--compress / --no-compress`` — compress numeric arrays inside the artifact (default: on).
**Example**
.. code-block:: bash
psyop model runs.csv output/trials.nc \
--target loss --exclude run_id --exclude notes --direction auto --seed 42
2) Suggest candidates (constrained EI + exploration)
----------------------------------------------------
.. code-block:: bash
psyop suggest MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]
**Options**
- ``--output, -o PATH`` — write suggestions CSV (if omitted, prints the table).
- ``--count, -k INTEGER`` — number of suggestions (default: 10).
- ``--p-success-threshold FLOAT`` — feasibility threshold in cEI (default: 0.8).
- ``--explore FLOAT`` — fraction of suggestions reserved for exploration (default: 0.34).
- ``--candidates-pool INTEGER`` — random candidate pool size to score (default: 5000).
- ``--seed INTEGER`` — RNG seed (default: 0).
**Constraints** — see *Constraint syntax* above.
**Output CSV columns**
``rank``, feature columns, ``pred_p_success``, ``pred_target_mean``, ``pred_target_sd``,
``acq_cEI``, ``acq_explore``, ``novelty_norm``, ``direction``, ``conditioned_on``.
**Examples**
.. code-block:: bash
# Fix epochs; bound dropout
psyop suggest output/trials.nc --epochs 20 --dropout 0.0:0.2 -k 12 -o output/suggest.csv
# Discrete choices and integer grid:
psyop suggest output/trials.nc \
--batch-size "(16, 32, 64)" \
--layers "range(2,8,2)" \
--optimizer "[adam, sgd]"
3) Rank probable optima (winner-take-all MC)
--------------------------------------------
.. code-block:: bash
psyop optimal MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]
**Options**
- ``--output PATH`` — write top rows CSV (prints table if omitted).
- ``--count, -k INTEGER`` — how many top rows to keep (default: 10).
- ``--draws INTEGER`` — Monte-Carlo draws (default: 2000).
- ``--min-p-success FLOAT`` — hard feasibility cutoff; set to 0.0 to disable (default: 0.0).
- ``--seed INTEGER`` — RNG seed (default: 0).
**Constraints** — see *Constraint syntax* above.
**Output CSV columns**
``rank_prob_best``, feature columns, ``pred_p_success``, ``pred_target_mean``,
``pred_target_sd``, ``prob_best_feasible``, ``wins``, ``n_draws_effective``, ``conditioned_on``.
**Example**
.. code-block:: bash
psyop optimal output/trials.nc \
--epochs 12 --dropout 0.0:0.2 --min-p-success 0.5 -k 5 -o output/optimal.csv
4) 2D Partial Dependence (pairwise features)
--------------------------------------------
.. code-block:: bash
psyop plot2d MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]
**Options**
- ``--output PATH`` — HTML file.
- ``--n-points-1d INTEGER`` — diagonal sweep resolution (default: 300).
- ``--n-points-2d INTEGER`` — grid size per axis for 2D panels (default: 70).
- ``--use-log-scale-for-target`` — enable log10 colors for the target (toggle flag; default: off).
- ``--log-shift-epsilon FLOAT`` — epsilon shift for log colors (default: 1e-9).
- ``--colorscale TEXT`` — Plotly colorscale (default: ``RdBu``).
- ``--show`` — open in a browser.
- ``--n-contours INTEGER`` — contour levels (default: 12).
- ``--optimal / --no-optimal`` — overlay the current best-probable optimum (default: on).
- ``--suggest INTEGER`` — overlay up to N suggested points (default: 0).
- ``--width INTEGER`` / ``--height INTEGER`` — panel dimensions (pixels).
**Constraints**
- **Fixed** features are clamped and **removed** from the axes.
- **Ranges** restrict the sweep domain for that feature.
**Examples**
.. code-block:: bash
# Clamp epochs; restrict dropout domain
psyop plot2d output/trials.nc --epochs 20 --dropout 0.0:0.2 --show
# Discrete choices for batch size
psyop plot2d output/trials.nc --batch-size "(16,32,64)" -o pairplot.html
5) 1D Partial Dependence (per-feature)
--------------------------------------
.. code-block:: bash
psyop plot1d MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]
**Options**
- ``--output PATH`` — HTML file.
- ``--csv-out PATH`` — tidy CSV export of PD values.
- ``--n-points-1d INTEGER`` — sweep resolution (default: 300).
- ``--line-color TEXT`` — Plotly color string for mean/band (default: ``rgb(31,119,180)``).
- ``--band-alpha FLOAT`` — fill alpha for ±2σ (default: 0.25).
- ``--figure-height-per-row-px INTEGER`` — pixels per PD row (default: 320).
- ``--show`` — open in a browser.
- ``--log-y / --no-log-y`` — log scale for target axis (default: log).
- ``--log-y-eps FLOAT`` — clamp for log-Y (default: 1e-9).
- ``--optimal / --no-optimal`` — overlay the current best-probable optimum (default: on).
- ``--suggest INTEGER`` — overlay up to N suggested points (default: 0).
- ``--width INTEGER`` / ``--height INTEGER`` — panel dimensions (pixels).
**Constraints**
Same as *Constraint syntax*. Fixed features are **not plotted**; ranges **clip** the sweep domain.
**Examples**
.. code-block:: bash
psyop plot1d output/trials.nc --epochs 20 --dropout 0.0:0.2 \
--csv-out output/pd.csv -o output/pd.html --show
Notes
-----
- **Colorscales** are Plotly names (e.g. ``RdBu``, ``Viridis``, ``Inferno``).
- For plots, historical points are drawn even if outside your specified *range*,
but the **sweep domain** (and axes) respect your bounds.
- All constraint parsing is printed once as ``Constraints: ...`` for sanity checking.
Examples at a glance
--------------------
.. code-block:: bash
# Fit
psyop model runs.csv output/trials.nc -t loss --exclude run_id --seed 0
# Suggest inside bounds, with discrete choices
psyop suggest output/trials.nc \
--epochs 20 \
--dropout 0.0:0.2 \
--batch-size "(16,32,64)" \
-k 12 -o output/suggest.csv
# Rank optima with a minimum feasibility threshold
psyop optimal output/trials.nc --min-p-success 0.6 -k 5
# Pairwise PD conditioned on epochs
psyop plot2d output/trials.nc --epochs 20 --show
# 1D PD with CSV export
psyop plot1d output/trials.nc --csv-out output/pd.csv -o output/pd.html
Programmatic API
================
All functionality is also exposed as Python functions. You can work directly with
``xarray.Dataset`` objects or file paths.
Import paths:
.. code-block:: python
import xarray as xr
from pathlib import Path
from psyop import build_model, optimal, suggest, plot1d, plot2d
Build a model
-------------
.. code-block:: python
build_model(
input=Path("runs.csv"),
output=Path("output/trials.nc"),
target_column="loss",
exclude_columns=["run_id", "notes"],
direction="auto", # "min", "max", or "auto"
success_column=None, # infer success as ~isna(target)
random_seed=42,
compress=True, # compress numeric arrays within the .nc
)
Load a model
------------
.. code-block:: python
ds = xr.load_dataset("output/trials.nc")
Suggest candidates
------------------
.. code-block:: python
# Constraints are passed as kwargs in ORIGINAL units:
# - fixed: number
# - range: slice(lo, hi) (inclusive semantics for the endpoints)
# - choices: list/tuple (finite) (e.g. tuple(range(...)))
suggestions = suggest(
model=ds, # or "output/trials.nc"
output=None, # optional CSV path; None to return only the DataFrame
count=12,
p_success_threshold=0.8,
explore_fraction=0.34,
candidates_pool=5000,
random_seed=0,
epochs=20, # fixed
dropout=slice(0.0, 0.2), # range
batch_size=(16, 32, 64), # choices
)
print(suggestions.head())
Rank probable optima
--------------------
.. code-block:: python
top = optimal(
model=ds, # or "output/trials.nc"
output=None, # optional CSV path
count=10,
n_draws=2000,
min_success_probability=0.5, # 0.0 disables the hard cutoff
random_seed=0,
epochs=12,
dropout=slice(0.0, 0.2),
)
print(top[["prob_best_feasible", "pred_target_mean"]].head())
2D Partial Dependence (HTML)
----------------------------
.. code-block:: python
# Fixed features are clamped and removed from axes.
# Ranges clip the sweep domain even if historical points exist outside the range.
plot2d(
model=ds, # xarray.Dataset
output=Path("pairplot.html"),
n_points_1d=300,
n_points_2d=70,
use_log_scale_for_target=False,
log_shift_epsilon=1e-9,
colorscale="RdBu",
show=False,
n_contours=12,
optimal=True, # overlay current best-probable optimum
suggest=5, # overlay top-N suggestions
width=None,
height=None,
epochs=20,
dropout=slice(0.0, 0.2),
)
1D Partial Dependence (HTML + tidy CSV)
---------------------------------------
.. code-block:: python
plot1d(
model=ds,
output=Path("pd.html"),
csv_out=Path("pd.csv"),
n_points_1d=300,
line_color="rgb(31,119,180)",
band_alpha=0.25,
figure_height_per_row_px=320,
show=False,
use_log_scale_for_target_y=True,
log_y_epsilon=1e-9,
optimal=True,
suggest=3,
width=None,
height=None,
epochs=20,
dropout=slice(0.0, 0.2),
)
Return types and side effects
-----------------------------
- ``build_model(...)`` → ``None`` (writes a ``.nc`` file).
- ``suggest(...)`` → ``pandas.DataFrame`` (and optionally writes a CSV if ``output`` is provided).
- ``optimal(...)`` → ``pandas.DataFrame`` (and optionally writes a CSV if ``output`` is provided).
- ``plot2d(...)`` → ``None`` (writes HTML if ``output`` is provided; may open a browser if ``show=True``).
- ``plot1d(...)`` → ``None`` (writes HTML/CSV if paths are provided; may open a browser if ``show=True``).
Constraint objects in Python
----------------------------
- **Fixed**: ``epochs=20`` or ``learning_rate=1e-3``.
- **Range**: ``dropout=slice(0.0, 0.2)`` (inclusive ends).
- **Choices**: ``batch_size=(16, 32, 64)`` (tuple/list of finite values).
- **Integer grids**: ``layers=tuple(range(2, 9, 2))`` → ``(2, 4, 6, 8)``.
All constraints are interpreted in **original units** of your data. Bounds are enforced
for candidate sampling and sweep ranges; fixed values remove the feature from PD axes.
.. end-quickstart
Credits
==================================
.. start-credits
Robert Turnbull
For more information contact: <robert.turnbull@unimelb.edu.au>
.. end-credits
Raw data
{
"_id": null,
"home_page": "https://github.com/rbturnbull/psyop/",
"name": "Psyop",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "command-line interface",
"author": "Robert Turnbull",
"author_email": "robert.turnbull@unimelb.edu.au",
"download_url": "https://files.pythonhosted.org/packages/ae/e3/3b584652e55dd5a16568eb2af799f536d9539d11a91fb1e627e52b0c4d6e/psyop-0.1.0a1.tar.gz",
"platform": null,
"description": ".. image:: https://rbturnbull.github.io/psyop/_images/psyop-banner.jpg\n\n.. start-badges\n\n|testing badge| |coverage badge| |docs badge| |black badge|\n\n.. |testing badge| image:: https://github.com/rbturnbull/psyop/actions/workflows/testing.yml/badge.svg\n :target: https://github.com/rbturnbull/psyop/actions\n\n.. |docs badge| image:: https://github.com/rbturnbull/psyop/actions/workflows/docs.yml/badge.svg\n :target: https://rbturnbull.github.io/psyop\n \n.. |black badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n \n.. |coverage badge| image:: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/rbturnbull/d3a9e5f1b7d7b8593c9df1cd46fe7557/raw/coverage-badge.json\n :target: https://rbturnbull.github.io/psyop/coverage/\n \n.. end-badges\n\n.. start-quickstart\n\nInstallation\n==================================\n\nInstall using pip:\n\n.. code-block:: bash\n\n pip install psyop\n\nOr\n\n.. code-block:: bash\n\n pip install git+https://github.com/rbturnbull/psyop.git\n\n.. warning::\n\n Psyop is currently in alpha testing phase. More updates are coming soon.\n\nQuick help\n----------\n\n.. code-block:: bash\n\n psyop --help\n psyop <command> --help\n\n\nModel artifact\n--------------\n\nMost commands take a path to a ``.nc`` artifact produced by ``psyop model``.\n\nThe artifact bundles:\n\n- raw columns (for plotting & metadata),\n- standardized design matrices,\n- per-feature transforms & standardization stats,\n- two GP heads (success probability; expected target conditional on success),\n- convenience predictions and metadata (direction, seed, etc.).\n\n\nConstraint syntax (used by ``suggest``, ``optimal``, ``plot2d``, ``plot1d``)\n-----------------------------------------------------------------------------\n\nThese commands accept **extra CLI options** that are *not predeclared*\u2014they are parsed\ninto **feature constraints**. Constraints are always interpreted in **original units**\n(before any internal log/standardization).\n\nPass any mix of:\n\n- **Fixed value** *(number)* \u2014 clamp a feature at a single value and (for plots) remove it from the axes:\n\n .. code-block:: bash\n\n --epochs 20\n --learning-rate 0.001\n\n- **Range** *(slice)* \u2014 inclusive lower/upper bound:\n\n .. code-block:: bash\n\n --dropout 0.0:0.2\n --x 0..2 # same as 0:2\n --width 64:512:64 # optional step token; used where applicable\n\n- **Choices** *(finite set)* \u2014 list/tuple or Python-like ``range()`` call:\n\n .. code-block:: bash\n\n --batch-size \"(16, 32, 64)\"\n --optimizer \"[adam, sgd, adamw]\"\n --layers \"range(2,8,2)\" # -> (2, 4, 6, 8)\n\nRules:\n\n- Unknown keys are ignored with a warning (feature names are matched case-insensitively; hyphens/underscores are normalized).\n- If you pass both a fixed value and a range/choices for the same feature, the **fixed value wins**.\n- For **suggest**/**optimal**, bounds/choices are enforced strictly when sampling candidates.\n- For **plot2d**/**plot1d**, fixed features are **clamped** and **not shown** on axes; range constraints **restrict the sweep domain** even if historical points exist outside the range.\n\nTip (shells): quote lists/tuples and anything that contains commas or parentheses to avoid shell expansion.\n\n\nCommands\n========\n\n1) Fit a model\n--------------\n\n.. code-block:: bash\n\n psyop model INPUT.csv OUTPUT.nc [OPTIONS]\n\n**Arguments**\n\n- ``INPUT`` *(CSV)* \u2014 your experiment log.\n- ``OUTPUT`` *(.nc)* \u2014 where to save the model artifact.\n\n**Options**\n\n- ``--target, -t TEXT`` \u2014 target column name (default: ``loss``).\n- ``--exclude TEXT`` \u2014 repeatable; columns to exclude from features.\n- ``--direction, -d [min|max|auto]`` \u2014 optimization direction for the target (default: ``auto``).\n- ``--success-column TEXT`` \u2014 optional boolean/int column; if omitted, success is inferred as ``~isna(target)``.\n- ``--seed INTEGER`` \u2014 RNG seed (default: 0).\n- ``--compress / --no-compress`` \u2014 compress numeric arrays inside the artifact (default: on).\n\n**Example**\n\n.. code-block:: bash\n\n psyop model runs.csv output/trials.nc \\\n --target loss --exclude run_id --exclude notes --direction auto --seed 42\n\n\n2) Suggest candidates (constrained EI + exploration)\n----------------------------------------------------\n\n.. code-block:: bash\n\n psyop suggest MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]\n\n**Options**\n\n- ``--output, -o PATH`` \u2014 write suggestions CSV (if omitted, prints the table).\n- ``--count, -k INTEGER`` \u2014 number of suggestions (default: 10).\n- ``--p-success-threshold FLOAT`` \u2014 feasibility threshold in cEI (default: 0.8).\n- ``--explore FLOAT`` \u2014 fraction of suggestions reserved for exploration (default: 0.34).\n- ``--candidates-pool INTEGER`` \u2014 random candidate pool size to score (default: 5000).\n- ``--seed INTEGER`` \u2014 RNG seed (default: 0).\n\n**Constraints** \u2014 see *Constraint syntax* above.\n\n**Output CSV columns**\n\n``rank``, feature columns, ``pred_p_success``, ``pred_target_mean``, ``pred_target_sd``,\n``acq_cEI``, ``acq_explore``, ``novelty_norm``, ``direction``, ``conditioned_on``.\n\n**Examples**\n\n.. code-block:: bash\n\n # Fix epochs; bound dropout\n psyop suggest output/trials.nc --epochs 20 --dropout 0.0:0.2 -k 12 -o output/suggest.csv\n\n # Discrete choices and integer grid:\n psyop suggest output/trials.nc \\\n --batch-size \"(16, 32, 64)\" \\\n --layers \"range(2,8,2)\" \\\n --optimizer \"[adam, sgd]\"\n\n\n3) Rank probable optima (winner-take-all MC)\n--------------------------------------------\n\n.. code-block:: bash\n\n psyop optimal MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]\n\n**Options**\n\n- ``--output PATH`` \u2014 write top rows CSV (prints table if omitted).\n- ``--count, -k INTEGER`` \u2014 how many top rows to keep (default: 10).\n- ``--draws INTEGER`` \u2014 Monte-Carlo draws (default: 2000).\n- ``--min-p-success FLOAT`` \u2014 hard feasibility cutoff; set to 0.0 to disable (default: 0.0).\n- ``--seed INTEGER`` \u2014 RNG seed (default: 0).\n\n**Constraints** \u2014 see *Constraint syntax* above.\n\n**Output CSV columns**\n\n``rank_prob_best``, feature columns, ``pred_p_success``, ``pred_target_mean``,\n``pred_target_sd``, ``prob_best_feasible``, ``wins``, ``n_draws_effective``, ``conditioned_on``.\n\n**Example**\n\n.. code-block:: bash\n\n psyop optimal output/trials.nc \\\n --epochs 12 --dropout 0.0:0.2 --min-p-success 0.5 -k 5 -o output/optimal.csv\n\n\n4) 2D Partial Dependence (pairwise features)\n--------------------------------------------\n\n.. code-block:: bash\n\n psyop plot2d MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]\n\n**Options**\n\n- ``--output PATH`` \u2014 HTML file.\n- ``--n-points-1d INTEGER`` \u2014 diagonal sweep resolution (default: 300).\n- ``--n-points-2d INTEGER`` \u2014 grid size per axis for 2D panels (default: 70).\n- ``--use-log-scale-for-target`` \u2014 enable log10 colors for the target (toggle flag; default: off).\n- ``--log-shift-epsilon FLOAT`` \u2014 epsilon shift for log colors (default: 1e-9).\n- ``--colorscale TEXT`` \u2014 Plotly colorscale (default: ``RdBu``).\n- ``--show`` \u2014 open in a browser.\n- ``--n-contours INTEGER`` \u2014 contour levels (default: 12).\n- ``--optimal / --no-optimal`` \u2014 overlay the current best-probable optimum (default: on).\n- ``--suggest INTEGER`` \u2014 overlay up to N suggested points (default: 0).\n- ``--width INTEGER`` / ``--height INTEGER`` \u2014 panel dimensions (pixels).\n\n**Constraints**\n\n- **Fixed** features are clamped and **removed** from the axes.\n- **Ranges** restrict the sweep domain for that feature.\n\n**Examples**\n\n.. code-block:: bash\n\n # Clamp epochs; restrict dropout domain\n psyop plot2d output/trials.nc --epochs 20 --dropout 0.0:0.2 --show\n\n # Discrete choices for batch size\n psyop plot2d output/trials.nc --batch-size \"(16,32,64)\" -o pairplot.html\n\n\n5) 1D Partial Dependence (per-feature)\n--------------------------------------\n\n.. code-block:: bash\n\n psyop plot1d MODEL.nc [OPTIONS] [EXTRA_CONSTRAINTS...]\n\n**Options**\n\n- ``--output PATH`` \u2014 HTML file.\n- ``--csv-out PATH`` \u2014 tidy CSV export of PD values.\n- ``--n-points-1d INTEGER`` \u2014 sweep resolution (default: 300).\n- ``--line-color TEXT`` \u2014 Plotly color string for mean/band (default: ``rgb(31,119,180)``).\n- ``--band-alpha FLOAT`` \u2014 fill alpha for \u00b12\u03c3 (default: 0.25).\n- ``--figure-height-per-row-px INTEGER`` \u2014 pixels per PD row (default: 320).\n- ``--show`` \u2014 open in a browser.\n- ``--log-y / --no-log-y`` \u2014 log scale for target axis (default: log).\n- ``--log-y-eps FLOAT`` \u2014 clamp for log-Y (default: 1e-9).\n- ``--optimal / --no-optimal`` \u2014 overlay the current best-probable optimum (default: on).\n- ``--suggest INTEGER`` \u2014 overlay up to N suggested points (default: 0).\n- ``--width INTEGER`` / ``--height INTEGER`` \u2014 panel dimensions (pixels).\n\n**Constraints**\n\nSame as *Constraint syntax*. Fixed features are **not plotted**; ranges **clip** the sweep domain.\n\n**Examples**\n\n.. code-block:: bash\n\n psyop plot1d output/trials.nc --epochs 20 --dropout 0.0:0.2 \\\n --csv-out output/pd.csv -o output/pd.html --show\n\n\nNotes\n-----\n\n- **Colorscales** are Plotly names (e.g. ``RdBu``, ``Viridis``, ``Inferno``).\n- For plots, historical points are drawn even if outside your specified *range*,\n but the **sweep domain** (and axes) respect your bounds.\n- All constraint parsing is printed once as ``Constraints: ...`` for sanity checking.\n\n\nExamples at a glance\n--------------------\n\n.. code-block:: bash\n\n # Fit\n psyop model runs.csv output/trials.nc -t loss --exclude run_id --seed 0\n\n # Suggest inside bounds, with discrete choices\n psyop suggest output/trials.nc \\\n --epochs 20 \\\n --dropout 0.0:0.2 \\\n --batch-size \"(16,32,64)\" \\\n -k 12 -o output/suggest.csv\n\n # Rank optima with a minimum feasibility threshold\n psyop optimal output/trials.nc --min-p-success 0.6 -k 5\n\n # Pairwise PD conditioned on epochs\n psyop plot2d output/trials.nc --epochs 20 --show\n\n # 1D PD with CSV export\n psyop plot1d output/trials.nc --csv-out output/pd.csv -o output/pd.html\n\n\nProgrammatic API\n================\n\nAll functionality is also exposed as Python functions. You can work directly with\n``xarray.Dataset`` objects or file paths.\n\nImport paths:\n\n.. code-block:: python\n\n import xarray as xr\n from pathlib import Path\n from psyop import build_model, optimal, suggest, plot1d, plot2d\n\nBuild a model\n-------------\n\n.. code-block:: python\n\n build_model(\n input=Path(\"runs.csv\"),\n output=Path(\"output/trials.nc\"),\n target_column=\"loss\",\n exclude_columns=[\"run_id\", \"notes\"],\n direction=\"auto\", # \"min\", \"max\", or \"auto\"\n success_column=None, # infer success as ~isna(target)\n random_seed=42,\n compress=True, # compress numeric arrays within the .nc\n )\n\nLoad a model\n------------\n\n.. code-block:: python\n\n ds = xr.load_dataset(\"output/trials.nc\")\n\nSuggest candidates\n------------------\n\n.. code-block:: python\n\n # Constraints are passed as kwargs in ORIGINAL units:\n # - fixed: number\n # - range: slice(lo, hi) (inclusive semantics for the endpoints)\n # - choices: list/tuple (finite) (e.g. tuple(range(...)))\n suggestions = suggest(\n model=ds, # or \"output/trials.nc\"\n output=None, # optional CSV path; None to return only the DataFrame\n count=12,\n p_success_threshold=0.8,\n explore_fraction=0.34,\n candidates_pool=5000,\n random_seed=0,\n epochs=20, # fixed\n dropout=slice(0.0, 0.2), # range\n batch_size=(16, 32, 64), # choices\n )\n print(suggestions.head())\n\nRank probable optima\n--------------------\n\n.. code-block:: python\n\n top = optimal(\n model=ds, # or \"output/trials.nc\"\n output=None, # optional CSV path\n count=10,\n n_draws=2000,\n min_success_probability=0.5, # 0.0 disables the hard cutoff\n random_seed=0,\n epochs=12,\n dropout=slice(0.0, 0.2),\n )\n print(top[[\"prob_best_feasible\", \"pred_target_mean\"]].head())\n\n2D Partial Dependence (HTML)\n----------------------------\n\n.. code-block:: python\n\n # Fixed features are clamped and removed from axes.\n # Ranges clip the sweep domain even if historical points exist outside the range.\n plot2d(\n model=ds, # xarray.Dataset\n output=Path(\"pairplot.html\"),\n n_points_1d=300,\n n_points_2d=70,\n use_log_scale_for_target=False,\n log_shift_epsilon=1e-9,\n colorscale=\"RdBu\",\n show=False,\n n_contours=12,\n optimal=True, # overlay current best-probable optimum\n suggest=5, # overlay top-N suggestions\n width=None,\n height=None,\n epochs=20,\n dropout=slice(0.0, 0.2),\n )\n\n1D Partial Dependence (HTML + tidy CSV)\n---------------------------------------\n\n.. code-block:: python\n\n plot1d(\n model=ds,\n output=Path(\"pd.html\"),\n csv_out=Path(\"pd.csv\"),\n n_points_1d=300,\n line_color=\"rgb(31,119,180)\",\n band_alpha=0.25,\n figure_height_per_row_px=320,\n show=False,\n use_log_scale_for_target_y=True,\n log_y_epsilon=1e-9,\n optimal=True,\n suggest=3,\n width=None,\n height=None,\n epochs=20,\n dropout=slice(0.0, 0.2),\n )\n\nReturn types and side effects\n-----------------------------\n\n- ``build_model(...)`` \u2192 ``None`` (writes a ``.nc`` file).\n- ``suggest(...)`` \u2192 ``pandas.DataFrame`` (and optionally writes a CSV if ``output`` is provided).\n- ``optimal(...)`` \u2192 ``pandas.DataFrame`` (and optionally writes a CSV if ``output`` is provided).\n- ``plot2d(...)`` \u2192 ``None`` (writes HTML if ``output`` is provided; may open a browser if ``show=True``).\n- ``plot1d(...)`` \u2192 ``None`` (writes HTML/CSV if paths are provided; may open a browser if ``show=True``).\n\nConstraint objects in Python\n----------------------------\n\n- **Fixed**: ``epochs=20`` or ``learning_rate=1e-3``.\n- **Range**: ``dropout=slice(0.0, 0.2)`` (inclusive ends).\n- **Choices**: ``batch_size=(16, 32, 64)`` (tuple/list of finite values).\n- **Integer grids**: ``layers=tuple(range(2, 9, 2))`` \u2192 ``(2, 4, 6, 8)``.\n\nAll constraints are interpreted in **original units** of your data. Bounds are enforced\nfor candidate sampling and sweep ranges; fixed values remove the feature from PD axes.\n\n\n.. end-quickstart\n\n\nCredits\n==================================\n\n.. start-credits\n\nRobert Turnbull\nFor more information contact: <robert.turnbull@unimelb.edu.au>\n\n.. end-credits\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Parameter Space Yield Optimizer",
"version": "0.1.0a1",
"project_urls": {
"Documentation": "https://rbturnbull.github.io/psyop",
"Homepage": "https://github.com/rbturnbull/psyop/",
"Repository": "https://github.com/rbturnbull/psyop/"
},
"split_keywords": [
"command-line",
"interface"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f573b6fdd68a34cafcc04c6f9923ceeed40fe8e9712f432c75070d45c764dfe7",
"md5": "4c4cbd4ff8e3f54ed7db8dc0cebfb05e",
"sha256": "e0564bb07e5b7efe7ffd25412cccda81808f271db2a5113d6422f875c742ad84"
},
"downloads": -1,
"filename": "psyop-0.1.0a1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c4cbd4ff8e3f54ed7db8dc0cebfb05e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 51432,
"upload_time": "2025-09-08T08:23:45",
"upload_time_iso_8601": "2025-09-08T08:23:45.227169Z",
"url": "https://files.pythonhosted.org/packages/f5/73/b6fdd68a34cafcc04c6f9923ceeed40fe8e9712f432c75070d45c764dfe7/psyop-0.1.0a1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aee33b584652e55dd5a16568eb2af799f536d9539d11a91fb1e627e52b0c4d6e",
"md5": "1052abc79f2281745d70b9a9b286fbdf",
"sha256": "5a2086c13b920ef0acac9c723c400b34fb5f14ed5851d79a107ce5ff6d7c144f"
},
"downloads": -1,
"filename": "psyop-0.1.0a1.tar.gz",
"has_sig": false,
"md5_digest": "1052abc79f2281745d70b9a9b286fbdf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 51690,
"upload_time": "2025-09-08T08:23:46",
"upload_time_iso_8601": "2025-09-08T08:23:46.887512Z",
"url": "https://files.pythonhosted.org/packages/ae/e3/3b584652e55dd5a16568eb2af799f536d9539d11a91fb1e627e52b0c4d6e/psyop-0.1.0a1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 08:23:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rbturnbull",
"github_project": "psyop",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "psyop"
}
JSON
