index.qmd

---
title: "Library"
format:
  html: 
    code-tools: 
      source: https://github.com/CGRG-lab/GEMS-MagTIP/blob/main/doc_library/index.qmd
include-after-body:
  - text: |
      <script>
      document.addEventListener('DOMContentLoaded', () => {
        const elements = document.querySelectorAll('[data-bs-toggle]');
        const noHash = !window.location.hash; // True if there's no hash in the URL
      
        if (noHash) {
          elements.forEach(element => {
            const isCollapsed = element.classList.contains('collapsed');
            // If it's not collapsed, click to collapse
            if (!isCollapsed) {
              element.click();
            }
          });
        }
      });
      </script>
# This is a javascript that reveal the collapsed element if linked with a hash, like doc_library/#main-functions
# https://github.com/quarto-dev/quarto-cli/discussions/6402
---

::: {.content-visible when-profile="en"}

::: {.callout-warning}
- Please don't assign undocumented name-value pair parameters to the functions. For example, `'CreateInfoOnly'` and `'InParforLoop'`, which are preserved for parallel computing, and you will never need to set them manually unless you are a developer.

:::
:::

::: {.content-visible when-profile="zhtw"}
::: {.callout-warning}
- 請勿將未記錄的名稱-值對參數分配給函數。例如，`'CreateInfoOnly'` 和 `'InParforLoop'`，這些參數是為平行運算保留的，除非您是開發者，否則無需手動設置它們。
:::

:::

## Main Functions

::: {.content-visible when-profile="en"}

There are four major stages in the complete GEMS-MagTIP workflow, and each stage is wrapped by the main functions as below: 

1. [`statind`](#statind): The calculation of statistical indices.
2. [`anomalyind`](#anomalyind): The calculation of anomaly indices number according to statistical indices.
3. [`molscore`](#molscore): Training phase based on anomaly indices, which involves the calculation of single-station TIP, matching TIP by target earthquakes and calculate Molchan scores accordingly.
4. [`molscore3`](#molscore3): Forecasting phase based on the model parameters of the highest Molchan scores, involving the calculation of joint-station TIP and probability based on the results of 2 and 3.

The four stages is wrapped by four functions with keyword arguments that we can customize some hyper parameters which are associated with model optimization and probability forecast. 
:::


::: {.content-visible when-profile="zhtw"}

在完整的 GEMS-MagTIP 工作流程中，主要分為四個階段，每個階段對應以下主要函數：

1. [`statind`](#statind)：統計指標的計算。
2. [`anomalyind`](#anomalyind)：基於統計指標計算異常指標數值。
3. [`molscore`](#molscore)：基於異常指標的訓練階段，包括單測站 TIP 的計算、匹配目標地震的 TIP，以及計算 Molchan 得分。
4. [`molscore3`](#molscore3)：基於最高 Molchan 得分的模型參數進行預報階段，包括計算聯合測站 TIP 和基於第 2、3 步結果的機率。

這四個階段由四個函數封裝，並提供關鍵字參數，允許我們自訂一些與模型優化和機率預報相關的超參數。

:::


::: {.callout-caution title="Docstring" collapse=false}

```{julia}
#| echo: false

using ReadMatlabDocstrings, GEMSMagTIPDocumentation, OkFiles, Markdown

y = [getdoc(dir_0("GEMS-MagTIP-insider/src/main/statind.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/statind_parfor.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/anomalyind.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/molscore.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/molscore_parfor.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/molscore3.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/main/molscore3_parfor.m"), filename_header=3)]

Markdown.parse(reduce(*, y))

```

:::


## Load raw data and convert it into a standard format

::: {.content-visible when-profile="en"}

Data of standard format denotes the formatted matfile that should contain only 1 field where the field name can be arbitrarily chosen. 
Saying the field to be `M`, `M` has to be a matrix where the column indices to time and data are assigned by function `fmt.colindex2data` (see [`fmt`](#format)) depending on the type of the data.

::: {.callout-warning}
Noted that `fmt.colindex2data` returns a set of indices for indexing into the data of standard format, whereas `columnind` (see docstring [below](#columnind)) returns a set of indices for indexing into the raw data.
:::

The naming of standard format data is critical. 
Please refer [`standarddataname`](#standarddataname) in the following docstring for the naming rule.


:::


::: {.content-visible when-profile="zhtw"}
標準格式資料表示應包含僅有一個欄位的格式化 matfile，該欄位名稱可任意選擇。假設欄位為 `M`，則 `M` 必須是一個矩陣，其時間和資料的欄位索引需依據資料類型由函數 `fmt.colindex2data`（參見 [`fmt`](#fmt)）分配。

::: {.callout-warning}
需注意，`fmt.colindex2data` 返回一組用於標準格式資料的索引，而 `columnind`（參見 [下方的 docstring](#columnind)）則返回一組用於原始資料的索引。
:::

標準格式資料的命名至關重要。
如需了解細節，請參考以下 docstring 中的 [`standarddataname`](#standarddataname) 以了解命名規則。
:::


::: {.callout-caution title="Docstring" collapse=false}


```{julia}
#| echo: false

y = [
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/conv_gemsdata.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/conv_geomagdata.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/readgems.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/read_gemsdat.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/geoelectric_projection.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/columnind.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/standarddataname.m"), filename_header=3),
    getdoc(dir_0("GEMS-MagTIP-insider/src/readdata/write_data.m"), filename_header=3),
]

Markdown.parse(reduce(*, y))
```

:::

## Available Preprocessing Functions

::: {.content-visible when-profile="en"}



{{< include "/GEMS-MagTIP-insider/src/preprocess/README.md" >}}
:::

::: {.content-visible when-profile="zhtw"}

{{< include "/GEMS-MagTIP-insider/src/preprocess/README-zhtw.md" >}}
:::

::: {.callout-caution title="Docstring" collapse=false}

```{julia}
#| echo: false

files = filelist(r".*\.m", dir_0("GEMS-MagTIP-insider/src/preprocess"))
y = [getdoc(f, filename_header=3) for f in files]

Markdown.parse(reduce(*, y))
```
:::

::: {.content-visible when-profile="en"}
::: {.callout-note}
`generalfilterprocess` is the core shared among `'ULF_X'` and `BP_X` family; please refer [Filtering Functions](#filtering-functions).
:::

:::

::: {.content-visible when-profile="zhtw"}
::: {.callout-note}
`generalfilterprocess` 是 `'ULF_X'` 和 `BP_X` 系列的核心共用函數；詳情請參考[濾波函數](#filtering-functions)。
:::

:::

## Filtering Functions

::: {.callout-caution title="Docstring" collapse=false}

```{julia}
#| echo: false

files = filelist(r".*\.m", dir_0("GEMS-MagTIP-insider/src/preprocess/filtering"))
y = [getdoc(f, filename_header=3) for f in files]

Markdown.parse(reduce(*, y))
```
:::


## Internal API for TIP Calculation

::: {.callout-caution title="Docstring" collapse=false}


```{julia}
#| echo: false

files = filelistall(dir_0("GEMS-MagTIP-insider/src/tip-calculation"))
y = [getdoc(f, filename_header=3) for f in files]

Markdown.parse(reduce(*, y))
```
:::

## Format

::: {.callout-caution title="Docstring" collapse=false}

```{julia}
#| echo: false

getdoc(dir_0("GEMS-MagTIP-insider/src/@fmt/fmt.m"), filename_header=3) |> Markdown.parse
```
:::


## Plotting functions

::: {.callout-caution}

```{julia}
#| echo: false

files = filelistall(dir_0("GEMS-MagTIP-insider/src/plot"))
y = [getdoc(f, filename_header=3) for f in files]

Markdown.parse(reduce(*, y))
```
:::

## Others

::: {.callout-caution title="Docstring" collapse=false}

```{julia}
#| echo: false

files = filelistall(dir_0("GEMS-MagTIP-insider/src/others"))
y = [getdoc(f, filename_header=3) for f in files]

Markdown.parse(reduce(*, y))
```
:::