How to use CoSiNE online

CoSiNE online currently supports zero-shot variant effect prediction (VEP) for paired-antibody deep mutational scanning data. Upload a CSV containing heavy-chain sequences, light-chain sequences, and experimental fitness, then calculate CoSiNE likelihoods, perplexities, assay correlations, and optional somatic-hypermutation-corrected selection scores.^[1][2]

The main caveat is that antibody evolution cannot run yet. CoSiNE's evolution interface needs a RefineGNN binding-predictor checkpoint that its authors have not published, so use Variant effect prediction for the available workflow. The CoSiNE webserver shows this status before submission.^[2][3]

For a first run:

What is CoSiNE?

CoSiNE stands for Conditionally Site-Independent Neural Evolution. It is a neural continuous-time Markov chain (CTMC) trained to model antibody sequence change during affinity maturation. The model factorizes transition probabilities across residue sites for tractable inference, while conditioning each site's rate matrix on the complete input sequence so surrounding residues can influence the prediction.^[1]

That design supports two scientific tasks:

• Variant effect prediction: score observed amino-acid variants without training on the submitted assay.
• Antibody evolution: sample mutation trajectories with unguided or predictor-guided Gillespie sampling and optional CDR or framework constraints.

The online VEP task is available. The evolution form is documented and visible, but its jobs are blocked until the CoSiNE authors publish the exact binding-predictor checkpoint required by their implementation.^[2][3]

CoSiNE scores how compatible a sequence transition is with its learned antibody-evolution process. It does not directly calculate a dissociation constant, expression yield, aggregation risk, or clinical developability.

How does CoSiNE variant scoring work?

It scores a transition, not an isolated sequence

For each DMS variant, CoSiNE compares a resolved wild-type or consensus sequence with the submitted mutant at a branch length t. Branch length represents evolutionary time in the CTMC. It controls how much sequence change the model expects between the starting and ending states.^[1]

The result table contains two raw metrics for every requested branch length:

Only compare these values under the same axis, paired-context choice, branch length, and sequence-length convention. A score from heavy with single-chain context is not directly interchangeable with a score from combined with paired context.

Scoring axes define which mutation is evaluated

CoSiNE separates mutation selection from sequence context:

This distinction matters for rows containing mutations in both chains. The heavy result isolates the submitted heavy-chain change while holding the light chain at the resolved wild type. The light result does the reverse. Choose combined when the biological question concerns the joint heavy-light variant.

When Use paired heavy-light context is disabled, the heavy and light axes are scored as separate single-chain transitions. Combined scoring always uses both chains. Paired context is a sensible first choice for paired antibodies, but it is also a model choice worth testing rather than an automatic guarantee of better assay correlation.^[1]

Thrifty correction separates mutation tendency from selection signal

Somatic hypermutation does not introduce every nucleotide change with equal probability. Local nucleotide context affects which mutations are likely to occur before antigen-driven selection acts. Thrifty models this neutral mutation process using wide nucleotide context.^[4]

With Apply Thrifty SHM correction enabled, CoSiNE calculates:

corrected_ll_<t>_<bl> = CoSiNE log-likelihood at t - Thrifty log-likelihood at bl

The corrected value asks whether a variant is more compatible with the learned affinity-maturation process than expected from neutral SHM alone. It is called a selection score in the CoSiNE implementation. The correction needs wild-type coding DNA because neutral SHM probabilities depend on nucleotide context, not only on the translated amino-acid sequence.^[1][4]

Correlations connect model scores with the submitted assay

The webserver calculates either Spearman or Pearson correlation between every raw score column and the submitted experimental fitness values. Spearman measures monotonic rank association and is the default. Pearson measures linear association and is more sensitive to scale and outliers.

The raw correlation file uses perplexity directly. Because lower perplexity means a more likely transition, a useful perplexity signal can have the opposite sign from the corresponding log-likelihood signal. Read the metric column before interpreting the sign.

Correlation is a property of the submitted dataset and assay. It is not a per-variant confidence score and does not establish performance on a different antigen, library, or measurement protocol. The CoSiNE paper also notes that its training data do not specify the selecting antigens, so a high model score is not automatically evidence of binding to the user's target.^[1]

How to prepare a CoSiNE DMS table

Required columns

The simplest CSV has these headers:

heavy,light,fitness
HEAVY_CHAIN_AA_SEQUENCE,LIGHT_CHAIN_AA_SEQUENCE,1.0
HEAVY_CHAIN_VARIANT,LIGHT_CHAIN_AA_SEQUENCE,0.73

Use real amino-acid sequences in place of the labels above. The table must satisfy these rules:

• heavy contains one heavy-chain amino-acid sequence per row.
• light contains one light-chain amino-acid sequence per row.
• fitness contains numeric experimental measurements.
• All heavy-chain sequences have the same length.
• All light-chain sequences have the same length.
• Protein sequences use the 20 canonical amino acids.

If your table uses headers such as VH, VL, or binding_score, enter those exact names in DMS column mapping. Extra assay metadata columns are preserved in the axis result tables.

Wild type and consensus handling

When explicit consensus sequences are empty, CoSiNE resolves the heavy and light wild types site by site from the submitted table. That is convenient when the library is centered on one parental antibody and the parental residue is the most common at every position.

Provide Heavy-chain consensus and Light-chain consensus explicitly when you know the parental sequence or when a combinatorial library makes site-by-site majority resolution ambiguous. The consensus must have the same length as its chain column.

Wild-type rows are useful for defining the assay baseline, but the scored axis tables contain non-wild-type variants. CoSiNE derives mutation labels by comparing each sequence with the resolved consensus unless you map precomputed heavy or light mutation columns.

Coding DNA for SHM correction

For every selected scoring axis, upload the matching wild-type coding sequence:

• heavy requires heavy-chain coding DNA.
• light requires light-chain coding DNA.
• combined requires both heavy-chain and light-chain coding DNA.

Each DNA sequence must use uppercase A, C, G, and T, contain one coding record, and translate exactly to the resolved amino-acid consensus. A synonymous construct that translates correctly is acceptable as input, but its codon context changes the Thrifty neutral-mutation likelihood. Use the actual parental coding sequence when available.

If the coding DNA is unavailable, turn off SHM correction and report that you analyzed raw CoSiNE likelihoods and perplexities.

How to choose CoSiNE settings

Start with branch length 0.2

The online default is 0.2. It is a defensible first value for VEP and keeps the first run aligned with the implemented preset. The CoSiNE paper reports that selection-score correlations were relatively stable across moderate branch lengths from 0.1 to 0.4 on its evaluated datasets, but this does not make branch length irrelevant for every assay.^[1]

For a sensitivity analysis, run 0.1,0.2,0.4 together. Compare rankings and correlations, then predefine or report the choice instead of selecting the best-looking value on the same data without qualification.

Use heavy and light before combined

The default heavy, light axes are useful when a DMS experiment changes one chain at a time or when you want chain-specific interpretation. Add combined for paired variants in which both submitted chains differ from the wild type.

Do not infer a combined effect by adding heavy and light scores. Combined mode evaluates the paired transition directly and can differ from an arithmetic sum because the model conditions rates on the complete sequence.

Keep paired context on, then test the assumption

Paired context uses the wild-type partner chain while scoring a heavy-only or light-only mutation. This preserves information about the antibody pair. For an intentionally unpaired library, single-chain context may be the more faithful setup.

When context could affect a conclusion, run both settings and report whether rankings are stable. Treat that comparison as a sensitivity analysis, not a search for whichever configuration gives the largest correlation.

Choose Spearman or Pearson before looking at the answer

Use Spearman when the main question is whether CoSiNE ranks variants consistently with fitness, especially when the assay is nonlinear or has outliers. Use Pearson when a linear relationship on the chosen fitness scale is scientifically justified.

Enable Log-transform experimental fitness only when all analyzed values are positive and a logarithmic assay scale makes sense. Zero or negative fitness values cannot be logged. Record the transformation because it changes Pearson correlations and can also affect how a reader understands the assay.

A reproducible first analysis

The official CoSiNE repository includes scripts/vep/data_dms/binding/Koenig2017_g6_binding.csv as its example table and uses scripts/vep/cosine_antibody_vep.ipynb for the VEP analysis. The dataset originates from a published deep mutational analysis of antibody variable domains.^[3][5]

To reproduce the interface without inventing benchmark results:

1. Obtain the example CSV from the pinned official CoSiNE repository.
2. Open CoSiNE online and select Variant effect prediction.
3. Upload the CSV and confirm that its heavy, light, and fitness headers match the column mapping.
4. Select heavy and light, keep paired context enabled, and enter 0.2 for CoSiNE branch lengths.
5. If you have the exact parental coding DNA, add it and keep Thrifty correction enabled. Otherwise, disable correction.
6. Use Spearman correlation without a fitness log transform for the first pass.
7. Submit the job and retain the axis tables, correlation files, submitted CSV, log, and provenance JSON together.

This procedure checks the data contract and analysis path. It does not claim that your run will reproduce a specific correlation value, because exact inputs, consensus handling, coding DNA, correction settings, and software revision all affect the result.

How to interpret CoSiNE outputs

Axis result tables

Each selected axis produces one primary CSV:

• cosine_vep_heavy.csv
• cosine_vep_light.csv
• cosine_vep_combined.csv

The table preserves submitted assay columns and adds chain, mutation, raw score columns, and optional corrected score columns. Use the original assay identifier columns to join results back to sample metadata.

Rank by ll_<t> from high to low or by ppl_<t> from low to high within one consistent setup. For corrected results, larger corrected_ll_<t>_<bl> means the transition is more likely under CoSiNE relative to the neutral SHM model. Do not compare absolute values across different axes as if they shared one universal scale.

Raw correlation file

cosine_correlations.csv contains:

Inspect sample count and the underlying scatter or rank pattern before treating a correlation as useful. A large coefficient from a small library can be unstable. Multiple branch lengths and metrics also create multiple comparisons; do not read an isolated p-value as validation of the complete workflow.

Selection correlation file

When correction is enabled, cosine_selection_correlations.csv contains a compact matrix for each chain. correction is no_correction or a Thrifty branch length such as bl=0.2. Columns such as t=0.2 identify CoSiNE branch lengths. Each cell is the selected correlation coefficient between fitness and the corresponding raw or corrected log-likelihood.

Use this matrix to assess whether neutral SHM correction changes the assay association. It is not a leaderboard for choosing parameters after the fact.

Audit files

Keep these files with any reported analysis:

• submitted_dms.csv is the unchanged input table.
• cosine_source.log contains diagnostic output from the CoSiNE analysis.
• cosine_provenance.json records the pinned implementation, model checkpoint, and resolved settings.

Together, they make it possible to distinguish a biological change in the data from a change in configuration or model revision.

How to validate CoSiNE predictions

Check data integrity first

Before interpreting scores:

• confirm that each sequence is assigned to the correct antibody and assay row
• verify heavy and light chain orientation and variable-domain boundaries
• confirm the parental amino-acid and coding sequences
• inspect replicate agreement and fitness normalization
• check that mutation labels match the submitted sequences
• record missing values, censoring, and assay floors or ceilings

One shifted row or mismatched chain can create a convincing but meaningless correlation.

Test sensitivity without cherry-picking

Compare a small, predefined set of defensible choices:

• branch lengths 0.1, 0.2, and 0.4
• paired and single-chain context when both are biologically plausible
• raw and Thrifty-corrected likelihood when the correct coding DNA is available
• Spearman and Pearson only when both answer a stated analysis question

Stable variant ranks across these checks are more reassuring than one optimized correlation. If the conclusion changes, report the dependence instead of hiding it.

Separate model validation from candidate validation

To evaluate predictive performance, hold out variants or use an independent experimental library that was not used to choose analysis settings. Report rank correlation, sample size, uncertainty, and any selection of branch lengths or transformations.

To validate candidates, retest shortlisted variants with the assay relevant to the project. Depending on the objective, that can include binding kinetics, expression, thermal stability, aggregation, specificity, sequence liabilities, and cell-based function. A CoSiNE score is prioritization evidence, not a substitute for those measurements.

Common CoSiNE mistakes

CoSiNE antibody evolution settings

The evolution interface preserves CoSiNE's sampling modes for future use:

• unguided or Guided Gillespie sampling
• SARS-CoV-2 Beta RBD or SARS-CoV-1 RBD predictor guidance
• continuous branch time or a discrete mutation-step count
• all-position, CDR-specific, all-CDR, framework-specific, or all-framework masks
• optional mutation ceilings
• configurable trajectory count, guidance strength, and random seed
• a submitted heavy-chain sequence or a built-in binder index

When enabled, the workflow is designed to return the native evolution CSV, sampled sequences as FASTA, and the execution log. It is not available now, and changing settings cannot remove the checkpoint requirement.^[2][3]

Guided sampling also deserves extra caution once it becomes available. Stronger guidance increases pressure toward the selected predictor, which can exploit predictor uncertainty rather than produce a genuinely improved antibody. The CoSiNE paper reports this behavior at high guidance strengths in its experiments.^[1]

CoSiNE alternatives

Choose the method that matches the evidence you have and the decision you need to make:

These tools are complementary. A candidate can score well under CoSiNE and still need structural review, humanization, developability assessment, and experimental testing.

CoSiNE analysis checklist

Before submission:

• Select Variant effect prediction.
• Confirm heavy, light, and fitness column mappings.
• Verify consistent chain lengths and canonical amino-acid sequences.
• Provide explicit parental consensus sequences when site-by-site consensus is ambiguous.
• Choose heavy, light, and/or combined axes to match the library design.
• Decide whether paired context matches the biological question.
• Add exact parental coding DNA for every corrected axis.
• Predefine branch lengths, correlation method, and any fitness transform.

After the run:

• Check n_samples and metric direction before reading correlations.
• Compare variant ranks only within a consistent scoring setup.
• Review sensitivity to reasonable branch lengths and contexts.
• Retain the submitted table, log, and provenance JSON.
• Validate performance on held-out data.
• Test shortlisted variants experimentally.

More antibody tools on ProteinIQ

• Run CoSiNE online
• Design antibody CDRs with DiffAb
• Humanize antibodies with BioPhi
• Score and embed antibody sequences with AbLang-2
• Learn about antibody variable regions
• Compare Fab and Fc regions

Frequently asked questions

Can I run CoSiNE online without installing Python or CUDA?

Yes. The CoSiNE webserver runs VEP on managed compute and returns the result tables and audit files in the browser.^[2]

What columns does a CoSiNE DMS CSV need?

It needs heavy-chain amino-acid sequences, light-chain amino-acid sequences, and numeric experimental fitness. The default names are heavy, light, and fitness, but you can map other headers. Optional mutation-label columns and explicit consensus sequences are also supported.

What CoSiNE branch length should I use?

Start with the online default of 0.2. For a planned sensitivity analysis, compare a small range such as 0.1,0.2,0.4 and report whether rankings change. Branch length is part of the transition definition, so there is no universal best value for every assay.^[1]

What is the CoSiNE selection score?

It is the CoSiNE transition log-likelihood minus a Thrifty neutral somatic-hypermutation log-likelihood. The score attempts to separate learned selection-associated signal from nucleotide-context mutation bias. It is not a measured binding affinity.^[1][4]

Why does SHM correction require DNA?

Somatic hypermutation probabilities depend on the nucleotide sequence surrounding a site. Two coding sequences can translate to the same antibody protein but present different nucleotide contexts, so amino-acid sequences alone are insufficient for Thrifty correction.^[4]

Should I use heavy, light, or combined scoring?

Use heavy or light to isolate mutations on one chain while holding the partner at wild type. Use combined when both submitted chains are mutated and the paired variant is the biological unit. You can select more than one axis in the same job.

Is a high CoSiNE score proof of better antigen binding?

No. CoSiNE models antibody sequence evolution, and its training data do not identify the selecting antigen for each lineage. A high likelihood or corrected selection score can prioritize a variant, but target-specific binding, expression, stability, and developability require separate validation.^[1]

Can CoSiNE evolve antibody sequences online now?

No. The controls are present, but the evolution task requires a RefineGNN binding-predictor checkpoint that the CoSiNE authors have not published. ProteinIQ does not substitute an unverified model because that would change the scientific method.^[2][3]