# MoMac API Documentation

## Overview
This API provides access to the MoMac (Microbiome and Cancer) dataset, which contains information about the relationship between microbes and cancer features.

## Base URL
All API endpoints are prefixed with `/momac-api/`

## Authentication
No authentication required for public access.

## Endpoints

### 1. Search MoMac Data
```
GET /momac-api/momacsearch/
```

#### Parameters
- `cancer_type` (string): Filter by cancer type (e.g., TCGA-BRCA)
- `features` (string): Filter by features (e.g., gene names, cell types)
- `microbe` (string): Filter by microbe name
- `enriched` (string): Filter by enrichment status (e.g., "Nonzero", "Zero")
- `data_type` (string): Filter by data type ("rob" or "sal")
- `feature_type` (string): Filter by feature type ("cell", "gene", "meth", "pro")
- `level` (string): Filter by level (e.g., "level2")
- `p_value` (number): Filter by p-value (less than)
- `adjusted_p_value` (number): Filter by adjusted p-value (less than)
- `fold_change` (number): Filter by fold change (greater than)
- `permutation_p_value` (number): Filter by permutation p-value (less than)
- `search` (string): Search across cancer_type, features, and microbe fields
- `page` (integer): Page number for pagination
- `page_size` (integer): Number of items per page (default: 20, max: 100)

#### Example Request
```
GET /momac-api/momacsearch/?cancer_type=TCGA-BRCA&feature_type=gene&limit=10
```

#### Example Response
```json
{
    "count": 1234,
    "next": "http://example.com/momac-api/momacsearch/?cancer_type=TCGA-BRCA&feature_type=gene&limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": 1,
            "cancer_type": "TCGA-BRCA",
            "features": "WNK2",
            "microbe": "Corynebacterium_kefirresidentii",
            "avg_zero": 542.164647959184,
            "avg_nonzero": 1192.99772727273,
            "med_zero": 357.926,
            "med_nonzero": 884.919,
            "p_value": 0.000685915768153438,
            "fold_change": 2.20043437314367,
            "adjusted_p_value": 0.0967465519920832,
            "enriched": "Nonzero",
            "permutation_average_fc": 1.04,
            "permutation_sd": 0.34,
            "permutation_p_value": 0.0,
            "level": "level2",
            "data_type": "rob",
            "feature_type": "gene"
        }
    ]
}
```

### 2. Autocomplete
```
GET /momac-api/momacsearch/autocomplete/
```

#### Parameters
- `q` (string): Query string for autocomplete (minimum 3 characters)

#### Example Request
```
GET /momac-api/momacsearch/autocomplete/?q=TCGA
```

#### Example Response
```json
{
    "suggestions": [
        "TCGA-BRCA",
        "TCGA-COAD",
        "TCGA-LUAD"
    ]
}
```

### 3. Word Cloud Data
```
GET /momac-api/wordcloud/
```

#### Parameters
- `dataset` (string): Filter by dataset type ("rob" or "sal"), default is "rob"
- `cancer_type` (string): Filter by cancer type (e.g., TCGA-BRCA)
- `features` (string): Filter by features (e.g., gene names, cell types)
- `microbe` (string): Filter by microbe name
- `enriched` (string): Filter by enrichment status (e.g., "Nonzero", "Zero")
- `data_type` (string): Filter by data type ("rob" or "sal")
- `feature_type` (string): Filter by feature type ("cell", "gene", "meth", "pro")
- `level` (string): Filter by level (e.g., "level2")
- `p_value` (number): Filter by p-value (less than)
- `adjusted_p_value` (number): Filter by adjusted p-value (less than)
- `fold_change` (number): Filter by fold change (greater than)
- `permutation_p_value` (number): Filter by permutation p-value (less than)
- `search` (string): Search across cancer_type, features, and microbe fields

#### Additional Filtering
The Word Cloud endpoint applies additional filtering to the data:
- Only includes records with `adjusted_p_value < 0.05`
- Only includes records with `permutation_p_value < 0.05`

#### Example Requests
```
GET /momac-api/wordcloud/  # Default rob dataset
GET /momac-api/wordcloud/?dataset=sal  # sal dataset
GET /momac-api/wordcloud/?cancer_type=TCGA-BRCA
```

#### Example Response
```json
{
    "ymeth": [["methylation_feature_1", 25], ["methylation_feature_2", 18]],
    "cancer": [["TCGA-BRCA", 42], ["TCGA-COAD", 38]],
    "microbe": [["Escherichia_coli", 35], ["Bacteroides_fragilis", 29]],
    "ycell": [["T_cells", 31], ["B_cells", 27]],
    "ygene": [["TP53", 45], ["BRCA1", 39]],
    "yprot": [["protein_A", 22], ["protein_B", 19]]
}
```

## Data Fields Description

| Field | Description |
|-------|-------------|
| cancer_type | Type of cancer (e.g., TCGA-BRCA) |
| features | Features being analyzed (gene names, cell types, etc.) |
| microbe | Microbe name |
| avg_zero | Average value when feature is zero |
| avg_nonzero | Average value when feature is non-zero |
| med_zero | Median value when feature is zero |
| med_nonzero | Median value when feature is non-zero |
| p_value | P-value of the association |
| fold_change | Fold change between zero and non-zero groups |
| adjusted_p_value | Adjusted p-value (FDR correction) |
| enriched | Enrichment status ("Nonzero" or "Zero") |
| permutation_average_fc | Average fold change from permutation test |
| permutation_sd | Standard deviation from permutation test |
| permutation_p_value | P-value from permutation test |
| level | Analysis level |
| data_type | Data type ("rob" or "sal") |
| feature_type | Type of feature ("cell", "gene", "meth", "pro") |

## Filtering Examples

1. Get all gene features for breast cancer:
   ```
   GET /momac-api/momacsearch/?cancer_type=TCGA-BRCA&feature_type=gene
   ```

2. Get features with significant p-values (p < 0.05):
   ```
   GET /momac-api/momacsearch/?p_value=0.05
   ```

3. Get features with high fold change (fold_change > 2):
   ```
   GET /momac-api/momacsearch/?fold_change=2
   ```

4. Search for specific microbe:
   ```
   GET /momac-api/momacsearch/?microbe=Escherichia_coli
   ```

## Pagination
All list endpoints support pagination:
- `page_size`: Number of items per page (default: 20, max: 100)
- `page`: Page number

Example:
```
GET /momac-api/momacsearch/?page_size=50&page=2
```

## MomacSearchFilter Details

The API uses `MomacSearchFilter` for filtering data in both the search and word cloud endpoints. This filter provides the following filtering capabilities:

### Filter Parameters

| Parameter | Field | Lookup | Description |
|-----------|-------|--------|-------------|
| `p_value` | `p_value` | `lt` | Filter by p-value (less than) |
| `adjusted_p_value` | `adjusted_p_value` | `lt` | Filter by adjusted p-value (less than) |
| `fold_change` | `fold_change` | `gt` | Filter by fold change (greater than) |
| `permutation_p_value` | `permutation_p_value` | `gt` | Filter by permutation p-value (greater than) |

### Model Fields Available for Filtering

| Field | Type | Description |
|-------|------|-------------|
| `cancer_type` | string | Type of cancer (e.g., TCGA-BRCA) |
| `features` | string | Features being analyzed (gene names, cell types, etc.) |
| `microbe` | string | Microbe name |
| `enriched` | string | Enrichment status ("Nonzero" or "Zero") |
| `data_type` | string | Data type ("rob" or "sal") |
| `feature_type` | string | Type of feature ("cell", "gene", "meth", "pro") |
| `level` | string | Analysis level |

### Additional Filtering in Word Cloud Endpoint

The Word Cloud endpoint (`/momac-api/wordcloud/`) applies additional hard-coded filtering:
- `adjusted_p_value < 0.05`
- `permutation_p_value > 0.05`

These filters ensure that only statistically significant results are included in the word cloud data.