Create case-studies.md

1 files changed, 361 insertions, 0 deletions

diff --git a/api/case-studies.md b/api/case-studies.md
new file mode 100644
index 0000000..15f974a
--- /dev/null
+++ b/api/case-studies.md
@@ -0,0 +1,361 @@
+# Case studies
+
+## The Hp1bp3 transcript
+Investigate Hp1bp3, which has a cis-QTL in hippocampus and is associated with cognitive ageing.
+
+___
+Search for the dataset:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/datasets?search=hippocampus
+
+[API v1]: # https://genenetwork.org/api/v_pre1/datasets/bxd
+```
+[
+	{
+    "AvgID": 1, 
+    "CreateTime": "Mon, 24 Oct 2005 00:00:00 GMT", 
+    "DataScale": "log2", 
+    "FullName": "Hippocampus Consortium M430v2 (Oct05) MAS5", 
+    "Id": 86, 
+    "Long_Abbreviation": "Hippocampus_M430_V2_BXD_MAS5_Oct05", 
+    "ProbeFreezeId": 24, 
+    "ShortName": "Hippocampus M430v2 BXD 10/05 MAS5", 
+    "Short_Abbreviation": "HC_M2_1005_M", 
+    "confidentiality": 0, 
+    "public": 0
+  }, 
+  {
+    "AvgID": 3, 
+    "CreateTime": "Mon, 24 Oct 2005 00:00:00 GMT", 
+    "DataScale": "log2", 
+    "FullName": "Hippocampus Consortium M430v2 (Oct05) RMA", 
+    "Id": 87, 
+    "Long_Abbreviation": "Hippocampus_M430_V2_BXD_RMA_Oct05", 
+    "ProbeFreezeId": 24, 
+    "ShortName": "Hippocampus M430v2 BXD 10/05 RMA", 
+    "Short_Abbreviation": "HC_M2_1005_R", 
+    "confidentiality": 0, 
+    "public": 0
+  }, 
+  {
+    "AvgID": 2, 
+    "CreateTime": "Mon, 24 Oct 2005 00:00:00 GMT", 
+    "DataScale": "log2", 
+    "FullName": "Hippocampus Consortium M430v2 (Oct05) PDNN", 
+    "Id": 88, 
+    "Long_Abbreviation": "Hippocampus_M430_V2_BXD_PDNN_Oct05", 
+    "ProbeFreezeId": 24, 
+    "ShortName": "Hippocampus M430v2 BXD 10/05 PDNN", 
+    "Short_Abbreviation": "HC_M2_1005_P", 
+    "confidentiality": 0, 
+    "public": 0
+  }
+]
+
+```
+This should return a list of all hippocampal _datasets_ containing the phrase 'hippocampus' (or its lemma).
+The user can then look through the descriptions and decide which one they need.
+In this case the appropriate key is `HC_M2_0606_P`.
+
+We could also just get a listing of all datasets and work through them locally (by eye or with a local grep).
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/datasets
+
+In all cases, giving the generic term (`species`, `populations`, `datasets`, `traits`) will return a listing of all descendent options.
+
+Just using the instance keys as the endpoint (e.g. `api/v2/Mus_musculus`, `api/v2/Mus_musculus/BXD`, `api/v2/Mus_musculus/BXD/HC_M2_0606_P`) will return metadata about the level (about the species 'mouse', the population 'BXD' or the dataset 'HC_M2_0606_P' respectively in the above examples).
+
+___
+To continue, we dig down and search the dataset for the desired gene name:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/traits?search&symbol=Hp1bp3
+
+```
+[
+	{
+	  "additive": -0.15845054446461, 
+	  "alias": "HP1BP74; HP1-BP74; Hp1bp74", 
+	  "chr": "4", 
+	  "description": "heterochromatin protein 1, binding protein 3", 
+	  "id": 78509, 
+	  "locus": "rsm10000002056", 
+	  "lrs": 57.6845496792109, 
+	  "mb": 138.242585, 
+	  "mean": 12.2393434343434, 
+	  "name": "1415751_at", 
+	  "p_value": 0.0, 
+	  "se": null, 
+	  "symbol": "Hp1bp3"
+	},
+	{
+	  "additive": -0.489152777777777, 
+	  "alias": "HP1BP74; HP1-BP74; Hp1bp74", 
+	  "chr": "4", 
+	  "description": "heterochromatin protein 1, binding protein 3", 
+	  "id": 102578, 
+	  "locus": "rsm10000002058", 
+	  "lrs": 96.3121317863362, 
+	  "mb": 138.244118, 
+	  "mean": 8.88365656565657, 
+	  "name": "1439845_at", 
+	  "p_value": 0.0, 
+	  "se": null, 
+	  "symbol": "Hp1bp3"
+	},
+	{
+	  "additive": -0.037382526029878, 
+	  "alias": "HP1BP74; HP1-BP74; Hp1bp74; 2310026L22Rik", 
+	  "chr": "4", 
+	  "description": "heterochromatin protein 1, binding protein 3", 
+	  "id": 110688, 
+	  "locus": "rs32937254", 
+	  "lrs": 13.2029671197265, 
+	  "mb": 138.21577, 
+	  "mean": 6.51316161616162, 
+	  "name": "1447955_at", 
+	  "p_value": 0.317, 
+	  "se": null, 
+	  "symbol": "Hp1bp3"
+	}
+]
+```
+
+This gives us the three probesets associated with Hp1bp3 and some metadata (name, aliases, expression, precomputed QTL etc.).
+We decide that `1439845_at` is the correct probeset.
+
+___
+Get more information about `1439845_at` including the metadata noted above, but also microarray platform, probe composition and mapping, chromosomal position, gene/transcript length, links to gene info (NCBI, Wikidata), homologous genes in other species, [what other datasets contain data for this gene] etc.:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/1439845_at
+
+[API v1]: # https://genenetwork.org/api/v_pre1/trait/HC_M2_0606_P/1439845_at
+```
+[
+	{
+	  "additive": -0.489152777777777, 
+	  "alias": "HP1BP74; HP1-BP74; Hp1bp74", 
+	  "chr": "4", 
+	  "description": "heterochromatin protein 1, binding protein 3", 
+	  "id": 102578, 
+	  "locus": "rsm10000002058", 
+	  "lrs": 96.3121317863362, 
+	  "mb": 138.244118, 
+	  "mean": 8.88365656565657, 
+	  "name": "1439845_at", 
+	  "p_value": 0.0, 
+	  "se": null, 
+	  "symbol": "Hp1bp3",
+	  "wikidata": "Q18251298",
+	  "homologene", "7774",
+	}
+]
+```
+*Should include all of the data shown at https://genenetwork.org/show_trait?trait_id=1439845_at&dataset=HC_M2_0606_P*
+
+___
+Get the expression data for this trait:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/1439845_at/data
+
+```
+[
+  {
+    "data_id": 23426549, 
+    "sample_name": "129S1/SvImJ", 
+    "sample_name_2": "129S1/SvImJ", 
+    "se": 0.219, 
+    "value": 6.61
+  }, 
+  {
+    "data_id": 23426549, 
+    "sample_name": "A/J", 
+    "sample_name_2": "A/J", 
+    "se": 0.158, 
+    "value": 6.536
+  }, 
+  {
+    "data_id": 23426549, 
+    "sample_name": "AKR/J", 
+    "sample_name_2": "AKR/J", 
+    "se": 0.076, 
+    "value": 6.486
+  }, 
+  {
+    "data_id": 23426549, 
+    "sample_name": "B6D2F1", 
+    "sample_name_2": "B6D2F1", 
+    "se": 0.09, 
+    "value": 6.561
+  }, 
+	.
+	.
+	.
+]
+```
+
+This is a data endpoint, so the returned JSON includes a vector of the transcript expression values for this probeset.
+
+If we wanted to grab the whole microarray dataset, then we can just use the data keyword one level up.
+Here, a return type can also be specified
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/BXD/data.tsv
+
+This returns a tab-delimited table of data (probesets in columns, strains/individuals in rows) for download.
+
+___
+Get the QTL vector:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/1439845_at/qtl?method=GEMMA&genotype=mm10
+
+[API v1]: # https://genenetwork.org/api/v_pre1/mapping?trait_id=1447955_at&db=HC_M2_0606_P&method=gemma&use_loco=FALSE&use_loco=0.01
+```
+[
+  [
+    {
+      "Mb": 3.00149, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rsm10000000001", 
+      "p_value": 0.8698536
+    }, 
+    {
+      "Mb": 3.010274, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rs31443144", 
+      "p_value": 0.8698536
+    }, 
+    {
+      "Mb": 3.492195, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rs6269442", 
+      "p_value": 0.8698536
+    }, 
+    {
+      "Mb": 3.511204, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rs32285189", 
+      "p_value": 0.8698536
+    }, 
+    {
+      "Mb": 3.659804, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rs258367496", 
+      "p_value": 0.8698536
+    }, 
+    {
+      "Mb": 3.777023, 
+      "additive": -0.0017764785, 
+      "chr": 1, 
+      "lod_score": 0.06055383480931299, 
+      "name": "rs32430919", 
+      "p_value": 0.8698536
+    },
+    .
+    .
+    .
+ ]
+```
+
+This is also a data endpoint, so we get a vector of p-values together with a vector of chromosomal positions.
+
+
+___
+Correlate with all phenotypes:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/1439845_at/correlations?method=spearmann&dataset=phenotypes&n_results=10
+
+[API v1]: # https://genenetwork.org/api/v_pre1/correlation?trait_id=1447955_at&db=HC_M2_0606_P&target_db=BXDPublish&type=sample&method=spearman&return=10 
+[Error]: # This returns 500 results.
+```
+[
+  {
+    "#_strains": 7, 
+    "p_value": 0.0025194724037946874, 
+    "sample_r": 0.9285714285714288, 
+    "trait": "12562"
+  }, 
+  {
+    "#_strains": 13, 
+    "p_value": 2.4445741031329683e-05, 
+    "sample_r": 0.9023392305243964, 
+    "trait": "12889"
+  }, 
+  {
+    "#_strains": 7, 
+    "p_value": 0.01369732661532562, 
+    "sample_r": -0.8571428571428573, 
+    "trait": "19087"
+  }, 
+  {
+    "#_strains": 13, 
+    "p_value": 0.00039102596905431295, 
+    "sample_r": 0.8342668763658431, 
+    "trait": "20884"
+  }, 
+  {
+    "#_strains": 8, 
+    "p_value": 0.01017554012345675, 
+    "sample_r": -0.8333333333333335, 
+    "trait": "10409"
+  }, 
+  {
+    "#_strains": 8, 
+    "p_value": 0.01017554012345675, 
+    "sample_r": -0.8333333333333335, 
+    "trait": "10410"
+  }, 
+  {
+    "#_strains": 6, 
+    "p_value": 0.04156268221574334, 
+    "sample_r": 0.8285714285714287, 
+    "trait": "20393"
+  }, 
+  {
+    "#_strains": 6, 
+    "p_value": 0.04156268221574334, 
+    "sample_r": -0.8285714285714287, 
+    "trait": "20595"
+  }, 
+  {
+    "#_strains": 10, 
+    "p_value": 0.0038149200825507135, 
+    "sample_r": -0.8181818181818182, 
+    "trait": "16177"
+  }, 
+  {
+    "#_strains": 15, 
+    "p_value": 0.000219365827727102, 
+    "sample_r": 0.8142857142857142, 
+    "trait": "27198"
+  }
+ ]
+```
+It is not necessary to specify the target at any level above dataset as correlations can only be performed within a population.
+
+___
+Correlate with a specific trait:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/HC_M2_0606_P/1439845_at/correlations?method=pearson&dataset=HC_M2_0606_P&traits=1415751_at,1447955_at
+
+Here, we have correlated against the two other Hs1bp3 probesets, which are specified by a comma-delimited list of trait IDs.
+
+Correlation across different datasets would be achieved by multiple API calls.
+Although there may be a way to line up a series of calls and have them run as a batch (I presume more complicated queries like this would be done via a POST interface though).
+
+___
+More advanced searches could allow restricting the search to certain fields:
+
+https://genenetwork.org/api/v2/Mus_musculus/BXD/datasets?search&type=transcript&tag=hippocampus
+
+I would support using tags to associate keywords with items at all levels.
+Here, the `search` parameter was left empty as we are looking for a phrase in a particular field.
+If all parameters are empty, this should not fail but return the same as the `datasets` query without the parameters (i.e. return a listing of all available datasets).