cellmaps_coembedding package

Subpackages

Submodules

cellmaps_coembedding.cellmaps_coembeddingcmd module

cellmaps_coembedding.cellmaps_coembeddingcmd.main(args)[source]

Main entry point for program

Parameters:

args (list) – arguments passed to command line usually sys.argv[1:]()

Returns:

return value of cellmaps_coembedding.runner.CellmapsCoEmbedder.run() or 2 if an exception is raised

Return type:

int

cellmaps_coembedding.exceptions module

exception cellmaps_coembedding.exceptions.CellmapsCoEmbeddingError[source]

Bases: Exception

Base exception for cellmaps_coembedding

cellmaps_coembedding.runner module

class cellmaps_coembedding.runner.AutoCoEmbeddingGenerator(dimensions=128, outdir=None, embeddings=None, ppi_embeddingdir=None, image_embeddingdir=None, embedding_names=None, jackknife_percent=0.0, n_epochs=100, save_update_epochs=True, batch_size=16, triplet_margin=0.2, dropout=0.5, l2_norm=False, mean_losses=False, lambda_reconstruction=1.0, lambda_l2=0.001, lambda_triplet=1.0)[source]

Bases: ProteinGPSCoEmbeddingGenerator

Generates co-embedding using the legacy ProteinGPS configuration.

Deprecated since version 1.0.0: The embedding was renamed to ProteinGPS, and the implementation now lives in ProteinProjectorCoEmbeddingGenerator.

Initializes a ProteinProjectorCoEmbeddingGenerator.

class cellmaps_coembedding.runner.CellmapsCoEmbedder(outdir=None, inputdirs=None, embedding_generator=None, name=None, organization_name=None, project_name=None, provenance_utils=<cellmaps_utils.provenance.ProvenanceUtil object>, skip_logging=True, input_data_dict=None, provenance=None)[source]

Bases: object

Executes the generation of co-embeddings from multiple biological embedding sources.

This class coordinates the loading of input embeddings (e.g., image, PPI), invokes a co-embedding generator (such as ProteinGPS or MUSE), and handles output generation, provenance tracking, and dataset registration.

Constructor

Parameters:

  • outdir (str) – Directory to write the results of this tool

  • inputdirs (list[str]) – Input directories where embeddings to be coembedded are located (e.g. output of cellmaps_image_embedding and cellmaps_ppi_embedding)

  • embedding_generator (EmbeddingGenerator) – An instance of a co-embedding generator class that produces combined embeddings. Must implement the method get_next_embedding(): ProteinGPSCoEmbeddingGenerator, : py:class:~MuseCoEmbeddingGenerator, or FakeCoEmbeddingGenerator.

  • skip_logging (bool) – If True skip logging, if None or False do NOT skip logging

  • name (str or None) – Optional display name for the generated co-embedding dataset. If not provided, the name is inferred from RO-Crate metadata or fallback values.

  • organization_name (str or None) – Optional name of the organization creating the co-embedding. Used in provenance metadata. Inferred if not specified.

  • project_name (str or None) – Optional name of the project associated with this co-embedding run. Used for provenance metadata. Inferred if not specified.

  • provenance_utils (py:class:~ProvenanceUtil) – Utility object for generating and registering RO-Crates, datasets, computations, and software metadata. Defaults to a new instance of py:class:~ProvenanceUtil.

  • input_data_dict (dict or None) –

    Optional dictionary representing the input configuration.

    Example:

    {'outdir': '/path/to/output','inputdirs': ['/path/to/image', '/path/to/ppi']}

  • provenance (dict or None) –

    Optional dictionary specifying metadata for dataset registration when RO-Crate metadata is not available in inputdirs. This is used to describe the data context, authorship, and keywords.

    Example:

    {
    'name': 'Coembedded Dataset',
    'organization-name': 'CM4AI',
    'project-name': 'Gene Atlas',
    'description': 'Merged representation of protein and image embeddings.',
    'keywords': ['coembedding', 'multi-omics']
}

generate_readme()[source]
get_coembedding_file()[source]

Gets image embedding file :return:

run()[source]

Runs CM4AI Generate COEMBEDDINGS

Returns:

class cellmaps_coembedding.runner.EmbeddingGenerator(dimensions=128, ppi_embeddingdir=None, image_embeddingdir=None, embeddings=None, embedding_names=None)[source]

Bases: object

Base class for implementations that generate network embeddings

Constructor

DROPOUT = 0.5
JACKKNIFE_PERCENT = 0.0
K = 10
LATENT_DIMENSIONS = 128
N_EPOCHS = 100
get_dimensions()[source]

Gets number of dimensions this embedding will generate

Returns:

number of dimensions aka vector length

Return type:

int

get_embedding_inputdirs()[source]

Determines the input directories for embeddings by extracting the directory path from each embedding file path. If the path is already a directory, it’s returned as is.

Returns:

A list of directory paths for each embedding, derived from the embedding file paths.

Return type:

list

get_next_embedding()[source]

Generator method for getting next embedding. Caller should implement with yield operator

Raises:

NotImplementedError: Subclasses should implement this

Returns:

Embedding

Return type:

list

class cellmaps_coembedding.runner.FakeCoEmbeddingGenerator(dimensions=128, ppi_embeddingdir=None, image_embeddingdir=None, embeddings=None, embedding_names=None)[source]

Bases: EmbeddingGenerator

Generates a fake coembedding for intersection of embedding dirs

Constructor :param dimensions:

get_next_embedding()[source]

Gets next embedding

Returns:

class cellmaps_coembedding.runner.MuseCoEmbeddingGenerator(dimensions=128, k=10, triplet_margin=0.1, dropout=0.5, n_epochs=100, n_epochs_init=100, outdir=None, embeddings=None, ppi_embeddingdir=None, image_embeddingdir=None, embedding_names=None, jackknife_percent=0.0)[source]

Bases: EmbeddingGenerator

Generats co-embedding using MUSE

Parameters:

  • dimensions

  • k – k nearest neighbors value used for clustering - clustering used for triplet loss

  • triplet_margin – margin for triplet loss

  • dropout – dropout between neural net layers

  • n_epochs – training epochs

  • n_epochs_init – initialization training epochs

  • outdir

  • ppi_embeddingdir

  • image_embeddingdir

  • jackknife_percent – percent of data to withhold from training

N_EPOCHS_INIT = 100
get_next_embedding()[source]
Returns:

class cellmaps_coembedding.runner.ProMERGECoEmbeddingGenerator(dimensions=128, outdir=None, embeddings=None, ppi_embeddingdir=None, image_embeddingdir=None, embedding_names=None, n_epochs=300, save_update_epochs=True, batch_size=16, triplet_margin=0.5, dropout=0, l2_norm=True, mean_losses=False, learn_rate=0.0001, hidden_size_1=512, hidden_size_2=256, negative_from_batch=False, cond_str_list=['base', 'query'], mod_str_list=['mod1', 'mod2'], mod_str_list_mine=None, lambda_reconstruction=1.0, lambda_disentangle=1.0, lambda_triplet_disentangle=1.0, lambda_l2_disentangle=0, lambda_l2_latent=0, lambda_var=0.1, disentangle_method='MINE')[source]

Bases: EmbeddingGenerator

Generates co-embeddings of a query context based on a base context with ProMERGE method.

Parameters:

  • cond_str_list – list of str. Strings in the embedding_names for contexts.

  • mod_str_list – list of str. Strings in the embedding_names for modalities.

  • mod_str_list_mine – list of str. Subset of mod_str_list to apply MINE disentanglement to. If None, apply to all modalities.

  • lambda_reconstruction – Weight for reconstruction loss.

  • lambda_disentangle – Weight for disentanglement loss.

  • lambda_triplet_disentangle – Weight for triplet loss.

  • lambda_l2_disentangle – Weight for L2 regularization on disentanglement.

  • lambda_l2_latent – Weight for L2 regularization on latent space.

  • lambda_var – Weight for variance regularization on latent space.

  • disentangle_method – Method for disentanglement. Options: “MINE”, “subtract”.

get_next_embedding()[source]

Iteratively generates embeddings

Returns:

Yields the next embedding.

class cellmaps_coembedding.runner.ProteinGPSCoEmbeddingGenerator(dimensions=128, outdir=None, embeddings=None, ppi_embeddingdir=None, image_embeddingdir=None, embedding_names=None, jackknife_percent=0.0, n_epochs=100, save_update_epochs=True, batch_size=16, triplet_margin=1.0, dropout=0.5, l2_norm=False, mean_losses=False, lambda_reconstruction=1.0, lambda_l2=0.001, lambda_triplet=1.0, learn_rate=0.0001, hidden_size_1=512, hidden_size_2=256, negative_from_batch=False)[source]

Bases: ProteinProjectorCoEmbeddingGenerator

Deprecated generator that proxies to ProteinProjectorCoEmbeddingGenerator.

Deprecated since version 1.5.0: Use ProteinProjectorCoEmbeddingGenerator instead.

Initializes a ProteinProjectorCoEmbeddingGenerator.

class cellmaps_coembedding.runner.ProteinProjectorCoEmbeddingGenerator(dimensions=128, outdir=None, embeddings=None, ppi_embeddingdir=None, image_embeddingdir=None, embedding_names=None, jackknife_percent=0.0, n_epochs=100, save_update_epochs=True, batch_size=16, triplet_margin=1.0, dropout=0.5, l2_norm=False, mean_losses=False, lambda_reconstruction=1.0, lambda_l2=0.001, lambda_triplet=1.0, learn_rate=0.0001, hidden_size_1=512, hidden_size_2=256, negative_from_batch=False)[source]

Bases: EmbeddingGenerator

Generates co-embeddings using the ProteinProjector algorithm (formerly ProteinGPS).

Initializes a ProteinProjectorCoEmbeddingGenerator.

get_next_embedding()[source]

Iteratively generates embeddings by fitting ProteinProjector to the current data set.

cellmaps_coembedding.utils module

Module contents

Top-level package for CM4AI Generate PPI.