{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 5 - Field-Specific Helper Functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mdf_forge.forge import Forge"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "mdf = Forge()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Field-Specific Query Builders"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_source_names\n",
    "`match_source_names()` matches values against the `\"mdf.source_name\"` field. It is equivalent to chaining `match_field(\"mdf.source_name\", value)` for each value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_source_names(\"oqmd\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'crystal_structure': {'number_of_atoms': 4,\n",
       "  'space_group_number': 225,\n",
       "  'volume': 66.7282},\n",
       " 'dft': {'converged': True,\n",
       "  'cutoff_energy': 247.5,\n",
       "  'exchange_correlation_functional': 'PBE'},\n",
       " 'files': [{'data_type': 'ASCII text, with very long lines, with no line terminators',\n",
       "   'filename': '670930.json',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/oqmd_v13/670930.json',\n",
       "   'length': 11138,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': 'a87051ace78249013ba17d331586f2470868e5e573e0bce347d22205f2a224a25772690ca8c7b78dce1743c98a2d585a09d74a062bc05bd8331de77d4c40d54d',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/oqmd_v13/670930.json'}],\n",
       " 'material': {'composition': 'Be2Lu1Sn1', 'elements': ['Be', 'Lu', 'Sn']},\n",
       " 'mdf': {'ingest_date': '2018-11-09T19:44:43.687681Z',\n",
       "  'mdf_id': '5be5e3af2ef388650efd6708',\n",
       "  'parent_id': '5be5e3ab2ef388650efd6704',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 4,\n",
       "  'source_id': 'oqmd_v13',\n",
       "  'source_name': 'oqmd',\n",
       "  'version': 13},\n",
       " 'oqmd': {'band_gap': {'units': 'eV', 'value': 0.0},\n",
       "  'configuration': 'fine_relax',\n",
       "  'magnetic_moment': {'units': 'bohr/atom'},\n",
       "  'total_energy': {'units': 'eV/atom', 'value': -3.7894355225},\n",
       "  'volume_pa': {'units': 'angstrom^3/atom', 'value': 16.6821}}}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search(limit=10)\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_records\n",
    "`match_records()` matches one or more specific records from a specific dataset. It matches the `source_name` against the `\"mdf.source_name\"` field and the `scroll_id` values against the `mdf.scroll_id` field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_records(\"cip\", [1003, 1006])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'cip': {'bv': '300.9',\n",
       "  'energy': '-2.67',\n",
       "  'forcefield': 'ffield.CuOCH.comb3',\n",
       "  'gv': '103.8',\n",
       "  'mpid': 'mp-703914',\n",
       "  'totenergy': '-1538.4116'},\n",
       " 'files': [{'data_type': 'ASCII text, with very long lines, with no line terminators',\n",
       "   'filename': 'classical_interatomic_potentials.json',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json',\n",
       "   'length': 1841203,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': '96635ee0c15d1d0187b18805653a02b1a6dfa5648db82153467045de18adcc08c753e2897d2b48a78a2167a442219e9aeff6b1103732c2158facac8fa4911b33',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json'}],\n",
       " 'material': {'composition': 'Cu192 O384', 'elements': ['Cu', 'O']},\n",
       " 'mdf': {'ingest_date': '2018-10-29T17:47:57.468388Z',\n",
       "  'mdf_id': '5bd747cf2ef3880b0f2139bf',\n",
       "  'parent_id': '5bd747cd2ef3880b0f2135d1',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 1006,\n",
       "  'source_id': 'cip_v1',\n",
       "  'source_name': 'cip',\n",
       "  'version': 1}}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search()\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_elements\n",
    "`match_elements()` matches values against the `\"materials.elements\"` field. It is equivalent to chaining `match_field(\"materials.elements\", value)` for each value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_elements([\"Al\", \"Cu\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'cip': {'bv': '121.8',\n",
       "  'energy': '-3.63',\n",
       "  'forcefield': 'AlCu.eam.alloy',\n",
       "  'gv': '43.5',\n",
       "  'mpid': 'mp-12777',\n",
       "  'totenergy': '-464.16852'},\n",
       " 'files': [{'data_type': 'ASCII text, with very long lines, with no line terminators',\n",
       "   'filename': 'classical_interatomic_potentials.json',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json',\n",
       "   'length': 1841203,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': '96635ee0c15d1d0187b18805653a02b1a6dfa5648db82153467045de18adcc08c753e2897d2b48a78a2167a442219e9aeff6b1103732c2158facac8fa4911b33',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json'}],\n",
       " 'material': {'composition': 'Al32 Cu96', 'elements': ['Al', 'Cu']},\n",
       " 'mdf': {'ingest_date': '2018-10-29T17:47:57.468388Z',\n",
       "  'mdf_id': '5bd747d32ef3880b0f2142a4',\n",
       "  'parent_id': '5bd747cd2ef3880b0f2135d1',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 3283,\n",
       "  'source_id': 'cip_v1',\n",
       "  'source_name': 'cip',\n",
       "  'version': 1}}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search(limit=10)\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_resource_types\n",
    "`match_resource_types()` matches values against the `\"mdf.resource_types\"` field. It is equivalent to chaining `match_field(\"mdf.resource_types\", value)` for each value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_resource_types(\"record\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'cip': {'bv': '30535.3',\n",
       "  'energy': '-0.37',\n",
       "  'forcefield': 'Fe-P.eam.fs',\n",
       "  'gv': '-1878841.7',\n",
       "  'mpid': 'mp-130',\n",
       "  'totenergy': '-17.804778'},\n",
       " 'files': [{'data_type': 'ASCII text, with very long lines, with no line terminators',\n",
       "   'filename': 'classical_interatomic_potentials.json',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json',\n",
       "   'length': 1841203,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': '96635ee0c15d1d0187b18805653a02b1a6dfa5648db82153467045de18adcc08c753e2897d2b48a78a2167a442219e9aeff6b1103732c2158facac8fa4911b33',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/cip_v1/classical_interatomic_potentials.json'}],\n",
       " 'material': {'composition': 'P48', 'elements': ['P']},\n",
       " 'mdf': {'ingest_date': '2018-10-29T17:47:57.468388Z',\n",
       "  'mdf_id': '5bd747cd2ef3880b0f21369b',\n",
       "  'parent_id': '5bd747cd2ef3880b0f2135d1',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 202,\n",
       "  'source_id': 'cip_v1',\n",
       "  'source_name': 'cip',\n",
       "  'version': 1}}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search(limit=10)\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_titles\n",
    "`match_titles()` matches values against the `\"dc.titles.title\"` field. It is equivalent to chaining `match_field(\"dc.titles.title\", value)` for each value.\n",
    "\n",
    "Remember, values with special characters (like spaces) need to be wrapped in double quotes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_titles('\"The Open Quantum Materials Database\"')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/oqmd_v13/',\n",
       "   'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/oqmd_v13/'},\n",
       "  'dc': {'creators': [{'affiliations': ['Northwestern University'],\n",
       "     'creatorName': 'Wolverton, Chris',\n",
       "     'familyName': 'Wolverton',\n",
       "     'givenName': 'Chris'},\n",
       "    {'affiliations': ['Northwestern University'],\n",
       "     'creatorName': 'Kirklin, Scott',\n",
       "     'familyName': 'Kirklin',\n",
       "     'givenName': 'Scott'},\n",
       "    {'affiliations': ['Northwestern University'],\n",
       "     'creatorName': 'Hegde, Vinay',\n",
       "     'familyName': 'Hegde',\n",
       "     'givenName': 'Vinay'},\n",
       "    {'affiliations': ['Northwestern University'],\n",
       "     'creatorName': 'Ward, Logan',\n",
       "     'familyName': 'Ward',\n",
       "     'givenName': 'Logan'}],\n",
       "   'descriptions': [{'description': 'The OQMD is a database of DFT-calculated thermodynamic and structural properties.',\n",
       "     'descriptionType': 'Other'}],\n",
       "   'publicationYear': '2013',\n",
       "   'publisher': 'Materials Data Facility',\n",
       "   'relatedIdentifiers': [{'relatedIdentifier': 'http://dx.doi.org/10.1007/s11837-013-0755-4',\n",
       "     'relatedIdentifierType': 'DOI',\n",
       "     'relationType': 'IsPartOf'},\n",
       "    {'relatedIdentifier': 'http://dx.doi.org/10.1038/npjcompumats.2015.10',\n",
       "     'relatedIdentifierType': 'DOI',\n",
       "     'relationType': 'IsPartOf'}],\n",
       "   'resourceType': {'resourceType': 'Dataset',\n",
       "    'resourceTypeGeneral': 'Dataset'},\n",
       "   'titles': [{'title': 'The Open Quantum Materials Database'}]},\n",
       "  'mdf': {'ingest_date': '2018-11-09T19:44:43.687681Z',\n",
       "   'mdf_id': '5be5e3ab2ef388650efd6704',\n",
       "   'resource_type': 'dataset',\n",
       "   'scroll_id': 0,\n",
       "   'source_id': 'oqmd_v13',\n",
       "   'source_name': 'oqmd',\n",
       "   'version': 13},\n",
       "  'oqmd': {'__custom.band_gap_desc': 'Band gap energy (eV)',\n",
       "   '__custom.configuration_desc': 'OQMD configuration profile used in calculation',\n",
       "   '__custom.delta_e_desc': 'Formation enthalpy (eV/atom)',\n",
       "   '__custom.magnetic_moment_desc': 'Magnetic moment (Bohr/atom)',\n",
       "   '__custom.stability_desc': 'Distance from formation enthalpy convex hull. Unstable compounds have positive values (eV/atom)',\n",
       "   '__custom.total_energy_desc': 'Total enregy (eV/atom)',\n",
       "   '__custom.volume_pa_desc': 'Volume per atom (Angstom^3/atom)'},\n",
       "  'services': {'mdf_search': 'This dataset was ingested to MDF Search.'}}]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.search()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_years\n",
    "`match_years()` matches values against the `\"dc.publicationYear\"` field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_years([\"2015\", 2010])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/mdr_item_571_v1/',\n",
       "  'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/mdr_item_571_v1/'},\n",
       " 'dc': {'alternateIdentifiers': [{'alternateIdentifier': 'http://hdl.handle.net/11256/272',\n",
       "    'alternateIdentifierType': 'Handle'},\n",
       "   {'alternateIdentifier': '571',\n",
       "    'alternateIdentifierType': 'NIST DSpace ID'}],\n",
       "  'creators': [{'affiliations': ['University of Maryland'],\n",
       "    'creatorName': 'Joost, William J.',\n",
       "    'familyName': 'Joost',\n",
       "    'givenName': 'William J.'},\n",
       "   {'affiliations': ['University of Maryland'],\n",
       "    'creatorName': 'Ankem, Sreeramamurthy',\n",
       "    'familyName': 'Ankem',\n",
       "    'givenName': 'Sreeramamurthy'},\n",
       "   {'affiliations': ['University of Maryland'],\n",
       "    'creatorName': 'Kuklja, Maija M.',\n",
       "    'familyName': 'Kuklja',\n",
       "    'givenName': 'Maija M.'}],\n",
       "  'publicationYear': '2015',\n",
       "  'publisher': 'NIST Materials Data Repository',\n",
       "  'resourceType': {'resourceType': 'Dataset',\n",
       "   'resourceTypeGeneral': 'Dataset'},\n",
       "  'rightsList': [{'rights': 'Attribution 3.0 United States',\n",
       "    'rightsURI': 'http://creativecommons.org/licenses/by/3.0/us/'}],\n",
       "  'subjects': [{'subject': 'Titanium'},\n",
       "   {'subject': ' Oxygen'},\n",
       "   {'subject': ' Diffusion'},\n",
       "   {'subject': ' Twin'}],\n",
       "  'titles': [{'title': 'Interaction Between Oxygen Interstitials and Deformation Twins in alpha-Titanium'}]},\n",
       " 'mdf': {'ingest_date': '2018-11-15T18:46:11.094146Z',\n",
       "  'mdf_id': '5bedbef32ef388392f953c09',\n",
       "  'repositories': ['National Institute of Standards and Technology',\n",
       "   'U.S. Department of Commerce',\n",
       "   'DOC',\n",
       "   'MDR',\n",
       "   'NIST',\n",
       "   'NIST Materials Data Repository',\n",
       "   'NIST MDR'],\n",
       "  'resource_type': 'dataset',\n",
       "  'scroll_id': 0,\n",
       "  'source_id': 'mdr_item_571_v1',\n",
       "  'source_name': 'mdr_item_571',\n",
       "  'version': 1},\n",
       " 'services': {'citrine': 'https://citrination.com/datasets/168832/',\n",
       "  'mdf_search': 'This dataset was ingested to MDF Search.',\n",
       "  'mrr': 'This dataset was registered with the MRR.'}}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search(limit=10)\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify a range of years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_years(start=2014, stop=2016, inclusive=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/khazana_vasp_v4/',\n",
       "  'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/khazana_vasp_v4/'},\n",
       " 'dc': {'contributors': [{'affiliations': ['University of Connecticut'],\n",
       "    'contributorName': 'Ramprasad, Rampi',\n",
       "    'contributorType': 'ContactPerson',\n",
       "    'familyName': 'Ramprasad',\n",
       "    'givenName': 'Rampi'}],\n",
       "  'creators': [{'affiliations': ['University of Connecticut'],\n",
       "    'creatorName': 'Ramprasad, Rampi'}],\n",
       "  'dates': [{'date': '2017-08-04T19:25:05.718973Z', 'dateType': 'Collected'}],\n",
       "  'descriptions': [{'description': 'A computational materials knowledgebase',\n",
       "    'descriptionType': 'Other'}],\n",
       "  'publicationYear': '2016',\n",
       "  'publisher': 'MDF (placeholder)',\n",
       "  'resourceType': {'resourceType': 'JSON', 'resourceTypeGeneral': 'Dataset'},\n",
       "  'subjects': [{'subject': 'DFT'}, {'subject': 'VASP'}],\n",
       "  'titles': [{'title': 'Khazana (VASP)'}]},\n",
       " 'mdf': {'ingest_date': '2018-11-05T21:42:40.557765Z',\n",
       "  'mdf_id': '5be0b9502ef388136874efdf',\n",
       "  'resource_type': 'dataset',\n",
       "  'scroll_id': 0,\n",
       "  'source_id': 'khazana_vasp_v4',\n",
       "  'source_name': 'khazana_vasp',\n",
       "  'version': 4},\n",
       " 'services': {'mdf_search': 'This dataset was ingested to MDF Search.'}}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search(limit=10)\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_organizations\n",
    "`match_organizations()` matches values against the `\"mdf.organizations\"` field. It is equivalent to chaining `match_field(\"mdf.organizations\", value)` for each value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Organizations are currently migrating from the old \"repositories\" field, so some may not be set up correctly just yet.\n",
    "# mdf.match_organizations([\"NIST\", \"DOE\"], match_all=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# res = mdf.search(limit=10)\n",
    "# res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### match_dois\n",
    "`match_dois()` searches for datasets with one of the given Digital Object Identifiers. It is equivalent to chaining `match_field(\"dc.identifier.identifier\", doi)` for each doi."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<mdf_forge.forge.Forge at 0x7f70957c4240>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mdf.match_dois(\"https://dx.doi.org/10.13011/M3B36G\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/si_ti_oxidation_v1/',\n",
       "  'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/si_ti_oxidation_v1/'},\n",
       " 'dc': {'creators': [{'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Chou, Kathleen',\n",
       "    'familyName': 'Chou',\n",
       "    'givenName': 'Kathleen'},\n",
       "   {'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Chu, Peng-Wei',\n",
       "    'familyName': 'Chu',\n",
       "    'givenName': 'Peng-Wei'},\n",
       "   {'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Marquis, Emmanuelle',\n",
       "    'familyName': 'Marquis',\n",
       "    'givenName': 'Emmanuelle'}],\n",
       "  'descriptions': [{'description': \"This dataset compiles images and data from oxidation studies of pure titanium coated with a pure Si coating at 800 degrees C that supplement submitted manuscript 'Early oxidation behavior of Si-coated titanium'. Please note, the meta-data provided may be updated over time. We reserve the right to update this data without notification. If you would like to be notified of changes, please email Kathleen Chou at kachou@umich.edu.\",\n",
       "    'descriptionType': 'Other'}],\n",
       "  'identifier': {'identifier': 'https://dx.doi.org/10.13011/M3B36G',\n",
       "   'identifierType': 'DOI'},\n",
       "  'publicationYear': '2018',\n",
       "  'publisher': 'Materials Commons',\n",
       "  'resourceType': {'resourceType': 'Dataset',\n",
       "   'resourceTypeGeneral': 'Dataset'},\n",
       "  'subjects': [{'subject': 'Titanium'},\n",
       "   {'subject': 'Oxidation'},\n",
       "   {'subject': 'Silicon coatings'},\n",
       "   {'subject': 'Transmission electron microscopy'}],\n",
       "  'titles': [{'title': 'Early oxidation behavior of Si-coated titanium'}]},\n",
       " 'mdf': {'ingest_date': '2018-10-30T21:44:27.860096Z',\n",
       "  'mdf_id': '5bd8d0bb2ef38836a62135d1',\n",
       "  'repositories': ['MCPub',\n",
       "   'DOE',\n",
       "   'Department of Energy Software Innovation Center for Integrated Multi-Scale Modeling of Structural Metals',\n",
       "   'U.S. Department of Energy',\n",
       "   'Materials Commons',\n",
       "   'Center for Predictive Integrated Structural Materials Science',\n",
       "   'PRISMS'],\n",
       "  'resource_type': 'dataset',\n",
       "  'scroll_id': 0,\n",
       "  'source_id': 'si_ti_oxidation_v1',\n",
       "  'source_name': 'si_ti_oxidation',\n",
       "  'version': 1},\n",
       " 'services': {'mdf_search': 'This dataset was ingested to MDF Search.'}}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search()\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Premade Searches"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### search_by_elements\n",
    "`search_by_elements()` executes a search for the provided elements in the provided sources and returns the results. Note that calling `search()` is not required, as this helper function already performs the search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'crystal_structure': {'cross_reference': {'icsd': 57668},\n",
       "  'number_of_atoms': 5,\n",
       "  'space_group_number': 164,\n",
       "  'volume': 72.5641},\n",
       " 'dft': {'converged': True,\n",
       "  'cutoff_energy': 520.0,\n",
       "  'exchange_correlation_functional': 'PBE'},\n",
       " 'files': [{'data_type': 'ASCII text, with very long lines, with no line terminators',\n",
       "   'filename': '19430.json',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/oqmd_v13/19430.json',\n",
       "   'length': 11181,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': '8015dc8ce744634f5e9be41ddd37379c444ef17f1aaeae57bfbab544125fa787d1f2ed937ba0e9b7be535f88dd0155e05de6541057ab2eaab6c383e85eb9495a',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/oqmd_v13/19430.json'}],\n",
       " 'material': {'composition': 'Al3Cu2', 'elements': ['Al', 'Cu']},\n",
       " 'mdf': {'ingest_date': '2018-11-09T19:44:43.687681Z',\n",
       "  'mdf_id': '5be5e7632ef388650e02b0e4',\n",
       "  'parent_id': '5be5e3ab2ef388650efd6704',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 346591,\n",
       "  'source_id': 'oqmd_v13',\n",
       "  'source_name': 'oqmd',\n",
       "  'version': 13},\n",
       " 'oqmd': {'band_gap': {'units': 'eV', 'value': 0.0},\n",
       "  'magnetic_moment': {'units': 'bohr/atom'},\n",
       "  'total_energy': {'units': 'eV/atom', 'value': -3.885221738},\n",
       "  'volume_pa': {'units': 'angstrom^3/atom', 'value': 14.5128}}}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search_by_elements([\"Al\", \"Cu\"], source_names=[\"oqmd\"])\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### search_by_titles\n",
    "`search_by_titles()` executes a search for the provided titles and returns the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/ab_initio_solute_database_v1-2/',\n",
       "  'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/ab_initio_solute_database_v1-2/'},\n",
       " 'dc': {'contributors': [{'affiliations': ['University of Wisconsin-Madison'],\n",
       "    'contributorName': 'Morgan, Dane',\n",
       "    'contributorType': 'ContactPerson',\n",
       "    'familyName': 'Morgan',\n",
       "    'givenName': 'Dane'}],\n",
       "  'creators': [{'affiliations': ['University of Wisconsin-Madison'],\n",
       "    'creatorName': 'Morgan, Dane',\n",
       "    'familyName': 'Morgan',\n",
       "    'givenName': 'Dane'},\n",
       "   {'affiliations': ['University of Wisconsin-Madison'],\n",
       "    'creatorName': 'Mayeshiba, Tam',\n",
       "    'familyName': 'Mayeshiba',\n",
       "    'givenName': 'Tam'},\n",
       "   {'affiliations': ['University of Wisconsin-Madison'],\n",
       "    'creatorName': 'Henry, Wu',\n",
       "    'familyName': 'Henry',\n",
       "    'givenName': 'Wu'}],\n",
       "  'dates': [{'date': '2017-08-07T16:07:32.938812Z', 'dateType': 'Collected'}],\n",
       "  'descriptions': [{'description': 'We demonstrate automated generation of diffusion databases from high-throughput density functional theory (DFT) calculations. A total of more than 230 dilute solute diffusion systems in Mg, Al, Cu, Ni, Pd, and Pt host lattices have been determined using multi-frequency diffusion models. We apply a correction method for solute diffusion in alloys using experimental and simulated values of host self-diffusivity.',\n",
       "    'descriptionType': 'Other'}],\n",
       "  'publicationYear': '2016',\n",
       "  'publisher': 'MDF (placeholder)',\n",
       "  'relatedIdentifiers': [{'relatedIdentifier': 'http://dx.doi.org/10.1038/sdata.2016.54',\n",
       "    'relatedIdentifierType': 'DOI',\n",
       "    'relationType': 'IsPartOf'}],\n",
       "  'resourceType': {'resourceType': 'JSON', 'resourceTypeGeneral': 'Dataset'},\n",
       "  'subjects': [{'subject': 'dilute'},\n",
       "   {'subject': 'solute'},\n",
       "   {'subject': 'DFT'},\n",
       "   {'subject': 'diffusion'},\n",
       "   {'subject': 'dataset'}],\n",
       "  'titles': [{'title': 'High-throughput Ab-initio Dilute Solute Diffusion Database'}]},\n",
       " 'mdf': {'ingest_date': '2018-11-24T08:12:11.852893Z',\n",
       "  'mdf_id': '5bf907db2ef3885ee1191ae0',\n",
       "  'resource_type': 'dataset',\n",
       "  'scroll_id': 0,\n",
       "  'source_id': 'ab_initio_solute_database_v1-2',\n",
       "  'source_name': 'ab_initio_solute_database',\n",
       "  'version': 1},\n",
       " 'services': {'mdf_search': 'This dataset was ingested to MDF Search.'}}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search_by_titles(['\"High-throughput Ab-initio Dilute Solute Diffusion Database\"'])\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### search_by_dois\n",
    "`search_by_dois()` executes a search for the given Digital Object Identifiers and returns the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'data': {'endpoint_path': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/si_ti_oxidation_v1/',\n",
       "  'link': 'https://www.globus.org/app/transfer?origin_id=e38ee745-6d04-11e5-ba46-22000b92c6ec&origin_path=/MDF/mdf_connect/prod/data/si_ti_oxidation_v1/'},\n",
       " 'dc': {'creators': [{'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Chou, Kathleen',\n",
       "    'familyName': 'Chou',\n",
       "    'givenName': 'Kathleen'},\n",
       "   {'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Chu, Peng-Wei',\n",
       "    'familyName': 'Chu',\n",
       "    'givenName': 'Peng-Wei'},\n",
       "   {'affiliations': ['University of Michigan'],\n",
       "    'creatorName': 'Marquis, Emmanuelle',\n",
       "    'familyName': 'Marquis',\n",
       "    'givenName': 'Emmanuelle'}],\n",
       "  'descriptions': [{'description': \"This dataset compiles images and data from oxidation studies of pure titanium coated with a pure Si coating at 800 degrees C that supplement submitted manuscript 'Early oxidation behavior of Si-coated titanium'. Please note, the meta-data provided may be updated over time. We reserve the right to update this data without notification. If you would like to be notified of changes, please email Kathleen Chou at kachou@umich.edu.\",\n",
       "    'descriptionType': 'Other'}],\n",
       "  'identifier': {'identifier': 'https://dx.doi.org/10.13011/M3B36G',\n",
       "   'identifierType': 'DOI'},\n",
       "  'publicationYear': '2018',\n",
       "  'publisher': 'Materials Commons',\n",
       "  'resourceType': {'resourceType': 'Dataset',\n",
       "   'resourceTypeGeneral': 'Dataset'},\n",
       "  'subjects': [{'subject': 'Titanium'},\n",
       "   {'subject': 'Oxidation'},\n",
       "   {'subject': 'Silicon coatings'},\n",
       "   {'subject': 'Transmission electron microscopy'}],\n",
       "  'titles': [{'title': 'Early oxidation behavior of Si-coated titanium'}]},\n",
       " 'mdf': {'ingest_date': '2018-10-30T21:44:27.860096Z',\n",
       "  'mdf_id': '5bd8d0bb2ef38836a62135d1',\n",
       "  'repositories': ['MCPub',\n",
       "   'DOE',\n",
       "   'Department of Energy Software Innovation Center for Integrated Multi-Scale Modeling of Structural Metals',\n",
       "   'U.S. Department of Energy',\n",
       "   'Materials Commons',\n",
       "   'Center for Predictive Integrated Structural Materials Science',\n",
       "   'PRISMS'],\n",
       "  'resource_type': 'dataset',\n",
       "  'scroll_id': 0,\n",
       "  'source_id': 'si_ti_oxidation_v1',\n",
       "  'source_name': 'si_ti_oxidation',\n",
       "  'version': 1},\n",
       " 'services': {'mdf_search': 'This dataset was ingested to MDF Search.'}}"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.search_by_dois(\"https://dx.doi.org/10.13011/M3B36G\")\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### aggregate_sources\n",
    "`aggregate_source_names()` fetches and returns all the records for a provided `\"mdf.source_name\"` value. Calling `search()` or `aggregate()` is not required, as this helper function does that for you. Please note that it is not possible to use the `limit` argument with this helper function, so you may get back a large number of results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'crystal_structure': {'number_of_atoms': 131.0,\n",
       "  'space_group_number': 1,\n",
       "  'stoichiometry': 'A60B71',\n",
       "  'volume': 8000.0},\n",
       " 'files': [{'data_type': 'ASCII text',\n",
       "   'filename': 'ge.cell',\n",
       "   'globus': 'globus://e38ee745-6d04-11e5-ba46-22000b92c6ec/MDF/mdf_connect/prod/data/ge_nanoparticles_v1/CASTEP_DFPT/Ge71H60/50GPa/ge.cell',\n",
       "   'length': 5686,\n",
       "   'mime_type': 'text/plain',\n",
       "   'sha512': '979c4f3b9cc84424d174f5f3faa5bc9c977f526b7f29c52bc99f2e5c2eeb80e98accdecd37b905b84061310f3fd810c93b756e4aaa80f3bd6c30bdf3389b5a3f',\n",
       "   'url': 'https://e38ee745-6d04-11e5-ba46-22000b92c6ec.e.globus.org/MDF/mdf_connect/prod/data/ge_nanoparticles_v1/CASTEP_DFPT/Ge71H60/50GPa/ge.cell'}],\n",
       " 'material': {'composition': 'Ge71H60', 'elements': ['Ge', 'H']},\n",
       " 'mdf': {'ingest_date': '2018-11-06T17:25:23.949096Z',\n",
       "  'mdf_id': '5be1ce832ef388345774efe1',\n",
       "  'parent_id': '5be1ce832ef388345774efdf',\n",
       "  'resource_type': 'record',\n",
       "  'scroll_id': 2,\n",
       "  'source_id': 'ge_nanoparticles_v1',\n",
       "  'source_name': 'ge_nanoparticles',\n",
       "  'version': 1}}"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = mdf.aggregate_sources(\"ge_nanoparticles\")\n",
    "res[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}