0
# Combinatorics
1

2
Functions for calculating combinations and permutations of datasets.
3

4
## Core Imports
5

6
```typescript
7
import { 
8
  combinations, 
9
  combinationsReplacement, 
10
  permutationsHeap 
11
} from "simple-statistics";
12
```
13

14
## Capabilities
15

16
### Combinations
17

18
#### combinations
19

20
```typescript { .api }
21
/**
22
 * Generates all combinations of k elements from an array
23
 * @param x - Array of elements to choose from
24
 * @param k - Number of elements to choose
25
 * @returns Array of all possible combinations
26
 */
27
function combinations<T>(x: T[], k: number): T[][];
28
```
29

30
**Usage Example:**
31

32
```typescript
33
import { combinations } from "simple-statistics";
34

35
const letters = ['A', 'B', 'C', 'D'];
36
const pairs = combinations(letters, 2);
37
// [['A', 'B'], ['A', 'C'], ['A', 'D'], ['B', 'C'], ['B', 'D'], ['C', 'D']]
38

39
const numbers = [1, 2, 3];
40
const singles = combinations(numbers, 1);
41
// [[1], [2], [3]]
42
```
43

44
#### combinationsReplacement
45

46
```typescript { .api }
47
/**
48
 * Generates all combinations with replacement of k elements from an array
49
 * @param x - Array of elements to choose from
50
 * @param k - Number of elements to choose
51
 * @returns Array of all possible combinations with replacement
52
 */
53
function combinationsReplacement<T>(x: T[], k: number): T[][];
54
```
55

56
**Usage Example:**
57

58
```typescript
59
import { combinationsReplacement } from "simple-statistics";
60

61
const dice = [1, 2, 3];
62
const rollTwice = combinationsReplacement(dice, 2);
63
// [[1, 1], [1, 2], [1, 3], [2, 2], [2, 3], [3, 3]]
64
```
65

66
### Permutations
67

68
#### permutationsHeap
69

70
```typescript { .api }
71
/**
72
 * Generates all permutations of an array using Heap's algorithm
73
 * @param x - Array of elements to permute
74
 * @returns Array of all possible permutations
75
 */
76
function permutationsHeap<T>(x: T[]): T[][];
77
```
78

79
**Usage Example:**
80

81
```typescript
82
import { permutationsHeap } from "simple-statistics";
83

84
const colors = ['red', 'green', 'blue'];
85
const arrangements = permutationsHeap(colors);
86
// [
87
//   ['red', 'green', 'blue'],
88
//   ['green', 'red', 'blue'],
89
//   ['blue', 'red', 'green'],
90
//   ['red', 'blue', 'green'],
91
//   ['green', 'blue', 'red'],
92
//   ['blue', 'green', 'red']
93
// ]
94

95
// Small example
96
const abc = ['A', 'B'];
97
const perms = permutationsHeap(abc);
98
// [['A', 'B'], ['B', 'A']]
99
```
100

101
## Mathematical Background
102

103
**Combinations** calculate the number of ways to choose k items from n items where order doesn't matter: C(n,k) = n! / (k!(n-k)!)
104

105
**Combinations with Replacement** allow the same item to be chosen multiple times: C(n+k-1,k)
106

107
**Permutations** calculate arrangements where order matters: P(n,k) = n! / (n-k)!
108

109
The `permutationsHeap` function implements Heap's algorithm, which generates all permutations with minimal changes between consecutive permutations, making it efficient for large datasets.