<commit_before># Generating Samples from your Hakaru Program #

The Hakaru language is built on Monte Carlo methods, which aim to generate individual samples and estimate expectation functions from a given distribution. The first task,
drawing samples from a distribution, is often difficult and this can be exasperated as the dimensionality of the sample space increases. Importance sampling is a Monte
Carlo method that is used to generate samples by estimating an expectation function for the target distribution instead. The estimated expectation function is then used to 
generate samples. To account for the knowledge that the samples were not generated from the target distribution, a weight is assigned so that each sample's contribution to
the estimator is adjusted according to its relevance. However, this method only works well if the distribution proposed by the expectation function is similar to the target
distribution. For more complex distributions, a different approach, such as the Metropolis Hastings method should be used[^1].

The `hakaru` command is used to indefinitely generate samples from a Hakaru program using importance sampling. Each sample is assigned a weight, and a sample's weight is 
initialized to `1.0`. Weights are changed by Hakaru primitives and processes such as [`weight`](../lang/rand.md).

## Usage ##

The `hakaru` command can take up to two Hakaru programs as arguments. If only one program is provided, the `hakaru` command generates samples based on the model described in
the Hakaru program. In this case, the `hakaru` command can be invoked in the command-line by calling:

````bash
hakaru hakaru_program.hk
````

If a second program is given to the `hakaru` command, it will treat the two programs as the start of a Markov Chain. This is used when you have created a transition kernel 
using the [Metropolis Hastings](../transforms/mh.md) transformation. To invoke the `hakaru` command with a transition kernel, you would call:

````bash
hakaru --transition-kernel transition.hk init.hk
````

The first program, `transition.hk`,  is treated as the transition kernel and the second program, `init.hk`, is treated as the initial state of the Markov Chain. When the 
`hakaru` command is run, a sample is drawn from `init.hk`. This sample is then passed to `transition.hk` to generate the second sample. After this point, samples generated
from `transition.hk` are passed back into itself to generate further samples.

### The Dash (`-`) Operator ###

You might encounter some scenarios where you wish to run a Hakaru command or transformation on a program and then send the resulting output to another command or transform. 
In these cases, you can take advantage of the dash (`-`) command-line notation.

The dash notation is a shortcut used to pass standard inputs and outputs to another command in the same line of script. For example, if you wanted to run the `disintegrate`
Hakaru command followed by the `simplify` command, you would enter:<commit_msg>Hakaru is not based on Monte Carlo methods, only better suited to expressing them<commit_after># Generating Samples from your Hakaru Program #

The Hakaru language is designed so that it is easy to express probabilistic models programmatically. In particular, Hakaru makes makes it easy to use Monte Carlo methods, 
which aim to generate individual samples and estimate expectation functions from a given distribution. The first task, drawing samples from a distribution, is often 
difficult and this can be exasperated as the dimensionality of the sample space increases. Importance sampling is a Monte Carlo method that is used to generate samples by 
estimating an expectation function for the target distribution instead. The estimated expectation function is then used to generate samples. To account for the knowledge 
that the samples were not generated from the target distribution, a weight is assigned so that each sample's contribution to the estimator is adjusted according to its 
relevance. However, this method only works well if the distribution proposed by the expectation function is similar to the target distribution. For more complex 
distributions, a different approach, such as the Metropolis Hastings method should be used[^1].

The `hakaru` command is used to indefinitely generate samples from a Hakaru program using importance sampling. Each sample is assigned a weight, and a sample's weight is 
initialized to `1.0`. Weights are changed by Hakaru primitives and processes such as [`weight`](../lang/rand.md).

## Usage ##

The `hakaru` command can take up to two Hakaru programs as arguments. If only one program is provided, the `hakaru` command generates samples based on the model described in
the Hakaru program. In this case, the `hakaru` command can be invoked in the command-line by calling:

````bash
hakaru hakaru_program.hk
````

If a second program is given to the `hakaru` command, it will treat the two programs as the start of a Markov Chain. This is used when you have created a transition kernel 
using the [Metropolis Hastings](../transforms/mh.md) transformation. To invoke the `hakaru` command with a transition kernel, you would call:

````bash
hakaru --transition-kernel transition.hk init.hk
````

The first program, `transition.hk`,  is treated as the transition kernel and the second program, `init.hk`, is treated as the initial state of the Markov Chain. When the 
`hakaru` command is run, a sample is drawn from `init.hk`. This sample is then passed to `transition.hk` to generate the second sample. After this point, samples generated
from `transition.hk` are passed back into itself to generate further samples.

### The Dash (`-`) Operator ###

You might encounter some scenarios where you wish to run a Hakaru command or transformation on a program and then send the resulting output to another command or transform. 
In these cases, you can take advantage of the dash (`-`) command-line notation.

The dash notation is a shortcut used to pass standard inputs and outputs to another command in the same line of script. For example, if you wanted to run the `disintegrate`
Hakaru command followed by the `simplify` command, you would enter:
{'fraction_non_alphanumeric': 0.0504269373288223, 'fraction_numerical': 0.0009666505558240696, 'mean_word_length': 4.716390423572744, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '625488', 'n_tokens_mistral': 1513, 'n_tokens_neox': 1431, 'n_words': 934}