qbiocode.embeddings.embed module#

Summary#

Functions:

check_embedding_name

Normalize and validate an embedding name, raising if it is unknown.

get_embeddings

Apply an embedding to the training and test datasets.

is_transductive

Return True if embedding is fit on the combined train and test rows.

pqk

This function generates quantum circuits, computes projections of the data onto these circuits.

Reference#

pqk(X_train, X_test, args, store=False, data_key='', encoding='Z', data_map=True, primitive='estimator', entanglement='linear', reps=2)[source]#

This function generates quantum circuits, computes projections of the data onto these circuits. It uses a feature map to encode the data into quantum states and then measures the expectation values of Pauli operators to obtain the features. This function requires a quantum backend (simulator or real quantum hardware) for execution. It supports various configurations such as encoding methods, entanglement strategies, and repetitions of the feature map. Optionally the results are saved to files for training and test projections.

Parameters:

  • X_train (np.ndarray) – Training data features.

  • X_test (np.ndarray) – Test data features.

  • args (dict) – Backend configuration. Requires backend ('simulator', 'simulator_aer', or an 'ibm_*' device) and, for the simulator, seed so the statevector primitive is reproducible.

  • store (bool) – If true projections are stored, using data_key as indefitier

  • data_key (str) – Key for the dataset, default is ‘’.

  • encoding (str) – Encoding method for the quantum circuit, default is ‘Z’.

  • data_map (bool) – If true ensures that all multiplicative factors of data features inside single qubit gates are 1.0. Not applicable for Hejsemberg feature maps

  • primitive (str) – Primitive type to use, default is ‘estimator’.

  • entanglement (str) – Entanglement strategy, default is ‘linear’.

  • reps (int) – Number of repetitions for the feature map, default is 2.

Returns:

A dictionary containing evaluation metrics and model parameters.

Return type:

modeleval (dict)

SKLEARN_METHODS = ('none', 'pca', 'nmf', 'lle', 'isomap', 'spectral', 'umap')#

Feature-reduction modes backed by scikit-learn / UMAP.

QUVINE_HEADLINE_METHODS = ('quvine_fused', 'quvine_rwr', 'quvine_dtqw', 'quvine_ctqw', 'node2vec', 'netmf', 'appnp')#

The headline QuVINE names, for discoverability. QUVINE_METHODS holds all of them; these are the ones worth naming next to pca/nmf/umap.

QUVINE_METHODS = ('appnp', 'baseline_filter_heat', 'baseline_filter_poly', 'baseline_gat', 'baseline_gcnmf', 'baseline_graphgps', 'ctqw', 'dtqw', 'filter_ctqw_heat', 'filter_ctqw_poly', 'filter_dtqw_heat', 'filter_dtqw_poly', 'filter_rwr_heat', 'filter_rwr_poly', 'fused', 'gat_baseline', 'gat_ctqw_heat', 'gat_ctqw_poly', 'gat_dtqw_heat', 'gat_dtqw_poly', 'gat_heat', 'gat_poly', 'gat_rwr', 'gat_rwr_heat', 'gat_rwr_poly', 'graphgps_baseline', 'graphgps_ctqw_heat', 'graphgps_ctqw_poly', 'graphgps_dtqw_heat', 'graphgps_dtqw_poly', 'graphgps_heat', 'graphgps_poly', 'graphgps_rwr', 'graphgps_rwr_heat', 'graphgps_rwr_poly', 'graphsage', 'netmf', 'node2vec', 'quvine', 'quvine_ctqw', 'quvine_ctqw_heat', 'quvine_ctqw_poly', 'quvine_ctqw_sgns', 'quvine_dtqw', 'quvine_dtqw_heat', 'quvine_dtqw_poly', 'quvine_dtqw_sgns', 'quvine_fused', 'quvine_gat', 'quvine_gat_ctqw', 'quvine_gat_ctqw_heat', 'quvine_gat_ctqw_poly', 'quvine_gat_dtqw', 'quvine_gat_dtqw_heat', 'quvine_gat_dtqw_poly', 'quvine_gat_rwr', 'quvine_gat_rwr_heat', 'quvine_gat_rwr_poly', 'quvine_gcnmf_ctqw', 'quvine_gcnmf_dtqw', 'quvine_gcnmf_rwr', 'quvine_graphgps', 'quvine_graphgps_ctqw', 'quvine_graphgps_ctqw_heat', 'quvine_graphgps_ctqw_poly', 'quvine_graphgps_dtqw', 'quvine_graphgps_dtqw_heat', 'quvine_graphgps_dtqw_poly', 'quvine_graphgps_rwr', 'quvine_graphgps_rwr_heat', 'quvine_graphgps_rwr_poly', 'quvine_heat', 'quvine_poly', 'quvine_rwr', 'quvine_rwr_heat', 'quvine_rwr_poly', 'quvine_rwr_sgns', 'quvine_sgns', 'quvine_sgns_fused', 'rwr', 'sgns_ctqw', 'sgns_dtqw', 'sgns_rwr')#

Every QuVINE method name accepted by get_embeddings(), e.g. quvine_rwr, quvine_ctqw_heat, node2vec, graphgps_rwr_poly.

is_transductive(embedding)[source]#

Return True if embedding is fit on the combined train and test rows.

Inductive methods (pca, nmf, lle, isomap, umap) are fit on the training rows alone and applied to the test rows through transform. Transductive methods — spectral and every QuVINE method — have no out-of-sample transform, so the embedding is computed once over vstack([X_train, X_test]) and sliced back.

Test features therefore participate in the embedding; test labels never reach it. This is the standard protocol for unsupervised graph and manifold embeddings, but it means an embedding fit this way cannot be reused on rows unseen at fit time, and a reported test score is a transductive score. Callers that need the distinction — e.g. to skip a method in a strictly inductive benchmark — should branch on this.

Parameters:

embedding (str) – An embedding name accepted by get_embeddings().

Returns:

True for a transductive method. Unknown names return False rather than raising, so this is safe to call before validation.

Return type:

bool

Examples

>>> is_transductive("pca")
False
>>> is_transductive("spectral")
True
check_embedding_name(embedding)[source]#

Normalize and validate an embedding name, raising if it is unknown.

get_embeddings() calls this, so a caller that is about to run many embeddings can validate the whole list before doing any work and get the identical message. QProfiler uses it for exactly that: a typo in the sixth entry of embeddings used to surface only after the first five had run.

Parameters:

embedding (str) – Method name, case-insensitive, surrounding space ignored.

Returns:

The normalized (lower-cased, stripped) name.

Return type:

str

Raises:

ValueError – if embedding is not a string, or names no known method. The message lists close matches and the valid sklearn modes.

get_embeddings(embedding, X_train, X_test, n_neighbors=30, n_components=None, method=None, quvine_args=None)[source]#

Apply an embedding to the training and test datasets.

Inductive methods are fit on X_train and applied to X_test through transform. Transductive methods (spectral and every QuVINE method) have no out-of-sample transform, so they are fit once on the concatenated rows and sliced back; a UserWarning is emitted and is_transductive() reports which is which.

Parameters:

  • embedding (str) –

    The embedding to use.

    • scikit-learn / UMAP modes: 'none', 'pca', 'nmf', 'lle', 'isomap', 'spectral', 'umap'. Listed in SKLEARN_METHODS.

    • QuVINE graph embeddings, accepted on exactly the same footing: 'quvine_fused', 'quvine_rwr', 'quvine_dtqw', 'quvine_ctqw', 'node2vec', 'netmf', 'appnp' and 76 more. The full list is QUVINE_METHODS; the headline names are QUVINE_HEADLINE_METHODS. These need the optional extra: pip install "qbiocode[quvine]".

  • X_train (array-like) – The training dataset.

  • X_test (array-like) – The test dataset.

  • n_neighbors (int, optional) – Number of neighbors for the neighbor-based embeddings and for the QuVINE kNN sample graph. Defaults to 30.

  • n_components (int, optional) – Width of the embedding. If None, defaults to the number of features in X_train.

  • method (str, optional) – Method for Locally Linear Embedding. Defaults to None.

  • quvine_args (dict, optional) – Extra config overrides forwarded to QuVINE embed when embedding is a QuVINE method, e.g. {"walks": {"steps": 4}, "train": {"epochs": 10}}. Ignored for the sklearn modes.

Returns:

(X_train_embedded, X_test_embedded).

Return type:

tuple

Raises:

  • ValueError – if embedding is not a known name (the message lists close matches), if n_components is not a positive integer, if n_components exceeds the feature count for an sklearn mode, or if X_train/X_test are not 2-D arrays with matching widths.

  • QuvineDependencyError – if a QuVINE method is requested without the [quvine] extra installed. The message names the extra and the install command.

Warns:

UserWarning – once per call, when embedding is transductive.

Examples

>>> Z_tr, Z_te = get_embeddings("pca", X_train, X_test, n_components=8)
>>> Z_tr, Z_te = get_embeddings("quvine_rwr", X_train, X_test, n_components=8)