MPD data API
• All endpoints are REST / HTTP GET.   Many examples available to try.   MPD Terms of Use apply.
• Use the domain   https://phenome.jax.org for all urls below.
• Results are JSON by default. Specify csv=yes to get CSV result unless otherwise indicated.
• Errors are indicated by a non-200 HTTP return code and "error" element.
• Available tutorials:
    • Get all data for a strain panel
    • Get all data for a center
    • Get all publications associated with QTL Archive projects

  Projects, data sets


/api/projects

Fetch a list of MPD projects / data sets. Each returned entry has some project attributes.
The following parameters can be supplied to filter the result (if none are specified then all projects are returned).
investigator ..... filter by pistring containing this, e.g. Gould TJ (case-insensitive)
projsym ..... retrieve a specific project by short name e.g. Gould2
projid ..... retrieve a specific project by integer ID eg. 471
mpdsector ..... filter by mpdsector term, e.g. pheno
largecollab ..... filter by largecollab term, e.g. HMDP
panelsym ..... filter by panelsym strain panel term, e.g. DO population
Example 1: /api/projects   (all projects)
Example 1a: /api/projects?csv=yes   (all projects, in CSV format)
Example 2: /api/projects?investigator=Gould TJ
Example 2a: /api/projects?investigator=jackson lab
Example 3: /api/projects?largecollab=HMDP
Example 4: /api/projects?panelsym=DO population
• Also available:   datasets.csv download file with all MPD projects.


/api/project_filters/filtername

This endpoint provides allowed filtering values for the /api/projects endpoint.
filtername is one of: mpdsector   largecollab   panelsym
Example 1: /api/project_filters/mpdsector
Example 2: /api/project_filters/panelsym
Example 3: /api/project_filters/largecollab


/api/projects/projsym/dataset

Return the project's entire dataset of measured phenotype animal values. By default this will be in CSV format; use json=yes to get JSON. Data set reflects any factor-related expansion. Some MPD projects don't have animal data; these will give a 404 error.
Example 1: /api/projects/Gould2/dataset
Example 2: /api/projects/Gould2/dataset?json=yes


/api/projects/projsym/strains

List the strains that were tested in the project projsym with some attributes for each.
Example 1: /api/projects/Gould2/strains
Example 2: /api/projects/UCLA1/strains
• Also available: datasets_strains.csv download file .


/api/projects/projsym/publications

Fetch the publications associated with the project projsym.
Example 1: /api/projects/Gould2/publications
Example 2: /api/projects/Beamer2/publications
• Also available:   datasets_pmids.csv download file


/api/projects/projsym/markers

Fetch the markers that have been associated with the project projsym.
(applies only to QTL Archive projects)
Example: /api/projects/Beamer2/markers


/api/investigators

Fetch a list of contributing investigators. The name parameter can be passed to filter on citation name eg. Smith JS (case insensitive).
Example 1: /api/investigators   (all)
Example 1a: /api/investigators?csv=yes   (all, in CSV format)
Example 2: /api/investigators?name=tarantino


  Phenotype measured data


/api/pheno/animalvals/measnum

Fetch numeric individual animal data for MPD strain survey phenotype measure(s) identified by measnum (an integer or comma-separated list of multiple integers).
Optional parameter: covariate .... the ID of another numeric measure involving the same animals
Example 1 (project Jaxpheno3, measureID 22826)   /api/pheno/animalvals/22826
Same as above but CSV result:   /api/pheno/animalvals/22826?csv=yes
Same as above but CSV for GxL:   /api/pheno/animalvals/45911?csv=yes&gxl_format1=yes
Example 2 (project Paigen1, measures 2908 and 2909)   /api/pheno/animalvals/2908,2909
Example 3 (measure 2909 with BW covariate 2905)   /api/pheno/animalvals/2909?covariate=2905
Example 4 (error example)   /api/pheno/animalvals/111
Example 5 (DO example)   /api/pheno/animalvals/47002
• Also available: the /api/projects/.../dataset endpoint (see above tab)
• Also available:   animaldatapoints.csv download file containing all numeric animal data points found in MPD.


/api/pheno/animalvals/series/measnum

Fetch numeric individual animal data for the measure series identified by measnum. For more about "measure series" see below (Metadata tab).
Example 1, Ackert1 BMD at 6mo, 12mo, 20mo   /api/pheno/animalvals/series/25011
Same as above but CSV result:   /api/pheno/animalvals/series/25011?csv=yes
Example 2, Gould2 jumping behavior, nicotine vs. control   /api/pheno/animalvals/series/47115


/api/pheno/shared_animals/measlist

Verify ("yes" or "no") that all measure IDs in measlist are for animal-granularity measures that could have some animals in common, based on known project animal sharing. If all measures are from the same project (and animal-granular) then "yes" is always returned. Use-case: to determine if it's OK to compute animal-granularity correlations based on animal_ids for a set of measureIDs from 2+ projects.
Example 1 (yes)   /api/pheno/shared_animals/24853,24855,24857,36304,36305
Example 2 (no)   /api/pheno/shared_animals/24853,2909


/api/pheno/lsmeans/selector

Get model-adjusted least-square strain means for phenotype measure(s). Model adjusted means are run on sex "f", "m" as well as "both". Not all MPD measures have adjusted means (for those that don't the unadjusted strain means are provided in the "unadj_means" element). The selector parameter can be a measure ID, a comma-separated list of two or more measure IDs, or a valid project symbol such as Vinyard1.
Example 1:   /api/pheno/lsmeans/2908,2909
Example 2:   /api/pheno/lsmeans/Vinyard1
Example 3:   /api/pheno/lsmeans/2909,2208 (2909 has adjusted, 2208 doesn't)
Example 4:   /api/pheno/lsmeans/2909
Example 5:   /api/pheno/lsmeans/2208
Same as above but CSV result:   /api/pheno/lsmeans/2208?csv=yes


/api/pheno/strainmeans/selector

Get unadjusted strain means for one or more MPD phenotype measures. The selector parameter can be one measure ID, a comma-separated list of two or more measure IDs, or a valid project symbol such as Vinyard1. Unadjusted strain means should be available for every strain survey measurement in MPD even if data were supplied with no individual animal data available. In the json result the "sex" for each strain mean element will be either "f" or "m".
Example 1:   /api/pheno/strainmeans/2908,2909
Example 2:   /api/pheno/strainmeans/Vinyard1
Same as above but CSV result:   /api/pheno/strainmeans/Vinyard1?csv=yes
• Also available:   strainmeans.csv download file


  Phenotype metadata, annotations


/api/pheno/measureinfo/selector

Get descriptions, units, and other metadata for one or more MPD measures.
selector is either:
• a project symbol eg. Tarantino1 .... list info for all measures in the project ... or...
• one or more measureIDs (measnums) eg. 2928 .... list info for these specific measure(s) ...or....
all .... list info for all MPD measures
Example 1: List info for the measure having measure ID 2908:   /api/pheno/measureinfo/2908
Example 2: List info for the measures 2908 and 2909:   /api/pheno/measureinfo/2908,2909
Example 3: List info for all the measures in project Albers1:   /api/pheno/measureinfo/Albers1
• Also available:   measurements.csv download file with metadata for all measures found in MPD.


/api/pheno/seriesinfo/measnum

Get descriptions, units, and other metadata for the measure series identified by measnum. A "measure series" is a set of 2 or more measures that are usually analyzed together, such as a timecourse series, dosage series, or a treated vs. control pair. To identify a measure series, use the measure ID of the first measure in the series (as shown in web app measure listings).
Example 1. Get info about measure series 25001:   /api/pheno/seriesinfo/25001
Example 2. Get info about measure series 110654:   /api/pheno/seriesinfo/110654


/api/pheno/measures_by_ontology/ont_term

The default use of this endpoint is to get measure IDs, descriptions, and other metadata for all measures that have been annotated to MP, VT, or MA ontology term ID ont_term or any of its DAG descendants. Payload includes additional info such as a list of all the involved ontology terms and descriptions. The following parameters are accepted:
this_term_only=yes .... work with the given term only, don't involve any DAG descendants
omit_baseline=yes .... omit measures that are 'baseline' or 'control' from the result; may be useful in eg. drug effect studies
collapse_series=yes .... any measure series will be represented as one pheno_measures row in the result
Example 1: /api/pheno/measures_by_ontology/VT:0010488
Example 2: /api/pheno/measures_by_ontology/VT:0010488?this_term_only=yes
Example 3: /api/pheno/measures_by_ontology/VT:0010488?omit_baseline=yes
Example 4: /api/pheno/measures_by_ontology/VT:0010488?collapse_series=yes
Example 5: /api/pheno/measures_by_ontology/VT:0010488?csv=yes
Example 6 (fail): /api/pheno/measures_by_ontology/VT:9898989
Example 7 (no measures mapped): /api/pheno/measures_by_ontology/MA:0000451
• Also available:   ontology_mappings.csv download file


  KOMP


/api/limsdata

Get a list of all JaxLIMS procedures (our names) for which we have captured data.
Example: /api/limsdata


/api/limsdata/procedure

Get the names and postgresql data types of all fields that are captured from JaxLIMS into MPD for a given procedure. Provides case identifiers (genotype_id, datedue, jr, sex, mouseid, etc.) as well as environment parameters with names like env_*.
Example 1: /api/limsdata/komp_bodycmp
Example 2: /api/limsdata/komp_bw
Example 3: /api/limsdata/komp_chem
Example 4: /api/limsdata/komp_ekg
Example 5: /api/limsdata/komp_oft


/api/limsdata/measures/procedure

Get a list of accessioned MPD measures that are available for a given procedure. Based on MPD's pheno_measures table. You can use all to list measures for all loaded KOMP procedures. Names of environment (env_*) parameters and standard identifier fields are not included.
Example 1: /api/limsdata/measures/komp_bodycmp
Example 2: /api/limsdata/measures/komp_bw
Example 3: /api/limsdata/measures/komp_chem
Example 4: /api/limsdata/measures/komp_shirpa
Example 5: /api/limsdata/measures/komp_oft
Example 6: /api/limsdata/measures/all


/api/limsdata/procedure/parameter(s)

/api/limsdata/any/measnum

Get the JaxLIMS individual animal data for the given procedure and parameter(s).
procedure is a short procedure name eg. komp_ekg   or   any
parameter(s) can be either:
  • all which will return all parameters associated with the procedure
  • one or more measure or parameter names (comma-separated if > one) associated with procedure
  • one or more measure IDs (comma-separated if > one and must all be from same procedure)
The following case identifiers are always included in the result: genotype_id, genotypedescription, jr, sex, mouseid, agedays, datedue, datecomplete, env_reviewaction. There are 3 top-level elements in the json result: animaldata, parameternames, and rowcount.
One or more of the following criteria parameters must be supplied, otherwise a "huge retrieval" error will result.
alltime=yes .... use alltime=yes to get all results regardless of datedue
genotype_id ... limit to this one genotype_id (integer)
startdate and enddate ... datedue within these YYYY-MM-DD dates (exclusive, must be supplied together)
jrnum ... limit to this one strain JR number (integer)
gene ... limit to this one gene symbol
You can also optionally specify:
maxrows ... limit the result to this many items ... handy for testing
newest_first=yes ... if yes sort on datedue newest first. Default is to sort on datedue oldest first.
wkomp_animal_attrs=yes ... if yes include komp_animal attributes such as env_exitreason
trait_colname ... specify as eg. value to have a consistent result fieldname for the phenotype value

Example 1: /api/limsdata/komp_ekg/all?startdate=2017-01-01&enddate=2017-01-31
Same as above but CSV result: /api/limsdata/komp_ekg/all?startdate=2017-01-01&enddate=2017-01-31&csv=yes
Example 2: /api/limsdata/any/100123?alltime=yes
Example 3: /api/limsdata/komp_chem/urea_bun?genotype_id=1855603
Example 4: /api/limsdata/komp_ekg/rr,pr,qt,env_dateofbirth?startdate=2017-01-01&enddate=2017-01-31
Example 5: /api/limsdata/komp_bw/body_weight?startdate=2016-07-01&enddate=2016-07-15
Example 6: /api/limsdata/komp_ekg/qrs?startdate=2016-07-01&enddate=2018-06-30&newest_first=yes&wkomp_animal_attrs=yes


/api/limsdata/komp_genotypes

Get info on strains / genotypes tested in KOMP. For available options see examples below:
Example 1: /api/limsdata/komp_genotypes?id=1855703
Example 2: /api/limsdata/komp_genotypes?gene=Trip13
Example 3: /api/limsdata/komp_genotypes?jr=18558
Example 4: /api/limsdata/komp_genotypes?desclike=Mbp
Example 5: /api/limsdata/komp_genotypes   (list all of them)


/api/limsdata/kompeff/measnums

Get the precomputed effect sizes for one or more KOMP measures by measure ID. If rankZ and adjusted pvalues are present they will be included on each row.
Example 1: /api/limsdata/kompeff/100123
Same as above but CSV result: /api/limsdata/kompeff/100123?csv=yes
Example 2: /api/limsdata/kompeff/100123,100233


/api/limsdata/kompeff_by_genotype/genotype_ids

Get the precomputed effect sizes for all loaded KOMP measures, for the requested genotype_ids (one or more genotype_ids, separated by comma if more than one).
Example 1: /api/limsdata/kompeff_by_genotype/1855603,1855803


  SNPs, genes


/api/snpdata

Retrieve rows from an MPD SNP dataset. Result is a CSV payload [more info] or else a JSON payload with error info. First CSV row is header with strains denoted as strain_name::strain_id. Results are truncated at 600K rows. Sanger4 retrievals are restricted to max 50 Mbp. The following 3 args are always required:
dataset=   name of a SNP dataset [List]
region=   a genomic region eg.   3:44-45   Abcd3   3:all   all   [More examples]
strains=   a comma-separated list of integer MPD strain IDs, or all to get all strains in dataset. To get the reference strain C57BL/6J in the leftmost result column, specify 7 as the first strain ID in the list.
With Sanger4 retrievals the optional arg indels=yes can also be given to include indels (normally not included).
Example 1: /api/snpdata?dataset=UCLA1&region=3:44-47&strains=all
Example 2: /api/snpdata?dataset=UCLA1&region=all&strains=7,8,1,4
Example 3: /api/snpdata?dataset=UNC-MMUGA2&region=7:all&strains=all
Example 3a: /api/snpdata?dataset=UNC-GMUGA1&region=19:all&strains=all
Example 4: /api/snpdata?dataset=Sanger4&region=3:121709000-121835200&strains=all&indels=yes
Example 5 (fail): /api/snpdata?dataset=UCLA1&region=flubba&strains=7,8,1,4
Example 6 (fail): /api/snpdata?dataset=Flubba2&region=Abcd2&strains=all
Example 7 (fail): /api/snpdata?dataset=UCLA1&region=Abcd2&strains=C57BL/6J,A/J


/api/geneinfo/sym

Get basepair coordinates and other attributes for a mouse gene / marker. Authority: MGI.
Example 1: /api/geneinfo/Abcd2
Example 2: /api/geneinfo/D10Mit104
Example 3 (fail): /api/geneinfo/Flubba


  Strains, nomenclature


/api/straininfo

See what info is available for a given mouse strain. Can be used to validate strain nomenclature. Supply either the target strain's name (ascii nomenclature) or stocknumber stocknum, or MGI ID mginum. Result includes a jaxinfo element (length=1 if strain found in our JaxStrain resource, length=0 otherwise), and an mpdinfo element (length=1 if strain found in MPD database, length=0 otherwise).
Example 1: /api/straininfo?name=DBA/2J
Example 2: /api/straininfo?stocknum=000664
Example 2a: /api/straininfo?stocknum=664
Example 3: /api/straininfo?mginum=MGI:2162761
Example 4: /api/straininfo?name=B6N(Cg)-Sipa1l1<tm1.1(KOMP)Vlcg>/J
Example 5: /api/straininfo?stocknum=025641   (found in MPD but not JaxStrain)
Example 6: /api/straininfo?stocknum=000522   (found in Jaxstrain but not MPD)
Examples of fail: /api/straininfo?name=flubba   /api/straininfo?stocknum=flubba   /api/straininfo?mginum=flubba
• Also available:   straininfo.csv download file with all strains referenced in MPD.


  Generate TCI animal uuids


/api/generate_uuids

Generate one or more of the TCI JMUS 36-char unique identifiers (uuids). n_ids (default=1) can optionally be given to specify how many to generate.
Example 1: /api/generate_uuids?n_ids=10