Source: https://docs.nygen.io/CyteOnto/api/cyteonto.html Revision: cb82698da3fc9e2bc385eb9a70e07f9304835eba CyteOnto class ************** "CyteOnto" compares cell type labels in Cell Ontology space. "from_config()" creates it and makes sure that the descriptions and embeddings of the Cell Ontology terms are on disk. "compare()" scores author labels against the labels of one or more algorithms and returns a DataFrame, and "compare_anndata()" reads the algorithm labels from "adata.obs". "cache_stats()", "clear_run()" and "purge_stale()" manage the caches of comparison runs. from cyteonto import CyteOnto cyto = await CyteOnto.from_config(agent=agent, embedding=embedding, llm=llm) df = await cyto.compare( author_labels=["alveolar macrophage", "regulatory T cell"], algorithms={"method_a": ["lung macrophage", "Treg"]}, run_id="lung_v1", ) "from_config()", "compare()" and "compare_anndata()" are coroutines: "await" them in a notebook, or run them with "asyncio.run()" in a script. The Python quickstart runs these steps, Read the results describes the DataFrame, and Caching and runs describes what each call saves on disk. class cyteonto.CyteOnto(agent, embedding, llm, data_dir=None, user_dir=None, max_description_concurrency=100, use_pubmed_tool=True, reasoning=False, fallback_agent=None, fallback_embedding=None, fallback_llm=None) Compare two sets of cell type annotations against the Cell Ontology. Typical use: cyto = await CyteOnto.from_config(agent=agent, embedding=embd_cfg, llm=llm_cfg) results = await cyto.compare( run_id="sample_run", author_labels=[...], algorithms={"algo1": [...], "algo2": [...]}, ) Set up paths and cache keys without loading the ontology or calling a model. Parameters: * **agent** ("Agent") – pydantic-ai agent whose model describes cell types and splits compound labels. * **embedding** ("EmbdConfig") – Embedding provider and model. When "embedding.apiKey" is "None", the key is read from the provider’s environment variable, such as "NEBIUS_API_KEY", or else from "EMBEDDING_MODEL_API_KEY". * **llm** ("LlmConfig") – Provider and model of "agent", which name the description caches. "llm.model" must equal "agent.model.model_name". * **data_dir** ("str" | "Path" | "None", default: "None") – Directory with the Cell Ontology files and the ontology caches. Defaults to the "data" directory inside the installed package. * **user_dir** ("str" | "Path" | "None", default: "None") – Directory for the caches of comparison runs. Defaults to "/user_files". * **max_description_concurrency** ("int", default: "100") – Maximum number of LLM requests that run at the same time. * **use_pubmed_tool** ("bool", default: "True") – Let the agent search PubMed abstracts while it describes a label. * **reasoning** ("bool", default: "False") – Leave the model’s reasoning mode as the provider sets it. When "False", the requests ask the provider to turn reasoning off. * **fallback_agent** ("Agent" | "None", default: "None") – Agent that describes the labels whose description is still blank after the primary agent’s retries. * **fallback_embedding** ("EmbdConfig" | "None", default: "None") – Embedding configuration to use when the primary embedding provider fails, unless it equals "embedding". The instance first loads the ontology embeddings of this model, or makes them from the ontology descriptions, and then keeps embedding with it. If that step fails, the call raises and the instance keeps the primary model. * **fallback_llm** ("LlmConfig" | "None", default: "None") – Provider and model of "fallback_agent". It is reported in "model_pair_usage"; descriptions from the fallback agent are cached under "llm". Raises: **ValueError** – If no embedding API key is found for a provider other than "ollama", or if "llm.model" differs from the agent’s model name. usage: cyteonto.AgentUsage The requests and tokens of the successful LLM calls of this instance, to describe and to split labels, including those of "from_config()". Failed attempts and embedding requests are not counted. model_pair_usage: cyteonto.ModelPairUsage Whether the primary or the fallback LLM and embedding models were used. async classmethod from_config(agent, embedding, llm, data_dir=None, user_dir=None, force_regenerate=False, max_description_concurrency=100, use_pubmed_tool=True, reasoning=False, fallback_agent=None, fallback_embedding=None, fallback_llm=None) Create a "CyteOnto" and make sure the ontology embeddings are on disk. Takes the arguments of "CyteOnto" and "force_regenerate". Loads the descriptions of the Cell Ontology terms for "llm" from "data_dir" and checks that the term embeddings for "llm" and "embedding" exist. Terms without a description are described with "agent", and "fallback_agent" if given, and then every term is embedded again. When every term has a description and the embeddings file was made after the descriptions last changed, no model is called. If "embedding" fails to embed the terms, the instance checks that "fallback_embedding" works and switches to it and its ontology embeddings, which are made if they are missing. Parameters: **force_regenerate** ("bool", default: "False") – Delete the ontology descriptions of "llm", which all model pairs with this LLM share, and their embeddings with "embedding" and "fallback_embedding" first. The descriptions and the embeddings with "embedding" are then made again for every term, and those with "fallback_embedding" at the next failover. Raises: * **ValueError** – For the same reasons as the constructor. * **FileNotFoundError** – If "cell_to_cell_ontology.csv", "cell_to_cell_ontology_enriched.csv" or "cl.owl" is missing from "/cell_ontology". * **RuntimeError** – If the ontology CSV cannot be read, or the term embeddings cannot be made or saved. Return type: "CyteOnto" async compare(author_labels, algorithms, *, run_id=None, metric='cosine_kernel', metric_params=None, min_match_similarity=0.1, use_cache=True, compound_scoring='max') Compare author labels with the labels of one or more algorithms. Labels are lowercased, compound labels are split into cell types, and each label or part is described, embedded and matched to its closest Cell Ontology term. Each author label is then scored against the algorithm label at the same position. Parameters: * **author_labels** ("list"["str"]) – Reference labels, one per item, such as a cell or a cluster. * **algorithms** ("dict"["str", "list"["str"]] | "Sequence"["tuple"["str", "list"["str"]]]) – Mapping "{algo_name: labels}" (or sequence of pairs). Each label list must be the same length as "author_labels". Algorithm names must be unique, and ""author"" is reserved. * **run_id** ("str" | "None", default: "None") – Unique identifier for this comparison. Used to namespace user caches on disk and to tag each result row. Reuse the same "run_id" across calls to benefit from caching; pass it to "clear_run" to delete the descriptions and embeddings. If "None", an id of the form "run-" is generated and logged. * **metric** ("str", default: "'cosine_kernel'") – Similarity metric for each pair of matched terms: "cosine_kernel", "cosine_direct", "path", "set:jaccard", "set:cosine", "set:weighted_jaccard", "weighted:num_ancestors", "weighted:specificity", "weighted:embedding_cosine" or "simple". Other names fall back to "simple". * **metric_params** ("dict"["str", "Any"] | "None", default: "None") – Parameters of "cosine_kernel": the "center", "width" and "amplitude" of its Gaussian. Other metrics ignore them. * **min_match_similarity** ("float", default: "0.1") – Lowest cosine similarity between a label and its closest Cell Ontology term at which the label counts as matched. * **use_cache** ("bool", default: "True") – When "True", reuse the label decompositions, descriptions and embeddings saved for "run_id". When "False", generate them again. * **compound_scoring** ("Literal"["'max'", "'hungarian_mean'"], default: "'max'") – How to reduce the m×n part score matrix for compound pairs. ""max"" takes the maximum entry; ""hungarian_mean"" uses Hungarian assignment mean with a coverage penalty when m != n. Return type: "DataFrame" Returns: DataFrame with one row per (algorithm, pair_index) combination. The "run_id" column is populated with the id used for this call (the caller-provided value or the auto- generated UUID). Raises: * **ValueError** – If "compound_scoring" is invalid, "algorithms" is empty, an algorithm name is repeated or is ""author"", or a label list differs in length from "author_labels". * **RuntimeError** – If labels cannot be embedded, or, at an embedding failover, the ontology embeddings of the fallback model cannot be made or saved; the instance then keeps the primary model. * **FileNotFoundError** – If the ontology embeddings of the model pair are missing, or, at an embedding failover, both those of the fallback model and the ontology descriptions to make them from. Run "from_config" first. async compare_anndata(author_labels, anndata_objects, target_columns, author_column, *, run_id=None, algorithm_names=None, metric='cosine_kernel', metric_params=None, min_match_similarity=0.1, use_cache=True, compound_scoring='max') Pull algorithm labels out of "adata.obs" and delegate to "compare". Each column in "target_columns" becomes one algorithm. Its values are converted to strings, so missing values become labels such as ""nan"". Parameters: * **author_labels** ("list"["str"]) – Reference labels, one per row of "adata.obs". * **anndata_objects** ("Sequence"["Any"]) – AnnData objects to read the columns from, each with one row per author label. An object without "author_column" in "obs" is skipped with a warning. With several objects, each algorithm name ends with the position of its object, such as "pred_0" and "pred_1". * **target_columns** ("list"["str"]) – Columns of "adata.obs" with the algorithm labels. A missing column is skipped with a warning. * **author_column** ("str") – Column that each object must have in "obs". Only its presence is checked; the author labels come from "author_labels". * **run_id** ("str" | "None", default: "None") – As in "compare": pass one to reuse caches, or "None" to let the call generate and log one. * **algorithm_names** ("list"["str"] | "None", default: "None") – Names of the algorithms in the results, one per target column. Defaults to the column names. * **metric** ("str", default: "'cosine_kernel'") – As in "compare". * **metric_params** ("dict"["str", "Any"] | "None", default: "None") – As in "compare". * **min_match_similarity** ("float", default: "0.1") – As in "compare". * **use_cache** ("bool", default: "True") – As in "compare". * **compound_scoring** ("Literal"["'max'", "'hungarian_mean'"], default: "'max'") – As in "compare". Return type: "DataFrame" Returns: The DataFrame that "compare" returns. Raises: **ValueError** – If "algorithm_names" and "target_columns" differ in length, or for the reasons that "compare" raises it, such as an object whose number of rows differs from "author_labels". cache_stats(run_id=None) Summarise on-disk user embedding caches. Parameters: **run_id** ("str" | "None", default: "None") – If given, restrict stats to that run. Otherwise aggregates across all runs under "user_dir/embeddings". Return type: "dict"["str", "Any"] Returns: A dict with "root" (the directory searched), "total_files" (the number of NPZ files), "total_size_mb" and "stale_files" (NPZ files that cannot be loaded, such as files without inline labels). clear_run(run_id, kind=None, identifier=None) Delete user embeddings and descriptions for a run. The label decompositions of the run are kept. Parameters: * **run_id** ("str") – The run identifier used in "compare(...)". * **kind** ("str" | "None", default: "None") – ""author"" or ""algorithm"". If omitted, all kinds under "run_id" are removed. * **identifier** ("str" | "None", default: "None") – When "kind" is given, restrict to a single identifier (e.g. one algorithm name) and to the files of the current model pair. Ignored if "kind" is "None". Return type: "int" Returns: Number of files removed. Raises: **ValueError** – If "kind" is not ""author"", ""algorithm"" or "None". purge_stale(run_id=None) Delete user NPZ files that cannot be loaded (such as the stale format). Files in the stale format lack the inline labels. Parameters: **run_id** ("str" | "None", default: "None") – If given, only delete files of that run. Return type: "int" Returns: Number of files removed.