Author: Wouter Saelens
Date: 2026-03-31

# Creating a TI method: Wrapping trajectories

#### Wouter Saelens

#### Robrecht Cannoodt

#### 2026-03-31

## Common trajectory model

dynwrap always represents trajectories in the same way, as illustrated here with a tree trajectory

- Milestone network, contains information of connections between milestones

    ## # A tibble: 5 × 4
    ##   from        to          length directed
    ##   <chr>       <chr>        <dbl> <lgl>
    ## 1 Milestone_A Milestone_B    1   FALSE
    ## 2 Milestone_B Milestone_C    2   FALSE
    ## 3 Milestone_B Milestone_D    1   FALSE
    ## 4 Milestone_C Milestone_E    1   FALSE
    ## 5 Milestone_C Milestone_F    1.5 FALSE

- Milestone percentages, contains how close a cell is to a milestone. For each cell, the percentages sum to one.

    ## # A tibble: 10 × 3
    ##    cell_id milestone_id percentage
    ##    <chr>   <chr>             <dbl>
    ##  1 Cell_a  Milestone_B      0.0529
    ##  2 Cell_a  Milestone_C      0.947
    ##  3 Cell_b  Milestone_C      0.360
    ##  4 Cell_b  Milestone_F      0.640
    ##  5 Cell_c  Milestone_C      0.686
    ##  6 Cell_c  Milestone_F      0.314
    ##  7 Cell_d  Milestone_B      0.335
    ##  8 Cell_d  Milestone_C      0.665
    ##  9 Cell_e  Milestone_C      0.0345
    ## 10 Cell_e  Milestone_E      0.966

- Progressions, an alternative to milestone percentages, also contains the positions of each cell but now based on its progression through an edge

    ## # A tibble: 10 × 4
    ##    cell_id from        to          percentage
    ##    <chr>   <chr>       <chr>            <dbl>
    ##  1 Cell_a  Milestone_B Milestone_C      0.947
    ##  2 Cell_b  Milestone_C Milestone_F      0.640
    ##  3 Cell_c  Milestone_C Milestone_F      0.314
    ##  4 Cell_d  Milestone_B Milestone_C      0.665
    ##  5 Cell_e  Milestone_C Milestone_E      0.966
    ##  6 Cell_f  Milestone_C Milestone_F      0.137
    ##  7 Cell_g  Milestone_A Milestone_B      0.598
    ##  8 Cell_h  Milestone_C Milestone_E      0.705
    ##  9 Cell_i  Milestone_B Milestone_D      0.208
    ## 10 Cell_j  Milestone_B Milestone_C      0.938

- Divergence regions, contain the information on >=3 milestones connected to eachother. This is optional.

    ## # A tibble: 3 × 3
    ##   divergence_id milestone_id is_start
    ##   <chr>         <chr>        <lgl>
    ## 1 Divergence_1  Milestone_B  TRUE
    ## 2 Divergence_1  Milestone_C  FALSE
    ## 3 Divergence_1  Milestone_D  FALSE

## Direct wrapping

These three objects (with either milestone percentages or progressions) are enough to form a trajectory using `add_trajectory`.

    trajectory <- wrap_data(cell_ids = cell_ids) %>%
      add_trajectory(
        milestone_network = milestone_network,
        milestone_percentages = milestone_percentages,
        divergence_regions = divergence_regions
      )

## Indirect wrapping

Often, you don’t want to directly output the milestone network and percentages, but want to output an alternative representation that is converted by dynwrap to the common representation:

Check out the reference documentation for an overview and examples of the different wrappers