sfs.py
High-level description
The code defines a class SFS that represents a Site Frequency Spectrum (SFS), a fundamental concept in population genetics used to summarize genetic variation within a population. It provides methods to calculate various statistics from the SFS, such as Tajima’s D, Fay and Wu’s H, Zeng’s E, and Ferretti’s L, which are used to infer demographic history and selection pressures.
Code Structure
The SFS class is the main component of the code. It holds the SFS data (counts) and provides methods to calculate different statistics. The statistics calculation methods (fay_and_wus_H, zengs_E, tajimas_D, ferrettis_L) rely on the SFS data and use helper methods (_calculate_fay_and_wus_H, _calculate_zengs_E, _calculate_tajimas_D, _calculate_ferrettis_L) to perform the actual calculations. The bin method is used to group the SFS data into bins for easier visualization and analysis.
Symbols
Symbol Name
SFS
Description
This class represents a Site Frequency Spectrum (SFS) and provides methods for calculating various statistics from it.
Inputs
| Name | Type | Description |
|---|---|---|
| counts | numpy.ndarray | An array representing the counts of mutations at different frequencies. |
| T | cassiopeia.data.CassiopeiaTree | Optional. A CassiopeiaTree object representing the phylogenetic tree. |
Outputs
An SFS object.
Internal Logic
The constructor initializes the counts and T attributes. It also initializes several attributes to None, which will be calculated lazily when their corresponding methods are called.
Symbol Name
SFS.from_tree
Description
This class method constructs an SFS object from a given phylogenetic tree.
Inputs
| Name | Type | Description |
|---|---|---|
| T | cassiopeia.data.CassiopeiaTree | A CassiopeiaTree object representing the phylogenetic tree. |
Outputs
An SFS object.
Internal Logic
The method iterates through the clades of the tree and counts the number of mutations at each frequency (number of leaves in each clade). It then creates an SFS object with the calculated counts and the input tree.
Symbol Name
SFS.bin
Description
This method bins the SFS data into specified bins for easier visualization and analysis.
Inputs
| Name | Type | Description |
|---|---|---|
| bins | str or array-like | Specifies the binning strategy. Can be “linear”, “log”, “logit”, or an array-like object defining the bin edges. |
| n_bins | int | Optional. Number of bins to use if bins is “linear” or “log”. |
| min_edge | float | Optional. Minimum edge for binning if bins is “linear” or “log”. |
| max_edge | float | Optional. Maximum edge for binning if bins is “linear” or “log”. |
Outputs
None. The method modifies the SFS object in place, adding attributes related to the binning.
Internal Logic
The method first determines the bin edges and centers based on the bins argument and optional parameters. It then bins the SFS data by counting the number of mutations falling into each bin. The binned data is normalized by the bin size. If a tree is provided, the method also calculates a cut version of the normalized binned data, setting bins beyond the tree size to np.nan.
Symbol Name
SFS.fay_and_wus_H
Description
This method calculates and returns Fay and Wu’s H statistic from the SFS.
Inputs
None.
Outputs
| Name | Type | Description |
|---|---|---|
| fay_and_wus_H | float | Fay and Wu’s H statistic. |
Internal Logic
The method first checks if the statistic has been previously calculated and cached. If not, it calls the _calculate_fay_and_wus_H method to calculate it.
Symbol Name
SFS._calculate_fay_and_wus_H
Description
This private method calculates Fay and Wu’s H statistic from the SFS data.
Inputs
None.
Outputs
None. The method modifies the SFS object in place, setting the _fay_and_wus_H attribute.
Internal Logic
The method calculates the statistic based on the formula: theta_pi - theta_H, where theta_pi and theta_H are calculated from the SFS data.
Symbol Name
SFS.zengs_E
Description
This method calculates and returns Zeng’s E statistic from the SFS.
Inputs
None.
Outputs
| Name | Type | Description |
|---|---|---|
| zengs_E | float | Zeng’s E statistic. |
Internal Logic
The method first checks if the statistic has been previously calculated and cached. If not, it calls the _calculate_zengs_E method to calculate it.
Symbol Name
SFS._calculate_zengs_E
Description
This private method calculates Zeng’s E statistic from the SFS data.
Inputs
None.
Outputs
None. The method modifies the SFS object in place, setting the _zengs_E attribute.
Internal Logic
The method calculates the statistic based on the formula: theta_L - theta_W, where theta_L and theta_W are calculated from the SFS data.
Symbol Name
SFS.tajimas_D
Description
This method calculates and returns Tajima’s D statistic from the SFS.
Inputs
None.
Outputs
| Name | Type | Description |
|---|---|---|
| tajimas_D | float | Tajima’s D statistic. |
Internal Logic
The method first checks if the statistic has been previously calculated and cached. If not, it calls the _calculate_tajimas_D method to calculate it.
Symbol Name
SFS._calculate_tajimas_D
Description
This private method calculates Tajima’s D statistic from the SFS data.
Inputs
None.
Outputs
None. The method modifies the SFS object in place, setting the _tajimas_D attribute.
Internal Logic
The method calculates the statistic based on the formula: theta_pi - theta_W, where theta_pi and theta_W are calculated from the SFS data.
Symbol Name
SFS.ferrettis_L
Description
This method calculates and returns Ferretti’s L statistic from the SFS.
Inputs
None.
Outputs
| Name | Type | Description |
|---|---|---|
| ferrettis_L | float | Ferretti’s L statistic. |
Internal Logic
The method first checks if the statistic has been previously calculated and cached. If not, it calls the _calculate_ferrettis_L method to calculate it.
Symbol Name
SFS._calculate_ferrettis_L
Description
This private method calculates Ferretti’s L statistic from the SFS data.
Inputs
None.
Outputs
None. The method modifies the SFS object in place, setting the _ferrettis_L attribute.
Internal Logic
The method calculates the statistic based on the formula: theta_W - theta_H, where theta_W and theta_H are calculated from the SFS data.