liberata_metrics.metrics.system_health_metrics module

System health metrics computation module.

This module provides classes and functions for computing and analyzing system health metrics, such as growth rates and shrinkage rates, and various properties related to the health of a portfiolio.

liberata_metrics.metrics.system_health_metrics.get_academic_capital_growth_rate(capital_history: List[spmatrix], contributor_index_map_subset: Dict[str, int]) → float

Compute the average Academic Capital Growth Rate of a portfolio. This is the rate at which the academic capital of a portfolio has grown over a historical sequence of capital matrices.

Parameters:

• capital_history (List[scipy.sparse.spmatrix]) – A chronological list of at least two sparse capital matrices representing portfolio states over time. Consecutive entries are should be a year apart

• contributor_index_map_subset (Dict[str, int]) – Mapping from contributor identifier to the corresponding column index in the capital matrices.

Returns:

The compound growth rate per time period. Returns 0.0 if the starting capital is zero

Return type:

float

Raises:

• TypeError – If any element in capital_history is not a scipy sparse matrix.

• ValueError – If capital_history contains fewer than two entries.

Notes

liberata_metrics.metrics.system_health_metrics.get_field_capital_shares(capital: spmatrix, region_contributor_index_map: Dict[str, int], field_contributor_index_maps: Dict[str, Dict[str, int]]) → Dict[str, float]

Compute the proportionate contribution of each academic field to the total academic capital of a region.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix.

• region_contributor_index_map (Dict[str, int]) – Contributor index map for the full region.

• field_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from field identifier to contributor index map for that field within the region.

Returns:

Mapping from field identifier to its proportionate share of regional academic capital.

Return type:

Dict[str, float]

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If total regional academic capital is zero.

liberata_metrics.metrics.system_health_metrics.get_funding_efficiency(capital: spmatrix, total_spending: float) → float

Compute global research funding efficiency, which is the academic capital produced per unit of research spending.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• total_spending (float) – Total global research spending ($Θ).

Returns:

Returns the funding efficiency.

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If total_spending is not positive.

liberata_metrics.metrics.system_health_metrics.get_gdp_efficiency(capital: spmatrix, total_spending: float, gdp: float) → float

Compute global research GDP efficiency, which is funding efficiency scaled by GDP.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• total_spending (float) – Total global research spending ($Θ).

• gdp (float) – Global GDP (GDP_Θ).

Returns:

Returns the GDP efficiency.

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If total_spending or gdp is not positive.

liberata_metrics.metrics.system_health_metrics.get_gini_per_capita(capital: spmatrix, region_contributor_index_maps: Dict[str, Dict[str, int]], regional_populations: Dict[str, float]) → float

Compute the Gini coefficient of per capita academic capital inequality across regions.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• region_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from region identifier to contributor index map for that region.

• regional_populations (Dict[str, float]) – Mapping from region identifier to population.

Returns:

Gini coefficient in [0, 1].

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If a region present in region_contributor_index_maps is missing from regional_populations.

liberata_metrics.metrics.system_health_metrics.get_gini_per_contributor(capital: spmatrix, region_contributor_index_maps: Dict[str, Dict[str, int]], regional_contributor_counts: Dict[str, int]) → float

Compute the Gini coefficient of per contributor academic capital inequality across regions.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• region_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from region identifier to contributor index map for that region.

• regional_contributor_counts (Dict[str, int]) – Mapping from region identifier to number of contributors in that region.

Returns:

Gini coefficient in [0, 1].

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If a region present in region_contributor_index_maps is missing from regional_contributor_counts.

liberata_metrics.metrics.system_health_metrics.get_gini_per_gdp(capital: spmatrix, region_contributor_index_maps: Dict[str, Dict[str, int]], regional_gdps: Dict[str, float]) → float

Compute the Gini coefficient of per GDP academic capital inequality across regions.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• region_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from region identifier to contributor index map for that region.

• regional_gdps (Dict[str, float]) – Mapping from region identifier to GDP.

Returns:

Gini coefficient in [0, 1].

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If a region present in region_contributor_index_maps is missing from regional_gdps.

liberata_metrics.metrics.system_health_metrics.get_ppp_efficiency(capital: spmatrix, total_spending: float, ppp: float) → float

Compute global research PPP efficiency, which is funding efficiency scaled by PPP.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• total_spending (float) – Total global research spending ($Θ).

• ppp (float) – Global purchasing power parity (PPP_Θ).

Returns:

Returns the PPP efficiency.

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If total_spending or ppp is not positive.

liberata_metrics.metrics.system_health_metrics.get_regional_academic_capital(capital: spmatrix, region_contributor_index_maps: Dict[str, Dict[str, int]]) → Dict[str, float]

Compute total academic capital per geographic region.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• region_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from region identifier to contributor index map for that region.

Returns:

Mapping from region identifier to total academic capital.

Return type:

Dict[str, float]

Raises:

TypeError – If capital is not a scipy sparse matrix.

liberata_metrics.metrics.system_health_metrics.get_regional_hhi(capital: spmatrix, region_contributor_index_map: Dict[str, int], field_contributor_index_maps: Dict[str, Dict[str, int]]) → float

Compute the HHI of academic capital concentration across fields for a region.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix.

• region_contributor_index_map (Dict[str, int]) – Contributor index map for the full region.

• field_contributor_index_maps (Dict[str, Dict[str, int]]) – Mapping from field identifier to contributor index map for that field within the region.

Returns:

HHI value.

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If total regional academic capital is zero.

liberata_metrics.metrics.system_health_metrics.get_replicator_fmp_volatility(capital_history: List[spmatrix], contributor_index_map: Dict[str, int]) → float

Compute the volatility of the global fair market price for replicators over a time period of n steps.

Parameters:

• capital_history (List[scipy.sparse.spmatrix]) – A chronological list of at least two sparse capital matrices.

• contributor_index_map (Dict[str, int]) – Full contributor map (all contributors, not a subset).

Returns:

Volatility of replicator FMP.

Return type:

float

Raises:

• TypeError – If any element in capital_history is not a scipy sparse matrix.

• ValueError – If capital_history contains fewer than two entries.

liberata_metrics.metrics.system_health_metrics.get_replicator_shrinkage_rate(capital_history: List[spmatrix], contributor_index_map: Dict[str, int]) → float

Compute the shrinkage rate of the global fair market price for replicators. This is just the negative rate of change in the total FMP for replicators.

Parameters:

• capital_history (List[scipy.sparse.spmatrix]) – A chronological list of at least two sparse capital matrices.

• contributor_index_map (Dict[str, int]) – Full contributor map (all contributors, not a subset).

Returns:

Per-period shrinkage rate for replicator FMP.

Return type:

float

Raises:

• TypeError – If any element in capital_history is not a scipy sparse matrix.

• ValueError – If capital_history contains fewer than two entries.

liberata_metrics.metrics.system_health_metrics.get_reviewer_fmp_volatility(capital_history: List[spmatrix], contributor_index_map: Dict[str, int]) → float

Compute the volatility of the global fair market price for reviewers over a time period of n steps.

Parameters:

• capital_history (List[scipy.sparse.spmatrix]) – A chronological list of at least two sparse capital matrices.

• contributor_index_map (Dict[str, int]) – Full contributor map (all contributors, not a subset).

Returns:

Volatility of reviewer FMP.

Return type:

float

Raises:

• TypeError – If any element in capital_history is not a scipy sparse matrix.

• ValueError – If capital_history contains fewer than two entries.

liberata_metrics.metrics.system_health_metrics.get_reviewer_shrinkage_rate(capital_history: List[spmatrix], contributor_index_map: Dict[str, int]) → float

Compute the shrinkage rate of the global fair market price for reviewers. This is just the negative rate of change in the total FMP for reviewers.

Parameters:

• capital_history (List[scipy.sparse.spmatrix]) – A chronological list of at least two sparse capital matrices.

• contributor_index_map (Dict[str, int]) – Full contributor map (all contributors, not a subset).

Returns:

Per-period shrinkage rate for reviewer FMP

Return type:

float

Raises:

• TypeError – If any element in capital_history is not a scipy sparse matrix.

• ValueError – If capital_history contains fewer than two entries.

liberata_metrics.metrics.system_health_metrics.get_time_efficiency(capital: spmatrix, delta_t: float) → float

Compute global research time efficiency, which is the academic capital produced per unit time.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix covering all manuscripts globally.

• delta_t (float) – Time elapsed (Δt_Θ).

Returns:

Returns the time efficiency.

Return type:

float

Raises:

• TypeError – If capital is not a scipy sparse matrix.

• ValueError – If delta_t is not positive.

liberata_metrics.metrics.system_health_metrics.total_fair_market_price(capital: spmatrix, contributor_index_map: Dict[str, int], is_reviewer: bool) → float

Compute the total fair market price for either reviewers or replicators across all manuscripts. This is the total capital across all reveiwers or replicators.

Parameters:

• capital (scipy.sparse.spmatrix) – Sparse capital matrix of shape (M, M + C), where M is the number of manuscripts and C = num_contributors * 3.

• contributor_index_map (Dict[str, int]) – Mapping from contributor identifier to base column index.

• is_reviewer (bool) – If True, sums the reviewer block (second role block). If False, sums the replicator block (third role block).

Returns:

Total fair market price across all manuscripts for the specified role.

Return type:

float