pySCA

What is pySCA?

pySCA is a Python-based implementation of Statistical Coupling Analysis (SCA), a method originally developed by the Ranganathan Lab and previously available in MATLAB. Given an alignment of homologous sequences, SCA identifies groups of coevolving amino acid positions, called protein sectors. These sectors represent physically connected networks of residues that contribute to specific protein functions like folding stability, ligand binding, or allosteric signaling.

SCA is based on the idea that functionally important residues do not evolve independently. When a mutation occurs at one position, compensatory changes at interacting positions preserve the protein�s function. SCA detects these correlated evolutionary patterns in a multiple sequence alignment and extracts them as spatially contiguous residue networks on the protein structure.

How to use pySCA online

Paste or upload a multiple sequence alignment in FASTA, Clustal, or Stockholm format into ProteinIQ to identify residue sectors without installing pySCA, downloading sequence databases, or configuring any dependencies. If your homologs are still unaligned, align them first with Clustal Omega or MAFFT. The default operation runs the full SCA pipeline and returns per-position conservation scores, sector assignments, eigenvalues, and the native pySCA results database for downstream analysis.

Pricing

Runs start at 10 credits. For an alignment-only submission, the existing calculator counts submitted residues without gaps; filtering and trial settings do not change that quote. The exact quote is shown before submission.

Sequences	Residues per sequence	Credits
4	25	12
32	25	21
100	200	148

These examples assume one ungapped FASTA alignment and no additional inputs. Additional submitted content can change the quote.

Inputs

Input	Description
MSA	MSA in FASTA, Clustal, or Stockholm format. Must contain at least 4 protein sequences. Supply a pre-aligned MSA. pySCA removes records containing nonstandard amino acids before processing the remaining alignment. For protein families like PDZ, SH3, or globins, aim for 50-500 diverse sequences. More sequences produce more reliable sector detection.

Settings

Filtering

The pre-processing step removes columns (positions) and rows (sequences) that would add noise to the analysis.

Setting	Description
Max position gap fraction	Maximum fraction of gaps allowed per alignment column before it is removed (0-1, default 0.3). Positions like loop regions often have high gap counts and get filtered.
Max sequence gap fraction	Maximum fraction of gaps allowed per sequence before it is removed (0-1, default 0.2). Truncated sequences or partial domains get filtered out.
Min sequence identity	Minimum identity to the reference sequence (0-1, default 0.15). Distant outliers that may not share the same functional constraints get removed.
Max sequence identity	Maximum identity to the reference sequence (0-1, default 0.85). Near-duplicate sequences that would overweight a clade get removed.
Reference sequence index	Zero-based index of the sequence to use as a reference. Leave empty to let pySCA choose automatically.

SCA Parameters

Setting	Description
Normalization type	Matrix normalization method. Frobenius (default) is standard for most protein families. Spectral can be useful for very large alignments.
Randomization trials	Number of randomized alignments for significance testing (1-100, default 10). More trials give a more stable significance threshold but increase runtime.
Pseudo-count lambda	Regularization parameter for sparse position frequencies (0-1, default 0.03). Prevents overfitting when certain amino acid combinations are underrepresented.
Significant eigenmodes	Override automatic selection of significant eigenmodes (0-10, default 0 = auto). Auto-selection uses randomization trials to determine significance; 10 is pySCA's default safety cap.
Sector significance cutoff	CDF threshold for including positions in a sector (0.5-1, default 0.95). Higher values produce smaller, more conservative sectors.

Native operations and additional inputs

Preprocessing and the full pipeline accept an optional PDB reference (.pdb or .ent), a reference FASTA (.fasta, .fa, .fas), a position-label file (.txt, one label per line), and a retained-sequence index file (.txt, using native 1-based indices). Files may be up to 50 MiB each. Native reference precedence and filtering apply.

SCA-only, sector-only, and visualization operations accept a native pySCA database (.db or .db.gz). Database uploads are checked for the supported native serialization constructors before pySCA opens them. The similarity plot requires a database containing sca.simMat; it returns an interactive HTML file. The pinned pySCA visualizer writes HTML even when a PNG filename is requested.

The existing minimum of four input sequences is a product limit. Native numerical routines can still reject small filtered alignments. Their errors are retained in the complete downloadable run log.

Parameter	Type	Default	Description
mode	enum	pipeline	Full analysis, preprocessing, SCA from a processed database, sector identification from an SCA database, or an interactive similarity plot.
reference_chain	string	A	PDB chain used for reference mapping.
reference_species	string	optional	Native header/species reference search.
truncate	boolean	false	Truncate to supplied reference positions.
precluster	enum	auto	Automatic above 50,000 sequences, enabled, or disabled.
cluster_id	number	0.85	MMseqs2 sequence identity threshold.
cluster_coverage	number	0.8	MMseqs2 coverage threshold.
cluster_cov_mode	enum	0	Native MMseqs2 coverage mode: 0, 1, or 2.
initial_trim_gap	number	optional	Initial position gap filter; empty uses native 0.8.
save_msa_num	boolean	false	Write the numeric alignment as compressed NPZ.
keep_sequences	string	optional	Whitespace-separated 1-based input indices to retain during preprocessing.
seqcorr_keep_indices	string	optional	Whitespace-separated 1-based similarity indices to retain.
do_seqcorr	boolean	false	Force sequence correlations. Disabled preserves native automatic selection rather than forcing them off.
max_seqcorr_m	integer	5000	Automatically compute sequence correlations at or below this sequence count.
max_seqcorr_seqs	integer	optional	Requested similarity sample size; empty preserves native automatic selection.
seqcorr_ref	integer	optional	1-based reference index for similarity subsampling, unlike the 0-based preprocessing reference.
seqcorr_mmseqs2	boolean	false	Use the native MMseqs2 similarity path.
seqcorr_max_cap	integer	50000	Native cap for automatic similarity sampling.
no_auto_seqcorr_subsample	boolean	false	Disable native automatic similarity subsampling.
store_crand	boolean	false	Retain randomized SCA matrices in the database.
do_sector_id	boolean	false	Also identify sectors in SCA-only mode; the full pipeline always identifies sectors.
float32	boolean	false	Store selected native arrays as float32.
kica	integer	optional	Independent component count, at least 2 and no greater than the selected eigenmode count; empty uses that count.
kmax_cap	integer	10	Automatic eigenmode cap, 1-10; the existing product cap is retained.
matlab	boolean	false	Write the native MATLAB workspace alongside other results.
plot_width	integer	800	Native plot width in pixels.
plot_height	integer	800	Native plot height in pixels.
plot_title	string	optional	Optional plot title; empty uses the native database-based title.
plot_colormap	string	Viridis256	Native Bokeh palette name. Unsupported names follow pySCA fallback behavior.
no_db	boolean	false	Skip writing the updated database. Enable MATLAB export to retain computed arrays; this option also removes the corresponding structured result preview.

Additional controls are shown for the relevant operation. The original filtering and SCA ranges above remain unchanged.

Outputs

Native files retain their original bytes. CSV downloads are convenience projections of native fields at full precision; the database contains the complete native arrays. Older saved jobs retain their original output formatting.

Output	Description
Processed alignment	Filtered MSA after removing low-quality positions and sequences, in FASTA format.
Sector assignments	Per-position data including relative entropy conservation score (sca.Di), eigenvector projections (VP1-VP3), and sector membership.
Eigenvalues	Complete SCA eigenvalue spectrum, with one row for every eigenmode retained by pySCA.
Raw pySCA database	Native db.gz results bundle from native pySCA. Includes the processed sequence block, SCA matrices, sector positions, ATS labels, and other downstream analysis fields.
Run summary	Native sequence and position counts, effective sequence count, complete eigenvalue spectrum, and sector counts where available.
Optional native files	Numeric alignment NPZ, MATLAB workspace, precluster representatives and weights, randomized matrices inside the database, diagnostic files, and interactive similarity HTML according to the selected options.
Complete logs and provenance	Native stage logs, exact command arguments, and pinned source identity. Failure logs are retained when a native command fails.

Understanding sector assignments

Each position in the alignment receives several metrics:

Column	Meaning
position	native ATS position label for the processed alignment. Without an external reference mapping, this is the processed alignment position label generated by pySCA.
sector	1-based sector number, comma-separated numbers for overlapping memberships, or 0 for no sector. Absent when sector identification has not run.
conservation	Native relative entropy (sca.Di) at each position. Higher values indicate more evolutionary constraint.
vp1, vp2, vp3	Values from the first three columns of the complete native sca.V eigenvector matrix. These columns are not restricted to the selected significant modes. Large absolute values indicate strong contribution to the corresponding mode.

Positions assigned to a sector typically have high conservation and large eigenvector projections compared to the rest of the protein. A globin alignment, for example, might place heme-contacting and helix-stabilizing residues into the same sector, revealing the physical network that maintains oxygen-binding function.

How pySCA works

SCA operates in several stages on a multiple sequence alignment.

1. Pre-processing. The alignment is filtered to remove positions with excessive gaps and sequences that are too divergent or too similar to the reference. This reduces noise from poorly aligned regions and sequence sampling bias. The remaining amino acid frequencies are regularized using pseudo-counts to handle sparse data.

2. Position-specific conservation. For each column in the filtered alignment, a relative entropy conservation score (sca.Di) measures how constrained that position is across the family, compared to a random distribution of amino acids.

3. Statistical coupling matrix. The DeltaDelta matrix is computed, capturing pairwise statistical dependencies between all position pairs. Each element measures how much the amino acid distribution at one position changes when the amino acid at another position is fixed.

4. Eigenmode decomposition. Singular value decomposition (SVD) extracts the dominant patterns of covariation from the coupling matrix. The largest eigenmodes represent the most significant collective evolutionary constraints.

5. Independent component analysis. ICA is applied to the significant eigenmodes to isolate statistically independent residue groups. Each independent component corresponds to a protein sector, which can be mapped back onto the structure as a physically connected network.

The number of sectors typically ranges from 1 to 4, depending on the protein family size and functional diversity.

When to use pySCA vs alternatives

SCA is not the only coevolution method. Choosing the right tool depends on the goal.

Approach	Best for	Tradeoffs
pySCA (SCA)	Identifying functional residue networks within a protein family. Sectors map to physical pathways on the structure.	Requires a well-curated MSA of closely related homologs. Less reliable for very small or very large families.
Direct coupling analysis (DCA)	Predicting residue-residue contacts for structure prediction. Strong pairwise couplings indicate spatial proximity.	Optimized for distance prediction, not functional decomposition. Produces contact maps without functional interpretation.
Phylogenetic methods	Tracing evolutionary history and ancestral sequence reconstruction.	Captures lineage-level patterns rather than within-family functional constraints.
Mutual information (MI)	Detecting pairwise correlations in an MSA. Simple and fast.	Suffers from phylogenetic noise and indirect correlations. SCA explicitly corrects for both.

A practical workflow might use DCA to validate a predicted structure, then SCA to identify which subset of contacting residues forms a functional sector. The sector positions can then guide mutagenesis experiments or inform restraints for molecular docking.