Loading

rupsycho.experiment_from_file

experiment_from_file(path: str | PathLike[str]) -> ExperimentDocument

Load one experiment from a JSON file.

PARAMETER	DESCRIPTION
path	Path of the JSON file. TYPE: str | PathLike[str]

RETURNS	DESCRIPTION
ExperimentDocument	The validated experiment.

RAISES	DESCRIPTION
FileNotFoundError	If the file does not exist.
ValueError	If the file is not valid JSON or not a valid experiment (pydantic's ValidationError is a ValueError).

Example

import rupsycho as rup

experiment = rup.experiment_from_file("config.json")

rupsycho.experiment_from_dict

experiment_from_dict(json_data: dict[str, Any]) -> ExperimentDocument

Create one experiment from a configuration dictionary.

PARAMETER	DESCRIPTION
json_data	The experiment configuration (see the configuration reference). TYPE: dict[str, Any]

RETURNS	DESCRIPTION
ExperimentDocument	The validated experiment.

RAISES	DESCRIPTION
ValueError	If the configuration is invalid (pydantic's ValidationError is a ValueError).

rupsycho.experiments_from_files

experiments_from_files(path_pattern: str, *, strict: bool = False) -> ExperimentCollection

Load all experiments matching a path or glob pattern.

PARAMETER	DESCRIPTION
path_pattern	A JSON file or glob pattern such as "configs/*.json". TYPE: str
strict	Raise on the first invalid file instead of logging and skipping it. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ExperimentCollection	A collection of the valid experiments, ordered by file name.

RAISES	DESCRIPTION
ValueError	If no file matches the pattern.

rupsycho.experiments_from_dicts

experiments_from_dicts(json_data_list: list[dict[str, Any]], *, strict: bool = False) -> Iterator[ExperimentDocument]

Lazily create experiments from configuration dictionaries.

PARAMETER	DESCRIPTION
json_data_list	The experiment configurations. TYPE: list[dict[str, Any]]
strict	Raise on the first invalid configuration instead of logging and skipping it. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Iterator[ExperimentDocument]	An iterator over the valid experiments.

rupsycho.reader.ExperimentLoader

ExperimentLoader(path_pattern: str | None = None, *, strict: bool = False)

A document loader that reads JSON files validated by the ExperimentDocument model.

PARAMETER	DESCRIPTION
path_pattern	A file path or glob pattern (** is supported) of JSON files. TYPE: str | None DEFAULT: None
strict	Raise on the first invalid experiment instead of logging and skipping it. TYPE: bool DEFAULT: False

Example

from rupsycho.reader import ExperimentLoader

experiments = ExperimentLoader("configs/*.json").load()

lazy_load

lazy_load(path_pattern: str | None = None) -> Iterator[ExperimentDocument]

Lazily load and validate the experiments in the resolved files.

PARAMETER	DESCRIPTION
path_pattern	A glob pattern or single file path; defaults to the pattern the loader was created with. TYPE: str | None DEFAULT: None

YIELDS	DESCRIPTION
ExperimentDocument	One validated experiment per readable, valid file.

RAISES	DESCRIPTION
ValueError	If no file paths are available.

alazy_load async

alazy_load(path_pattern: str | None = None) -> AsyncIterator[ExperimentDocument]

Asynchronous version of lazy_load.

lazy_load_from_dicts

lazy_load_from_dicts(dicts: list[dict[str, Any]]) -> Iterator[ExperimentDocument]

Lazily validate dictionaries as experiments.

PARAMETER	DESCRIPTION
dicts	Experiment configurations. TYPE: list[dict[str, Any]]

YIELDS	DESCRIPTION
ExperimentDocument	One validated experiment per valid dictionary.

alazy_load_from_dicts async

alazy_load_from_dicts(dicts: list[dict[str, Any]]) -> AsyncIterator[ExperimentDocument]

Asynchronous version of lazy_load_from_dicts.

Bundled examples

rupsycho.datasets

Bundled example experiments.

The wheel ships a ready-to-run Big Five Inventory configuration so that the documentation examples work after a plain pip install. Larger study configurations live in the examples/data folder of the repository.

list_examples

list_examples() -> list[str]

Return the names of the bundled example configurations.

RETURNS	DESCRIPTION
list[str]	Alphabetically sorted names, usable with load_example_config.

Example

from rupsycho import list_examples

print(list_examples())  # ['bfi']

load_example_config

load_example_config(name: str = 'bfi') -> dict[str, Any]

Load a bundled example configuration as a dictionary.

PARAMETER	DESCRIPTION
name	Name of the example (see list_examples). TYPE: str DEFAULT: 'bfi'

RETURNS	DESCRIPTION
dict[str, Any]	A fresh dictionary that may be modified freely, for instance to swap the model.

RAISES	DESCRIPTION
KeyError	If there is no example with that name.

Example

from rupsycho import load_example_config

config = load_example_config("bfi")
config["parameters"]["seeds"] = ["1", "2", "3"]

load_example_experiment

load_example_experiment(name: str = 'bfi', *, models: dict[str, Any] | None = None, seeds: list[int] | list[str] | None = None) -> ExperimentDocument

Create an experiment from a bundled example.

PARAMETER	DESCRIPTION
name	Name of the example (see list_examples). TYPE: str DEFAULT: 'bfi'
models	Replacement for the models section of the example, e.g. {} to add your own model with experiment.add_model(...) without the example's Hugging Face model being used. TYPE: dict[str, Any] | None DEFAULT: None
seeds	Replacement for the example's seeds, e.g. [1, 2, 3]. TYPE: list[int] | list[str] | None DEFAULT: None

RETURNS	DESCRIPTION
ExperimentDocument	The validated experiment.

Example

from rupsycho import load_example_experiment

experiment = load_example_experiment("bfi", models={})

Deprecated example experiment

rupsycho.example_experiment_bfi

example_experiment_bfi(model_name: str = 'google/flan-t5-small', pipeline_type: str = 'text2text-generation', temperature: float = 0.7, max_new_tokens: int = 128, api_key: str | None = None) -> ExperimentDocument

Create a tiny Big Five experiment around a Hugging Face pipeline.

Deprecated

Use load_example_experiment and add your model with experiment.add_model.

PARAMETER	DESCRIPTION
model_name	Name of the Hugging Face model to use. TYPE: str DEFAULT: 'google/flan-t5-small'
pipeline_type	Pipeline task, e.g. "text2text-generation". TYPE: str DEFAULT: 'text2text-generation'
temperature	Sampling temperature. TYPE: float DEFAULT: 0.7
max_new_tokens	Maximum number of generated tokens. TYPE: int DEFAULT: 128
api_key	Optional Hugging Face token for gated models. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
ExperimentDocument	A configured experiment with the model already added.

RAISES	DESCRIPTION
ImportError	If the huggingface extra is not installed.

Utilities

rupsycho.utils

json_loader

json_loader(path: str) -> dict

Load a JSON file from the given path and return its contents as a dictionary.

PARAMETER	DESCRIPTION
path	Path to the JSON file. TYPE: str

RETURNS	DESCRIPTION
dict	Dictionary containing the JSON data.

json_saver

json_saver(data: dict, name: str = 'output', path: str = '') -> None

Save a dictionary as a JSON file at the specified path and file name. If no path is provided, saves to the current directory. Prints the full path upon successful save.

PARAMETER	DESCRIPTION
data	Dictionary to save as JSON. TYPE: dict
name	Name of the file to save. Defaults to 'output'. TYPE: str DEFAULT: 'output'
path	Directory path where the file will be saved. Defaults to the current directory. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
None	None

import_tqdm

import_tqdm() -> Any

Return the tqdm flavour that fits the environment.

In a Jupyter kernel the notebook widget variant is returned, everywhere else the console progress bar. IPython is only inspected if it has already been imported, so plain scripts never pay for importing it.

RETURNS	DESCRIPTION
Any	The tqdm class.