Merge pull request #49 from AUAS-Pulsar/dedisp_documentation

Dedispersion documentation

Author: maxvhas

README.md

@@ -48,13 +48,18 @@ Creating a free and open source framework that contains the generic algorithms a
     2. [Filter samples](docs/clipping.md#62-filter-samples)
     3. [Filter channels](docs/clipping.md#63-filter-channels)
     4. [Filter individual channels](docs/clipping.md#64-filter-individual-channels)
-7. [Pipeline](docs/pipeline.md)
+7. [Dedispersion](docs/dedispersion.md)
+    1. [Dedisperse](docs/dedispersion.md#72-Dedisperse)
+    2. [Find dispersion measure](docs/dedispersion.md#73-find_dm)
+    3. [Find line](docs/dedispersion.md#74-find_line)
+    4. [Find estimation intensity](docs/dedispersion.md#75-find_estimation_intensity)
+8. [Pipeline](docs/pipeline.md)
     1. [Introduction](docs/pipeline.md#71-introduction)
     2. [Read rows](docs/pipeline.md#72-read-rows)
     3. [Read n rows](docs/pipeline.md#73-read-n-rows)
     3. [Read static](docs/pipeline.md#74-read-static)
     4. [Measure methods](docs/pipeline.md#75-measure-methods)
-8. [Generating mock data](docs/generate.md)
+9. [Generating mock data](docs/generate.md)
     1. [Creating a filterbank file](docs/generate.md#81-creating-a-filterbank-file)
     2. [Generate signal](docs/generate.md#82-generate-signal)
     3. [Generate header](docs/generate.md#83-generate-header)

docs/dedispersion.md

@@ -0,0 +1,83 @@
+# 7. Dedispersion
+
+## 7.1 Introduction
+
+- Pulsars produce a narrow beam of electromagnetic
+radiation which rotates like a lighthouse beam, so
+a pulse is seen as it sweeps over a radiotelescope.
+The signal is spread over a wide frequency range.
+
+- If space was an empty vacuum, all the signals would
+travel at the same speed, but due to free electrons
+different frequencies travel at slightly different speeds
+(dispersion).
+
+## 7.2 Dedisperse
+
+This method performs dedispersion on the filterbank data.
+
+### 7.2.1 Parameters
+
+| Parameters | Description |
+|---|---|
+| Samples | Array or sequence containing the data to be plotted. |
+| DM | Dispersion measure (cm<sup>-3</sup> pc) |
+
+### 7.2.2 Returns
+
+| Variable | Description |
+|---|---|
+| Samples | Dedispersed samples |
+
+## 7.3 find_dm
+
+This method finds the dispersion measure.
+
+### 7.3.1 Parameters
+
+| Parameters | Description |
+|---|---|
+| Samples | 1-D array or sequence. Array or sequence containing the data to be plotted. |
+
+### 7.3.2 Returns
+
+| Variable | Description |
+|---|---|
+| dm | Dispersion measure |
+
+## 7.4 find_line
+
+This method finds a line starting from the sample index given in the parameters. This will stop if there isn't a intensity within the max_delay higher than the average_intensity.
+
+### 7.4.1 Parameters
+
+| Parameters | Description |
+|---|---|
+| Samples | 1-D array or sequence. Array or sequence containing the data to be plotted. |
+| start_sample_index | The start sample index |
+| max_delay | The max delay of the recieved signal |
+| average_intensity | The average intensity |
+
+### 7.4.2 Returns
+
+| Variable | Description |
+|---|---|
+| start_sample_index | The first frequency |
+| previous_sample_index | The higher frequency |
+
+## 7.5 find_estimation_intensity
+
+This method finds the average intensity for top x intensities.
+The `average_intensity` is considered a requirement for intensities to be considered a pulsar.
+
+### 7.5.1 Parameters
+
+| Parameters | Description |
+|---|---|
+| Samples | Array or sequence containing the data to be plotted. |
+
+### 7.5.2 Returns
+
+| Variable | Description |
+|---|---|
+| average_intensity | The avarage intesity |

docs/generate.md

@@ -1,6 +1,6 @@
-# 8. Generating mock data
+# 9. Generating mock data
 
-## 8.1 Creating a filterbank file
+## 9.1 Creating a filterbank file
 
 To generate a filterbank file you may use the following example code:
 ```python
@@ -25,7 +25,7 @@ header.generate_file("file_path/file_name", header)
 
 The header data is passed in a header dict. For a more detailed explanation on the file header, please consult [chapter 2.2](docs/filterbank.md#22-read-the-header-from-filterbank-data). 
 
-## 8.2 Generate signal
+## 9.2 Generate signal
 
 The generate_signal method generates a mock signal based on the following parameters:
 
@@ -36,15 +36,15 @@ The generate_signal method generates a mock signal based on the following parame
 | t_obs | observation time in s |
 | n_pts | intervals between samples |
 
-## 8.3 Generate header
+## 9.3 Generate header
 
 The generate_header method generates a header string based on the header dict provided in the example in chapter 8.1. The dict provides keys encoded in bytes and the method converts each keyword to a string using the keyword_to_string method (see below).
 
-## 8.4 Keyword to string
+## 9.4 Keyword to string
 
 The keyword_to_string method converts a keyword from the header dict to a serialized string.
 
-## 8.5 Write data
+## 9.5 Write data
 
 Once all the required data is generated to a filterbank file. The data is written to the file as bytes.
 

docs/pipeline.md

@@ -1,6 +1,6 @@
-# 7. Pipeline
+# 8. Pipeline
 
-## 7.1 Introduction
+## 8.1 Introduction
 
 The Pipeline module is used to execute the different modules in a specific order.
 There are currently three different options for running the pipeline.  
@@ -23,15 +23,15 @@ The constructor of the pipeline module will recognize which method is fit for ru
 
 After deciding which method to run for running the filterbank in a pipeline, it will measure the time it takes to run each method using `measure_method`. After running all the different methods, the constructor will append the results (a dictionary) to a txt file.
 
-## 7.2 Read rows
+## 8.2 Read rows
 
 The `read_rows` method reads the Filterbank data row per row. Because it only reads the filterbank per row, it is unable to execute most methods. The alternative for this method is the `read_n_rows` method, which is able to run all methods.
 
 ```
 pipeline.Pipeline(<filterbank_file>, as_stream=True)
 ```
 
-## 7.3 Read n rows
+## 8.3 Read n rows
 
 The `read_n_rows` method first splits all the filterbank data into chunks of n samples. After splitting the filterbank data in chunks, it will run the different modules of the pipeline for each chunk. The remaining data, that which does not fit into the sample size, is currently ignored.
 
@@ -41,15 +41,15 @@ The `n` or sample size should be a power of 2 multiplied with the given scale fo
 pipeline.Pipeline(<filterbank_file>, n=<size> , as_stream=True)
 ```
 
-## 7.4 Read static
+## 8.4 Read static
 
 The `read_static` method reads the entire filterbank at once, and applies each method to the entire dataset. If the filterbank file is too large for running it in-memory, the alternative is using `read_n_rows`.
 
 ```
 pipeline.Pipeline(<filterbank_file>)
 ```
 
-## 7.5 Measure methods
+## 8.5 Measure methods
 
 The `measure_methods` is ran for each of the above methods, and calculates the time it takes to run each of the different methods. For each method it will create a key using the name of the method, and save the time it took to run the method as a value.
 At the end, it will returns a dictionary with all the keys and values.