# Quick Start: MyoScore

## Overview

MyoScore (Genetic Muscle Health Score) quantifies skeletal muscle health from bulk RNA-seq raw count data across five genetically-driven dimensions:

Dimension | Weight | GWAS Basis | Meaning
--- | --- | --- | ---
Strength | 25.2% | Grip strength, walking pace | Muscle function
Mass | 17.7% | Fat-free mass (whole body, limbs) | Muscle quantity
LeanMuscle | 24.3% | Thigh fat infiltration MRI | Low fat = healthy
Youth | 24.2% | Telomere length | Biological age
Resilience | 8.7% | Myopathy diagnosis, CK levels | Disease resistance

Higher score = healthier muscle (0-100 scale).

## Installation

    # From GitHub
    devtools::install_github("hua-xie/MyoScore")

## Basic Usage

### Calculate MyoScore from a count matrix

    library(MyoScore)

    # From a CSV file (genes as rows, samples as columns)
    scores <- myoscore_score("path/to/raw_counts.csv")

    # From a matrix in R
    scores <- myoscore_score(count_matrix)

    # For tab-separated files
    scores <- myoscore_score("counts.tsv", sep = "\t")

The output is a data.frame with 6 columns per sample:

- `Strength_score`, `Mass_score`, `LeanMuscle_score`, `Youth_score`, `Resilience_score` (individual dimensions, 0-100)
- `MyoScore` (weighted composite, 0-100)

### Explore the gene weights

    library(MyoScore)
    #> MyoScore v1.0.1
    #>   A genetically-informed transcriptomic scoring system
    #>   for quantifying human skeletal muscle health.
    #>   5 dimensions: Strength, Mass, LeanMuscle, Youth, Resilience
    #>   Use myoscore_score() to calculate scores from raw counts.
    data(myoscore_genes)
    head(myoscore_genes)
    #>         ID    weight direction_v3 dimension
    #> 1     NFS1 10.385270            1  Strength
    #> 6     NEK4  7.877092            1  Strength
    #> 10    RFT1  7.672116            1  Strength
    #> 12 PLEKHM1  7.509400           -1  Strength
    #> 13    MAPT  7.430800            1  Strength
    #> 14    RBM6  7.390450            1  Strength
    table(myoscore_genes$dimension)
    #>
    #> LeanMuscle       Mass Resilience   Strength      Youth
    #>        147        219        157         31         37

### Preprocessing only

    # Just normalize without scoring
    log2cpm <- myoscore_preprocess(count_matrix)

### Single dimension

    log2cpm <- myoscore_preprocess(count_matrix)
    youth <- myoscore_score_dimension(log2cpm, dimension = "Youth")

## Visualization

### Radar chart

    # Requires: install.packages("fmsb")

    # Overall mean radar
    myoscore_plot_radar(scores)

    # Grouped by condition
    myoscore_plot_radar(scores, groups = metadata$condition)

### Grouped boxplot

    # Requires: install.packages("ggplot2")

    # Compare MyoScore across groups
    myoscore_plot_boxplot(scores, groups = metadata$condition)

    # All dimensions
    myoscore_plot_boxplot(scores, groups = metadata$condition, which = "all")

## Input Requirements

- Format: Raw count matrix (not TPM, FPKM, or normalized values)
- Genes: Gene Symbols as row names (not Ensembl IDs)
- Samples: At least 2 samples (recommend >= 20 for reliable normalization)
- Coverage: Typical bulk RNA-seq datasets contain ~417 of the 1,116 scoring genes (~50% per dimension), which is sufficient for reliable scoring.

## Color Palette

    myoscore_colors("dimensions")
    #>   Strength       Mass LeanMuscle      Youth Resilience
    #>  "#50327b"  "#46508b"  "#f4e030"  "#72c95e"  "#31848f"
    myoscore_colors("spectrum")
    #> unhealthy      mild   neutral  positive   healthy
    #> "#50327b" "#46508b" "#31848f" "#72c95e" "#f4e030"

## Citation

> Revealing myopathy spectrum: integrating transcriptional and clinical features of human skeletal muscles with varying health conditions. Communications Biology, 2024.