biomedical_data_generator.config.DatasetConfig

class biomedical_data_generator.config.DatasetConfig(*, standalone_informative_groups=<factory>, n_standalone_noise=0, class_configs=[ClassConfig(n_samples=30, class_distribution='normal', class_distribution_params={'loc': 0.0, 'scale': 1.0}, label='healthy'), ClassConfig(n_samples=30, class_distribution='normal', class_distribution_params={'loc': 0.0, 'scale': 1.0}, label='diseased')], noise_distribution='normal', noise_distribution_params=None, prefixed_feature_naming=True, prefix_informative='i', prefix_noise='n', prefix_corr='corr', corr_clusters=<factory>, batch_effects=None, random_state=None)

Bases: BaseModel

Configuration for synthetic dataset generation.

This model defines the input-level controls for building a synthetic dataset. Signal is expressed structurally through channels, never through declared relevance. The inputs are:

• Standalone informative block: standalone_informative_groups – a list of StandaloneInformativeGroup, each contributing independent informative features that share one separation strength (class_sep).

• Standalone noise block: n_standalone_noise independent noise features.

• Correlated clusters: corr_clusters – a list of CorrClusterConfig. Each cluster is a correlated block (anchor plus proxies) whose signal is carried by optional channels: a mean_channel (per-class anchor mean shift, first moment), a covariance_channel (per-class within-cluster correlation, second moment), and a structural baseline_correlation used when no covariance channel overrides a class.

• Class definitions: class_configs – per-class sample counts, base distributions, and labels.

• Optional batch effects: batch_effects.

• Reproducibility: random_state.

Derived properties (computed from the inputs above, never set by the user):

• n_samples (int): Total samples (from class_configs).

• n_classes (int): Number of classes (from class_configs).

• n_features (int): Standalone informative + standalone noise + cluster members.

• n_standalone_informative (int): Sum of n_features over all standalone_informative_groups.

• n_informative (int): Standalone informative features plus all members of clusters that the signal predicate derives as informative (a cluster is informative iff its mean channel varies across classes or its effective per-class correlation varies across classes).

• n_noise (int): Complement of n_informative.

Setting any of n_samples, n_classes, n_features, n_informative, n_noise, or n_standalone_informative manually is rejected.

Parameters:

• standalone_informative_groups (list[StandaloneInformativeGroup]) – Groups of standalone informative features, each with its own class_sep.

• n_standalone_noise (int) – Number of standalone (cluster-free) noise features.

• class_configs (list[ClassConfig]) – List of class definitions (>= 2).

• corr_clusters (list[CorrClusterConfig]) – Correlated feature clusters with optional mean/covariance channels and a structural baseline correlation.

• noise_distribution (str) – Distribution for noise features. Any supported DistributionType.

• noise_distribution_params (dict) – Parameters for the noise distribution.

• prefixed_feature_naming (bool) –

  If True, role-based prefixed feature names:

  • Standalone informative: i1, i2, …

  • Standalone noise: n1, n2, …

  • Correlated: corr{cid}_anchor, corr{cid}_2, …, corr{cid}_k

  If False, use generic feature_{i} naming. Default: True.

• prefix_informative (str) – Prefix for informative features (if prefixed_feature_naming=True). Default: “i”.

• prefix_noise (str) – Prefix for noise features (if prefixed_feature_naming=True). Default: “n”.

• prefix_corr (str) – Prefix for correlated cluster features (if prefixed_feature_naming=True). Default: “corr”.

• batch_effects (BatchEffectsConfig) – Optional BatchEffectsConfig for simulating batch effects.

• random_state (int | None) – Global random seed for dataset generation.

breakdown()

Return dict with derived feature counts (standalone/cluster members and the derived informative/noise totals).

Return type:

dict[str, int]

cluster_informative_flags()

Per-cluster booleans for derived informativeness.

Return type:

list[bool]

from_yaml(path)

Load and validate a config from a YAML file.

Parameters:

path (str)

Return type:

DatasetConfig

Validation:

Before model construction:

• Forbid manual n_samples, n_classes, n_features, n_informative, n_noise, n_standalone_informative.

• Require at least two classes.

After model construction:

• Validate sequence class_sep lengths on each group against n_classes - 1.

• Validate that every per-class channel key (mean and covariance) is a valid class index in range(n_classes).

• Auto-generate missing class labels as class_{idx}.

Raises:

• ValueError – On invalid numeric ranges or inconsistent counts.

• TypeError – For invalid types in class_configs or class_sep.

Parameters:

• standalone_informative_groups (list[StandaloneInformativeGroup])

• n_standalone_noise (Annotated[int, Ge(ge=0)])

• class_configs (Annotated[list[ClassConfig], MinLen(min_length=2)])

• noise_distribution (Literal['normal', 'lognormal', 'exp_normal', 'uniform', 'exponential', 'laplace'])

• noise_distribution_params (dict[str, Any] | None)

• prefixed_feature_naming (bool)

• prefix_informative (str)

• prefix_noise (str)

• prefix_corr (str)

• corr_clusters (list[CorrClusterConfig])

• batch_effects (BatchEffectsConfig | None)

• random_state (int | None)

Examples

>>> from biomedical_data_generator.config import (
...     ClassConfig,
...     CorrClusterConfig,
...     DatasetConfig,
...     MeanChannel,
...     StandaloneInformativeGroup,
... )
>>> cfg = DatasetConfig(
...     standalone_informative_groups=[
...         StandaloneInformativeGroup(n_features=5, class_sep=1.0),
...     ],
...     n_standalone_noise=3,
...     class_configs=[
...         ClassConfig(n_samples=50, label="healthy"),
...         ClassConfig(n_samples=50, label="diseased"),
...     ],
...     corr_clusters=[
...         CorrClusterConfig(
...             n_cluster_features=4,
...             baseline_correlation=0.8,
...             mean_channel=MeanChannel(per_class_effect={1: 1.5}),
...             label="Metabolic Pathway A",
...         ),
...         CorrClusterConfig(
...             n_cluster_features=3,
...             baseline_correlation=0.5,
...             label="Structural Correlated Block",
...         ),
...     ],
...     noise_distribution="normal",
...     noise_distribution_params={"loc": 0, "scale": 1},
...     prefixed_feature_naming=True,
...     random_state=42,
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

__init__(**data)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

Methods

__init__(**data)	Create a new model by parsing and validating input data from keyword arguments.
breakdown()	Structured, derived feature counts.
cluster_column_informative_flags()	Per-column booleans: whether each cluster column is derived informative.
cluster_informative_flags()	Per-cluster booleans: whether each cluster is derived informative.
construct([_fields_set])
copy(*[, include, exclude, update, deep])	Returns a copy of the model.
dict(*[, include, exclude, by_alias, ...])
from_orm(obj)
from_yaml(path)	Load from YAML and validate via the same pipeline.
json(*[, include, exclude, by_alias, ...])
model_construct([_fields_set])	Creates a new instance of the Model class with validated data.
model_copy(*[, update, deep])	!!! abstract "Usage Documentation"
model_dump(*[, mode, include, exclude, ...])	!!! abstract "Usage Documentation"
model_dump_json(*[, indent, ensure_ascii, ...])	!!! abstract "Usage Documentation"
model_json_schema([by_alias, ref_template, ...])	Generates a JSON schema for a model class.
model_parametrized_name(params)	Compute the class name for parametrizations of generic classes.
model_post_init(context, /)	Override this method to perform additional initialization after __init__ and model_construct.
model_rebuild(*[, force, raise_errors, ...])	Try to rebuild the pydantic-core schema for the model.
model_validate(obj, *[, strict, extra, ...])	Validate a pydantic model instance.
model_validate_json(json_data, *[, strict, ...])	!!! abstract "Usage Documentation"
model_validate_strings(obj, *[, strict, ...])	Validate the given object with string data against the Pydantic model.
parse_file(path, *[, content_type, ...])
parse_obj(obj)
parse_raw(b, *[, content_type, encoding, ...])
schema([by_alias, ref_template])
schema_json(*[, by_alias, ref_template])
update_forward_refs(**localns)
validate(value)

Attributes

class_counts	n_samples}.
class_labels	List of class labels (auto-generated or user-provided).
model_computed_fields
model_config	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
model_extra	Get extra fields set during validation.
model_fields
model_fields_set	Returns the set of fields that have been explicitly set on this model instance.
n_classes	Number of classes (derived from class_configs).
n_features	standalone informative + standalone noise + cluster members.
n_informative	Derived informative feature count.
n_noise	the complement of n_informative.
n_samples	Total samples (derived from class_configs).
n_standalone_informative	Derived count of standalone (cluster-free) informative features.
standalone_informative_groups
n_standalone_noise
class_configs
noise_distribution
noise_distribution_params
prefixed_feature_naming
prefix_informative
prefix_noise
prefix_corr
corr_clusters
batch_effects
random_state

breakdown()

Structured, derived feature counts.

Returns:

• n_standalone_informative

• n_standalone_noise

• n_cluster_members

• n_informative (derived)

• n_noise (derived)

• n_features

Return type:

A dict with keys

property class_counts: dict[int, int]

n_samples}.

Type:

Class counts as dict {class_idx

property class_labels: list[str]

List of class labels (auto-generated or user-provided).

cluster_column_informative_flags()

Per-column booleans: whether each cluster column is derived informative.

The per-column refinement of cluster_informative_flags(). Relevance is derived per column from the channel mappings via the shared predicate, never declared. A cluster column is informative iff it carries a class-dependent mean shift (the anchor’s shift, or a proxy’s attenuated propagation) or participates in a class-dependent within-cluster correlation. A single cluster may therefore split across informative and noise roles (e.g. an informative anchor with noise proxies).

Returns:

One inner list per cluster, in corr_clusters order, with one boolean per column (anchor and proxies) in block-column order.

Return type:

list[list[bool]]

cluster_informative_flags()

Per-cluster booleans: whether each cluster is derived informative.

Relevance is derived from the channel mappings via the shared predicate, never declared. A cluster is informative iff its mean channel varies across classes or its effective per-class correlation varies across classes.

Returns:

One boolean per cluster, in corr_clusters order.

Return type:

list[bool]

classmethod from_yaml(path)

Load from YAML and validate via the same pipeline.

Parameters:

path (str)

Return type:

DatasetConfig

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property n_classes: int

Number of classes (derived from class_configs).

property n_features: int

standalone informative + standalone noise + cluster members.

Type:

Total number of features

property n_informative: int

Derived informative feature count.

Standalone informative features plus all members of clusters that the signal predicate marks informative.

property n_noise: int

the complement of n_informative.

Type:

Derived noise feature count

property n_samples: int

Total samples (derived from class_configs).

property n_standalone_informative: int

Derived count of standalone (cluster-free) informative features.

Sum of n_features across all standalone_informative_groups.