Source: https://docs.nygen.io/CyteOnto/getting-started/how-cyteonto-works/ Revision: cb82698da3fc9e2bc385eb9a70e07f9304835eba Structured page: https://docs.nygen.io/CyteOnto/getting-started.how-cyteonto-works.json How CyteOnto works CyteOnto does not compare label strings. It maps each label to a term of the Cell Ontology and compares the terms. Two labels that map to the same term, such as Treg and regulatory T cell, score 1 however they are worded, and labels that map to different terms score by how related those terms are. Prepare the ontology The mapping file lists 6,155 labels, the names and synonyms of 2,902 Cell Ontology terms. For each term, CyteOnto joins its lowercase labels with semicolons, such as alveolar macrophage;dust cell;mf.lu for CL:0000583. The LLM describes each term as a CellDescription with five fields. This is the description of CL:0000815, regulatory T cell, in the precomputed files: Field Value initialLabel regulatory t cell;regulatory t lymphocyte;regulatory t-cell;regulatory t-lymphocyte;suppressor t cell;suppressor t lymphocyte;suppressor t-cell;suppressor t-lymphocyte;treg descriptiveName CD4-positive regulatory T lymphocyte function Suppresses immune responses and maintains self-tolerance by inhibiting effector T cell proliferation and cytokine production. Limits inflammation and prevents autoimmunity through contact-dependent and cytokine-mediated mechanisms. diseaseRelevance Deficiency causes severe autoimmune diseases such as IPEX syndrome. Expanded populations occur in tumors and chronic infections, promoting immune evasion. Adoptive Treg therapy is explored for autoimmune diseases and transplantation. developmentalStage Terminally differentiated; arises in thymus from CD4 single-positive thymocytes or periphery from conventional CD4 T cells The embedding model then embeds each description, joined into one sentence. The descriptions depend on the LLM and the embeddings on both models, so CyteOnto keeps them in files named after the model pair. python -m cyteonto.setup downloads the files of the default model pair, and CyteOnto.from_config() generates any that are missing (see Models and providers ). Compare labels For each call of compare(): Lowercase. Non-empty labels are lowercased, so that Plasma cell and plasma cell share their caches. The results show the lowercased labels. Split compound labels. The LLM decides whether each distinct label names one cell type or several, as a doublet or a mixed population does, and splits the latter into their cell types. Semicolons separate synonyms of one cell type, and the prompt tells the model not to split them. See Compound labels . Describe. The LLM writes a CellDescription of each distinct label or part, in the same way as for the ontology terms. If a label cannot be described after all retries, the label text itself is embedded instead. Embed. The embedding model embeds each description. Match. CyteOnto computes the cosine similarity of each embedding with the embeddings of all 2,902 terms and keeps the closest term. A label whose closest term has a similarity below min_match_similarity, 0.1 by default, stays unmatched. Score. For each position, the author’s term and the algorithm’s term are scored with the chosen metric, by default cosine_kernel, which compares the embeddings of the two terms’ descriptions. Compound labels are scored part by part, and the part scores are reduced to one score. A pair with an empty label, or with a single-part label that matched no term, scores 0. See Similarity metrics . Return the results. A DataFrame with one row per algorithm and position. See Read the results . The decompositions, descriptions and embeddings of the labels are saved under the run_id of the call, so a second call with the same labels and run_id calls no model (see Caching and runs ). What CyteOnto sends to the providers To the LLM provider: each distinct label, in the prompts that split it and describe it. Only the model of your pydantic-ai agent is used; CyteOnto sends its own instructions. To NCBI: with use_pubmed_tool=True, the default, the model may search PubMed while it describes a label, and its search terms are sent to NCBI’s E-utilities. To the embedding provider: the text of each description, which starts with the label. When you run the package yourself, your labels go only to these providers, and to the fallback providers if you configure them, and the caches stay on your disk. python -m cyteonto.setup only downloads files. With the hosted API , your labels go to the CyteOnto service, which calls its own providers and keeps the results, descriptions and embeddings of each job. What it costs Step Model requests from_config() with the precomputed files of the model pair None from_config() with another LLM One description per term, 2,902, and one embedding per term, once from_config() with the default LLM and another embedding model One embedding per term, 2,902, once compare() One request to split each distinct label of the run. Then, separately for the author labels and for each algorithm, one description and one embedding of each distinct label or part compare() at the first embedding failover One embedding per term, 2,902, with the fallback model, unless its ontology embeddings exist. The labels embedded earlier in the call are embedded again with the fallback model compare() again with the same run_id and labels None So a label that both the authors and an algorithm use is described and embedded twice. A description takes one more request for each PubMed search, and failed requests are retried. CyteOnto.usage counts the requests and tokens of the LLM calls that succeeded.