======================================
 Get Started with Cistrome Search API
======================================

.. highlight:: xml

Search a Sample
===============
Return a sample record that matches a speciefied query.

Resource URL
------------

http://cistrome.org/cisapi/get/s

.. warning::

   It's better **NOT** to open the above URL in browser as it'll cost huge memory space to render them in browser. Use ``wget`` or ``curl`` instead.

Parameters
----------

+-----+-------------------------------+
|     |                               |
+-----+-------------------------------+
|id   |The ID of the Sample (SampleID)|
|     |                               |
|     |**Example Values**: 100        |
+-----+-------------------------------+
|fid  |The ID of the Factor ChIPed in |
|     |the Sample.                    |
|     |                               |
|     |**Example Values**: 7          |
+-----+-------------------------------+
|uid  |The unique ID of the Sample    |
|     |(**Fuzzy Search**)             |
|     |                               |
|     |**Example Values**: ``SRX``,   |
|     |``ESM000328``                  |
+-----+-------------------------------+

Examples
--------

Fetch all (use ``wget`` or ``curl`` to fetch):
  http://cistrome.org/cisapi/get/s

Query the Samples with ``GSM58857`` as the UniqueID.
  http://cistrome.org/cisapi/get/s?uid=GSM58857

Query all Samples whose source is ENCODE and use ``41`` as the ID of Factor.
  http://cistrome.org/cisapi/get/s?uid=ESM&fid=41


Output Structure
----------------
  
::

  <?xml version="1.0" encoding="utf-8" ?>
  <samples >
    <sample id='1463' mode='id'>
      <factor>12</factor>
      <unique>GSM588576</unique>
      <cellLine>104</cellLine>
      <cellType>1</cellType>
      <cellPop>None</cellPop>
      <species>1</species>
      <tissue>7</tissue>
      <diseaseState>5</diseaseState>
      <paper>139</paper>
      <url>ftp://ftp-trace.ncbi.nih.gov/sra/sra-instant/reads/ByExp/sra/SRX/SRX038/SRX038747</url>
    </sample>
  </sample>
  </samples>


Search a Sample literally
=========================
Return a sample record that matches a speciefied query literally.

.. note::

  This function is different from the function above because it will output the actual **names** of each entity such as Factor and CellLine instead of **IDs**.


Resource URL
------------

http://cistrome.org/cisapi/get/s2

.. warning::

   It's better **NOT** to open the above URL in browser as it'll cost huge memory space to render them in browser. Use ``wget`` or ``curl`` instead.

Parameters
----------


+--------------+---------------------------------------+
|              |                                       |
+--------------+---------------------------------------+
|id            |The ID of the Sample (Sample           |
|              |ID)                                    |
|              |                                       |
|              |**Example Values**: 5                  |
+--------------+---------------------------------------+
|uid           |The Unique ID of the Sample            |
|              |(**Fuzzy Search**)                     |
|              |                                       |
|              |**Example Values**:                    |
|              |``GSM588574``                          |
+--------------+---------------------------------------+
|fname         |The Factor name of the Sample          |
|              |                                       |
|              |**Example Values**: ``ctcf``           |
+--------------+---------------------------------------+
|dname         |The DiseaseState name of the           |
|              |Sample                                 |
|              |                                       |
|              |**Example Values**: ``Ductal           |
|              |Carcinoma``                            |
+--------------+---------------------------------------+
|clname        |The CellLine name of the               |
|              |Sample                                 |
|              |                                       |
|              |**Example Values**: ``MCF-7``          |
+--------------+---------------------------------------+
|ctname        |The CellType name of the               |
|              |Sample                                 |
|              |                                       |
|              |**Example Values**: ``Epithelial``     |
+--------------+---------------------------------------+
|cpname        |The CellPop name of the Sample         |
|              |                                       |
|              |**Example Values**: ``HCF``, ``CD4``   |
|              |                                       |
+--------------+---------------------------------------+
|tname         |The Tissue name of the Sample          |
|              |                                       |
|              |**Example Values**: ``Blood``          |
+--------------+---------------------------------------+
|sname         |The Species name of the Sample         |
|              |                                       |
|              |**Example Values**: ``Homo sapiens``   |
+--------------+---------------------------------------+
|pid           |The PaperID of the Sample              |
|              |                                       |
|              |**Example Values**: ``1``              |
+--------------+---------------------------------------+
|pmid          |The Pubmed ID of the Paper for the     |
|              |Sample                                 |
|              |                                       |
|              |**Example Values**: ``22237151``       |
+--------------+---------------------------------------+
|aname         |One of the authors' names of the Sample|
|              |                                       |
|              |**Example Values**: ``Young RA``, ``Ren|
|              |B``                                    |
+--------------+---------------------------------------+

.. warning::

   If you want to search CD4+ Cell Population, please use ``cd4`` instead of ``cd4+`` to search. The reason is that `+` will be escaped in the URL call.

Example
-------

Query the Samples done by Shirley's lab
  http://cistrome.org/cisapi/get/s2?aname=liu%20xs
Query the H3K4me3 Samples in cells related to embryo with Normal state
  http://cistrome.org/cisapi/get/s2?fname=h3k4me3&sname=mus&dname=normal&ctname=embryo  
Query the samples whose Pubmed ID is 22237151 and use CD4+ as Cell Population
  http://cistrome.org/cisapi/get/s2?cpname=cd4&pmid=22237151  

Output Structure
----------------
  
::

  <?xml version="1.0" encoding="utf-8" ?>
  <?xml-stylesheet type="text/xsl" href="/cisapi_static/sample2.xsl" ?>
  <samples >
    <sample id='435' mode='verbose'>
      <factor>H3K27me3</factor>
      <cellLine>nil</cellLine>
      <cellType>T Lymphocyte</cellType>
      <cellPop>CD4+ / CD8+</cellPop>
      <species>Mus musculus</species>
      <tissue>Blood</tissue>
      <diseaseState>nil</diseaseState>
      <paper>Genetic inactivation of the polycomb repressive complex 2 in T cell acute lymphoblastic leukemia</paper>
      <pmid>22237151</pmid>
      <authors>Ntziachristos P, Tsirigos A, Vlierberghe PV, Nedjic J, Trimarchi T, Flaherty MS, Ferres-Marco D, da Ros V, Tang Z, Siegle J, Asp P, Hadler M, Rigo I, Keersmaecker KD, Patel J, Huynh T, Utro F, Poglio S, Samon JB, Paietta E, Racevskis J, Rowe JM, Rabadan R</authors>
      <uniqueID>GSM859496</uniqueID>
      <url>None</url>
    </sample>
  </samples>

  
Search a Dataset
================

Return a Dataset record that match a specified query.

Resource URL
------------

http://cistrome.org/cisapi/get/d

Parameters
----------

+-----+------------------------------------------------------------------------+
|     |                                                                        |
+-----+------------------------------------------------------------------------+
|id   |The ID of the Dataset                                                   |
|     |                                                                        |
|     |**Example Values**: ``1``, ``1456``                                     |
|     |                                                                        |
+-----+------------------------------------------------------------------------+
|uid  |The sample ID of the Samples that a Dataset contains                    |
|     |                                                                        |
|     |**Example Values**: ``890``, ``                                         |
|     |                                                                        |
|     |                                                                        |
+-----+------------------------------------------------------------------------+

.. warning::

   The meaning of uid here has changed. It now uses Sample ID instead of unique ID to search.


Examples
--------

Fetch all:
  http://cistrome.org/cisapi/get/d

Query ``Dataset 5512``:
  http://cistrome.org/cisapi/get/d?id=5512

Search a Dataset Literally
==========================

Return a Dataset record that match a specified query literally.

Resource URL
------------

http://cistrome.org/cisapi/get/d2

Parameters
----------

+-----+------------------------------------------------------------------------+
|     |                                                                        |
+-----+------------------------------------------------------------------------+
|id   |The ID of the Dataset                                                   |
|     |                                                                        |
|     |**Example Values**: ``1``, ``1456``                                     |
|     |                                                                        |
+-----+------------------------------------------------------------------------+


Examples
--------

Query ``Dataset 5092``:
  http://cistrome.org/cisapi/get/d2?id=5092



Output Structure
----------------
  
::


  <?xml version="1.0" encoding="utf-8" ?>
  <?xml-stylesheet type="text/xsl" href="/cisapi_static/dataset2.xsl" ?>
  <dataset id='5099'>
  <treatment >
   <sample id='921' mode='verbose'>
    <factor>HNF4G</factor>
    <cellLine>HepG2</cellLine>
    <cellType>Epithelial</cellType>
    <cellPop>nil</cellPop>
    <species>Homo sapiens</species>
    <tissue>Liver</tissue>
    <diseaseState>Hepatocellular Carcinoma</diseaseState>
    <paper>Proteomic analysis of native hepatocyte nuclear factor-4? (HNF4?) isoforms, phosphorylation status, and interactive cofactors.</paper>
    <pmid>21047794</pmid>
    <authors>Daigo K,Kawamura T,Ohta Y,Ohashi R,Katayose S,Tanaka T,Aburatani H,Naito M,Kodama T,Ihara S,Hamakubo T</authors>
    <uniqueID>GSM469865</uniqueID>
    <url>ftp://ftp-trace.ncbi.nih.gov/sra/sra-instant/reads/ByExp/sra/SRX/SRX018/SRX018627</url>
   </sample>
  </treatment>
  <control >
  </control>
  </dataset>