# Documentation for Enrichment APIs :

### 1. Create Enrichment
- Creates a new enrichment.
- This API has support to add multiple groups at a time.
- It has support to add a collection

**params:**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| name | Name of the enrichment | string | Pathway Metabolites | no |
| groups | Name of the groups to be added | string/list | testGroup or testGroup1,testGroup2,... | yes |
| collections | collection ids to which the enrichment should to be added | string/list | root-wikipedia | yes |
| description | Information about the enrichment | string | Genes related insights | yes |
| meta | meta info of the enrichment | dictionary | {'key' : 'value' } | yes |

- Accepts only one collection id ( If more than one is given the Following Exception will be raised )

{
     message: {
     enrichment_id: "nfer-disease-contexts-enrichment",
     collections: [
       {
        collection_id: "root-companies",
        name: "Companies"
       }
     ],
     user_message: "The Following collections are already associated with an enrichment"
    },
     success: false
}

**Ref link :**

**GET Request :**
https://pre-staging.nferx.com/api/create_enrichment?name=mesh1&groups=testgroup1,testgroup2&description=info&collections=root-enrichment

**POST Request :**

data = { 
        "name":"Pathway Metabolites",
        "groups":['testgroup1','testgroup2'],
        "description":"info",
        "meta": {"data" : "data"},
        "collections" : 
}
requests.post('https://pre-staging/api/create_enrichment', auth=auth, data=json.dumps(data))

**Response :**

{
result: 'Enrichment "Pathway Metabolites" created successfully',
success: true
}

### 2.Delete Enrichment
- Deletes enrichments for given id.
- This API has support to delete multiple enrichments at a time.

**params:**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| ids | A unique identifier for the enrichment | string/list | pathway_metabolites | no |

**Ref link :**

**GET Request :**
https://pre-staging.nferx.com/api/delete_enrichment?ids=root-pathwaysmetabolitietestings23

**POST Request :**

data ={
       "ids":['enrichment1','enrichment2','enrichment3']
       }
requests.post('https://dc-preview.nferx.com/api/delete_enrichment', auth=auth, data=json.dumps(data))

**Response :**

{
result: "Enrichments deleted successfully",
success: true
}

### 3.Update enrichment

- Updates enrichment info like name, description, meta, groups, collections etc.
- Accepts only one collection

**params:**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| id | A unique identifier for the enrichment | string | pathway_metabolites | no |
| name | Name of the enrichment | string | Pathway Metabolites | yes |
| description | Information about the enrichment | string | Genes related insights | yes |
| meta | meta info of the enrichment | dict | {'key' : 'value' } | yes |
| groups | Collection Groups | string/list | 'testgroup1,testgroup2' | yes |
| collections | Collection ids | string/list | 'coll_id1' | yes |
| Replace | Delete all the info for the enrihment present and add the new info | Boolean | true/false(default) | yes |

**Ref link :**

**GET Request :**
https://pre-staging/api/update_enrichment?id=root-pathwaysmetabolitietestings23&name=PathwayMetabolities

**POST Request:**

data = {
       "id":"pathway_metabolities",
       "name":"Pathway Metabolities",
       "description":"Info",
       "meta": {"data" : "data"}
       }
requests.post('https://pre-staging/api/update_enrichment', auth=auth, data=json.dumps(data))

**Response :**

{
result: '"Pathway Metabolities" Enrichment Info updated successfully',
success: true
}

**Replace**:

**GET Request :**
https://pre-staging/api/update_enrichment?id=root-pathwaysmetabolitietestings23&name=PathwayMetabolities&groups=Mesh&collections=root-wikipedia&replace=true

**POST Request:**

data = {
       "id":"pathway_metabolities",
       "name":"Pathway Metabolities",
       "description":"Info",
       "meta": {"data" : "data"},
       "groups" : [group1,group2],
       "collections" : [collection1,collection2],
       "replace" : True
       }
requests.post('https://pre-staging/api/update_enrichment', auth=auth, data=json.dumps(data))

**Response :**

{
result: '"Pathway Metabolities" Enrichment replaced successfully',
success: true
}

### 4.Update enrichment groups :

- This API has support add or remove groups from an enrichment

**params :**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| id | A unique identifier for the enrichment | string | mesh | no |
| groups | Name of the groups to be added | string/list | testGroup or testGroup1,testGroup2,... | no |
| action | To indicate if we want to add/delete groups in an enrichment | string | add/remove | no |

**Ref link :**

**GET Request :**
**To add :**
https://pre-staging.nferx.com/api/update_enrichment_groups?id=root-pathwaysmetabolitietestings23&groups=testgroup1,testgroup2,testgroup3&action=add

**To remove :**
https://pre-staging.nferx.com/api/update_enrichment_groups?id=root-pathwaysmetabolitietestings23&groups=testgroup1,testgroup2,testgroup3&action=remove

**POST Request:**

data = { 
        "id" :"pathway_metabolities",  
        "groups" : ['group1','group2','group3'], 
        "name"   : "pathway_metabolities1",
        "action" : "add"
     }

requests.post('https://pre-staging.nferx.com/api/update_enrichment_groups', auth=auth, data=json.dumps(data))

**Response :**

{
result: "Added groups to enrichment successfully",
success: true
}

### 5.Update enrichments to collection :

- Adds or deletes enrichments for a collection
- This API has support to add or delete multiple enrichment for collection at a time.
- Need to update this. Currently it adds multiple enrichments. Will provide support where a collection should have only one enrichment.

**params :**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| coll_id | A unique identifier for the collection | string | root-genes | no |
| enrichment_ids | A unique identifier for the collection | string/list | mesh | no |
| action | To indicate if we want to add/delete enrichments in a collection | string | add/remove | no |

**Ref link :**

**GET Request :**
**To add :**
https://pre-staging.nferx.com/api/update_enrichments_to_collection?coll_id=root-genes&enrichment_ids=root-pathwaysmetabolitietestings23&action=add

**To remove :**
https://pre-staging.nferx.com/api/update_enrichments_to_collection?coll_id=root-genes&enrichment_ids=root-pathwaysmetabolitietestings23&action=remove

**POST Request:**

data = { 
        "coll_id" :"root-enrichment",  
        "enrichment_ids" : ['enrichment89','enrichment90'], 
        "action" : "add"
            }

requests.post('https://pre-staging.nferx.com/api/update_enrichments_for_collection', auth=auth, data=json.dumps(data))

**Response :**

{
result: "Enrichments added successfully",
success: true
}

### 6.Get Collection to enrichment :
- Gives enrichments info for a collection

**params :**

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| coll_ids | A unique identifier for the collection | string | root-diseases | no |

**Ref link :**

**GET Request :**
https://pre-staging.nferx.com/api/get_collection_to_enrichment?coll_ids=root-genes

**POST Request:**

data = {
    "coll_ids" :"root-genes",      
}

requests.post('https://pre-staging.nferx.com/api/get_collection_to_enrichment', auth=auth, data=json.dumps(data))

**Response Format:**

{
result:{
    collection_id : {
        enrichments : [{
            enrichment_id_1 : "id",
            enrichment_name : "name",
            dt_created : 1589545833,
            dt_updated : 4375893475
        },
            {
            enrichment_id_2 : "id",
            enrichment_name : "name",
            dt_created : 2387498327,
            dt_updated : 3232743223
            
    }]
}
}

**Example :**

{
result: {
    root-enrichment-1: {
        enrichments: [
                    { }
                    ]
                },
    root-enrichment: {
        enrichments: [
            {
            dt_updated: 1553765427,
            dt_created: 1553765427,
            name: "enrichment1",
            id: "testenrichment1"
        },
            {
            dt_updated: 1553765428,
            dt_created: 1553765428,
            name: "enrichment3",
            id: "testenrichment3"
        },
            {
            dt_updated: 1553834973,
            dt_created: 1553834973,
            name: "pathway_metabolites",
            id: "PathwayMetabolities1"
        },
            {
            dt_updated: 1553842216,
            dt_created: 1553842216,
            name: "root-root-pathwaymetabolites2",
            id: "root-pathwaymetabolites2"
        }
                ]
        }
},
success: true

### 7.Get enrichments :
- To get the enrichments matched for the given query or id

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| query | Character to search for | string | root-generic-name-stems | yes |
| sort_by | sort data by asc/desc order | string| desc(default) | yes |
| pagination | For pagination of results | boolean | True(default)/False | yes |
| num_per_page | Number of results per page | int | 50(default) | yes |
| page_num | To indicate the number of the page | int | 1(default) | yes |
| ids | Unique identifier for enrichment | string/list | root-mesh | yes |

**Ref link :**

**GET Request :**
https://pre-staging.nferx.com/api/get_enrichments
https://pre-staging.nferx.com/api/get_enrichments?query=pathway

**POST Request :**

data = { 
        "query" :"pathway",
        "page_num" : 2,
        }

requests.post('https://pre-staging.nferx.com/api/get_enrichments', auth=auth, data=json.dumps(data))

**Response :**

{
  "result": {
    "total_items": 7,
    "num_per_page": 50,
    "has_next_page" : true
    "enrichments": [
      {
        "description": "info",
        "dt_created": 1553783040,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553783040,
        "id": "pathway_metabolitestest",
        "name": "PathwayMetabolitestest"
      },
      {
        "description": "info",
        "dt_created": 1553784222,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553784222,
        "id": "pathway_metabolites123",
        "name": "PathwayMetabolites"
      },
      {
        "description": "",
        "dt_created": 1553840281,
        "meta": {},
        "groups": [
          "testgroup1",
          "testgroup3",
          "testgroup2"
        ],
        "owner": "root",
        "dt_updated": 1553863160,
        "id": "root-pathwaymetabolites",
        "name": "Pathway Metabolities"
      },
      {
        "description": "",
        "dt_created": 1553783059,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553783059,
        "id": "pathway_metabolitestest1",
        "name": "PathwayMetabolitestest1"
      },
      {
        "description": "",
        "dt_created": 1553863088,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553863088,
        "id": "root-pathwaymetabolites2",
        "name": "PathwayMetabolites2"
      },
      {
        "description": "",
        "dt_created": 1553842216,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553842216,
        "id": "root-root-pathwaymetabolites2",
        "name": "root-pathwaymetabolites2"
      },
      {
        "description": "info",
        "dt_created": 1553834973,
        "meta": {},
        "groups": [
          null
        ],
        "owner": "root",
        "dt_updated": 1553834973,
        "id": "pathway_metabolites",
        "name": "PathwayMetabolities1"
      }
    ],
    "page": 1
  },
  "success": true
}

### 8. get_enrichment_info_for_collection

| parameter | description | type | example | optional |
| --------- | ----------- | ---- | ------- | -------- |
| query | Character to search for | string | Drugs | yes |
| num_results | Number of results per page | int | 50(default) | yes |
| page_num | To indicate the number of the page | int | 1(default) | yes |
| ids | Collection ids | string/list | ['root-companies']/root-companies | yes |

Ref : https://pre-staging.nferx.com/api/get_enrichment_info_for_collection

**Response :**

{
result: {
total_items: 167286,
num_per_page: 2,
has_next_page: true,
enrichments: [
{
     enrichment_name: "",
     collection_id: "nfer-abnormality-of-the-globe-human-snp-ensembl",
     enrichment_id: "",
     groups: [ ],
     collection_name: "abnormality of the globe (Human SNP - ENSEMBL)"
},
{
     enrichment_name: "",
     collection_id: "nfer-5-2-acetamidoethylamino-naphthalene-1-sulfonic-acid-modulators-nferx-predicted",
     enrichment_id: "",
     groups: [ ],
     collection_name: "5_[2_Acetamidoethylamino]Naphthalene_1_Sulfonic_Acid Modulators (Nferx Predicted)"
},
],
page: 1
},
success: true
}