-
Notifications
You must be signed in to change notification settings - Fork 185
/
matminer.data_retrieval.html
443 lines (414 loc) · 28.1 KB
/
matminer.data_retrieval.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>matminer.data_retrieval package — matminer 0.7.6 documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link href='https://fonts.googleapis.com/css?family=Lato:400,700' rel='stylesheet' type='text/css'>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.7.6 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">matminer.data_retrieval package</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="matminer-data-retrieval-package">
<h1>matminer.data_retrieval package<a class="headerlink" href="#matminer-data-retrieval-package" title="Permalink to this headline">¶</a></h1>
<div class="section" id="subpackages">
<h2>Subpackages<a class="headerlink" href="#subpackages" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="matminer.data_retrieval.tests.html">matminer.data_retrieval.tests package</a><ul>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#submodules">Submodules</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#module-matminer.data_retrieval.tests.base">matminer.data_retrieval.tests.base module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#matminer-data-retrieval-tests-test-retrieve-aflow-module">matminer.data_retrieval.tests.test_retrieve_AFLOW module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#matminer-data-retrieval-tests-test-retrieve-citrine-module">matminer.data_retrieval.tests.test_retrieve_Citrine module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#matminer-data-retrieval-tests-test-retrieve-mdf-module">matminer.data_retrieval.tests.test_retrieve_MDF module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#module-matminer.data_retrieval.tests.test_retrieve_MP">matminer.data_retrieval.tests.test_retrieve_MP module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#matminer-data-retrieval-tests-test-retrieve-mpds-module">matminer.data_retrieval.tests.test_retrieve_MPDS module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#module-matminer.data_retrieval.tests.test_retrieve_MongoDB">matminer.data_retrieval.tests.test_retrieve_MongoDB module</a></li>
<li class="toctree-l2"><a class="reference internal" href="matminer.data_retrieval.tests.html#module-matminer.data_retrieval.tests">Module contents</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="section" id="submodules">
<h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="matminer-data-retrieval-retrieve-aflow-module">
<h2>matminer.data_retrieval.retrieve_AFLOW module<a class="headerlink" href="#matminer-data-retrieval-retrieve-aflow-module" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="matminer-data-retrieval-retrieve-citrine-module">
<h2>matminer.data_retrieval.retrieve_Citrine module<a class="headerlink" href="#matminer-data-retrieval-retrieve-citrine-module" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="matminer-data-retrieval-retrieve-mdf-module">
<h2>matminer.data_retrieval.retrieve_MDF module<a class="headerlink" href="#matminer-data-retrieval-retrieve-mdf-module" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-matminer.data_retrieval.retrieve_MP">
<span id="matminer-data-retrieval-retrieve-mp-module"></span><h2>matminer.data_retrieval.retrieve_MP module<a class="headerlink" href="#module-matminer.data_retrieval.retrieve_MP" title="Permalink to this headline">¶</a></h2>
<dl class="py class">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval">
<em class="property">class </em><code class="sig-prename descclassname">matminer.data_retrieval.retrieve_MP.</code><code class="sig-name descname">MPDataRetrieval</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">api_key</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval" title="matminer.data_retrieval.retrieve_base.BaseDataRetrieval"><code class="xref py py-class docutils literal notranslate"><span class="pre">matminer.data_retrieval.retrieve_base.BaseDataRetrieval</span></code></a></p>
<p>Retrieves data from the Materials Project database.</p>
<p>If you use this data retrieval class, please additionally cite:</p>
<p>Ong, S.P., Cholia, S., Jain, A., Brafman, M., Gunter, D., Ceder, G.,
Persson, K.A., 2015. The Materials Application Programming Interface
(API): A simple, flexible and efficient API for materials data based on
REpresentational State Transfer (REST) principles. Computational
Materials Science 97, 209–215.
<a class="reference external" href="https://doi.org/10.1016/j.commatsci.2014.10.037">https://doi.org/10.1016/j.commatsci.2014.10.037</a></p>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">api_key</span><span class="o">=</span><span class="default_value">None</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.__init__" title="Permalink to this definition">¶</a></dt>
<dd><dl class="simple">
<dt>Args:</dt><dd><dl class="simple">
<dt>api_key: (str) Your Materials Project API key, or None if you’ve</dt><dd><p>set up your pymatgen config.</p>
</dd>
</dl>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.api_link">
<code class="sig-name descname">api_link</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.api_link" title="Permalink to this definition">¶</a></dt>
<dd><p>The link to comprehensive API documentation or data source.</p>
<dl class="simple">
<dt>Returns:</dt><dd><p>(str): A link to the API documentation for this DataRetrieval class.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.citations">
<code class="sig-name descname">citations</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.citations" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve a list of formatted strings of bibtex citations which
should be cited when using a data retrieval method.</p>
<dl class="simple">
<dt>Returns:</dt><dd><p>([str]): Bibtext formatted entries</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.get_data">
<code class="sig-name descname">get_data</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">criteria</span></em>, <em class="sig-param"><span class="n">properties</span></em>, <em class="sig-param"><span class="n">mp_decode</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="n">index_mpid</span><span class="o">=</span><span class="default_value">True</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.get_data" title="Permalink to this definition">¶</a></dt>
<dd><dl class="simple">
<dt>Args:</dt><dd><dl class="simple">
<dt>criteria: (str/dict) see MPRester.query() for a description of this</dt><dd><p>parameter. String examples: “mp-1234”, “Fe2O3”, “Li-Fe-O’,
“*2O3”. Dict example: {“band_gap”: {“$gt”: 1}}</p>
</dd>
<dt>properties: (list) see MPRester.query() for a description of this</dt><dd><p>parameter. Example: [“formula”, “formation_energy_per_atom”]</p>
</dd>
<dt>mp_decode: (bool) see MPRester.query() for a description of this</dt><dd><p>parameter. Whether to decode to a Pymatgen object where
possible.</p>
</dd>
<dt>index_mpid: (bool) Whether to set the materials_id as the dataframe</dt><dd><p>index.</p>
</dd>
</dl>
</dd>
<dt>Returns ([dict]):</dt><dd><p>a list of jsons that match the criteria and contain properties</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.get_dataframe">
<code class="sig-name descname">get_dataframe</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">criteria</span></em>, <em class="sig-param"><span class="n">properties</span></em>, <em class="sig-param"><span class="n">index_mpid</span><span class="o">=</span><span class="default_value">True</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.get_dataframe" title="Permalink to this definition">¶</a></dt>
<dd><p>Gets data from MP in a dataframe format. See api_link for more details.</p>
<dl>
<dt>Args:</dt><dd><p>criteria (dict): the same as in get_data
properties ([str]): the same properties supported as in get_data</p>
<blockquote>
<div><p>plus: “structure”, “initial_structure”, “final_structure”,
“bandstructure” (line mode), “bandstructure_uniform”,
“phonon_bandstructure”, “phonon_ddb”, “phonon_bandstructure”,
“phonon_dos”. Note that for a long list of compounds, it may
take a long time to retrieve some of these objects.</p>
</div></blockquote>
<p>index_mpid (bool): the same as in get_data
kwargs (dict): the same keyword arguments as in get_data</p>
</dd>
</dl>
<p>Returns (pandas.Dataframe):</p>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MP.MPDataRetrieval.try_get_prop_by_material_id">
<code class="sig-name descname">try_get_prop_by_material_id</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">prop</span></em>, <em class="sig-param"><span class="n">material_id_list</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MP.MPDataRetrieval.try_get_prop_by_material_id" title="Permalink to this definition">¶</a></dt>
<dd><p>Call the relevant get_prop_by_material_id. “prop” is a property such
as bandstructure that is not readily available in supported properties
of the get_data function but via the get_bandstructure_by_material_id
method for example.</p>
<dl>
<dt>Args:</dt><dd><dl class="simple">
<dt>prop (str): the name of the property. Options are:</dt><dd><p>“bandstructure”, “dos”, “phonon_dos”, “phonon_bandstructure”,
“phonon_ddb”</p>
</dd>
</dl>
<p>material_id_list ([str]): list of material_id of compounds
kwargs (dict): other keyword arguments that get_*_by_material_id</p>
<blockquote>
<div><p>may have; e.g. line_mode in get_bandstructure_by_material_id</p>
</div></blockquote>
</dd>
<dt>Returns ([target prop object or NaN]):</dt><dd><p>If the target property is not available for a certain material_id,
NaN is returned.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="matminer-data-retrieval-retrieve-mpds-module">
<h2>matminer.data_retrieval.retrieve_MPDS module<a class="headerlink" href="#matminer-data-retrieval-retrieve-mpds-module" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-matminer.data_retrieval.retrieve_MongoDB">
<span id="matminer-data-retrieval-retrieve-mongodb-module"></span><h2>matminer.data_retrieval.retrieve_MongoDB module<a class="headerlink" href="#module-matminer.data_retrieval.retrieve_MongoDB" title="Permalink to this headline">¶</a></h2>
<dl class="py class">
<dt id="matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval">
<em class="property">class </em><code class="sig-prename descclassname">matminer.data_retrieval.retrieve_MongoDB.</code><code class="sig-name descname">MongoDataRetrieval</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">coll</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval" title="matminer.data_retrieval.retrieve_base.BaseDataRetrieval"><code class="xref py py-class docutils literal notranslate"><span class="pre">matminer.data_retrieval.retrieve_base.BaseDataRetrieval</span></code></a></p>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.__init__">
<code class="sig-name descname">__init__</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">coll</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieves data from a MongoDB collection to a pandas.Dataframe object</p>
<dl class="simple">
<dt>Args:</dt><dd><p>coll: A MongoDB collection object</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.api_link">
<code class="sig-name descname">api_link</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.api_link" title="Permalink to this definition">¶</a></dt>
<dd><p>The link to comprehensive API documentation or data source.</p>
<dl class="simple">
<dt>Returns:</dt><dd><p>(str): A link to the API documentation for this DataRetrieval class.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.get_dataframe">
<code class="sig-name descname">get_dataframe</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">criteria</span></em>, <em class="sig-param"><span class="n">properties</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">limit</span><span class="o">=</span><span class="default_value">0</span></em>, <em class="sig-param"><span class="n">sort</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">idx_field</span><span class="o">=</span><span class="default_value">None</span></em>, <em class="sig-param"><span class="n">strict</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.MongoDataRetrieval.get_dataframe" title="Permalink to this definition">¶</a></dt>
<dd><dl>
<dt>Args:</dt><dd><p>criteria: (dict) - a pymongo-style query to filter data records
properties: ([str] or None) - a list of str fields to retrieve;</p>
<blockquote>
<div><p>dot-notation is allowed (e.g. “structure.lattice.a”).
Set to “None” to try to auto-detect the fields.</p>
</div></blockquote>
<p>limit: (int) - max number of entries. 0 means no limit
sort: (tuple) - pymongo-style sort option
idx_field: (str) - name of field to use as index (must have unique</p>
<blockquote>
<div><p>entries)</p>
</div></blockquote>
<p>strict: (bool) - if False, replaces missing values with NaN</p>
</dd>
</dl>
<p>Returns (pandas.DataFrame):</p>
</dd></dl>
</dd></dl>
<dl class="py function">
<dt id="matminer.data_retrieval.retrieve_MongoDB.clean_projection">
<code class="sig-prename descclassname">matminer.data_retrieval.retrieve_MongoDB.</code><code class="sig-name descname">clean_projection</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">projection</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.clean_projection" title="Permalink to this definition">¶</a></dt>
<dd><p>Projecting on e.g. ‘a.b.’ and ‘a’ is disallowed in MongoDb, so project
inclusively. See unit tests for examples of what this is doing.</p>
<dl class="simple">
<dt>Args:</dt><dd><p>projection: (list) - list of fields to retrieve; dot-notation is allowed.</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt id="matminer.data_retrieval.retrieve_MongoDB.is_int">
<code class="sig-prename descclassname">matminer.data_retrieval.retrieve_MongoDB.</code><code class="sig-name descname">is_int</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">x</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.is_int" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="py function">
<dt id="matminer.data_retrieval.retrieve_MongoDB.remove_ints">
<code class="sig-prename descclassname">matminer.data_retrieval.retrieve_MongoDB.</code><code class="sig-name descname">remove_ints</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">projection</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_MongoDB.remove_ints" title="Permalink to this definition">¶</a></dt>
<dd><p>Transforms a string like “a.1.x” to “a.x” - for Mongo projection purposes</p>
<dl class="simple">
<dt>Args:</dt><dd><p>projection: (str) the projection to remove ints from</p>
</dd>
</dl>
<p>Returns (str)</p>
</dd></dl>
</div>
<div class="section" id="module-matminer.data_retrieval.retrieve_base">
<span id="matminer-data-retrieval-retrieve-base-module"></span><h2>matminer.data_retrieval.retrieve_base module<a class="headerlink" href="#module-matminer.data_retrieval.retrieve_base" title="Permalink to this headline">¶</a></h2>
<dl class="py class">
<dt id="matminer.data_retrieval.retrieve_base.BaseDataRetrieval">
<em class="property">class </em><code class="sig-prename descclassname">matminer.data_retrieval.retrieve_base.</code><code class="sig-name descname">BaseDataRetrieval</code><a class="headerlink" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
<p>Abstract class to retrieve data from various material APIs while adhering to
a quasi-standard format for querying.</p>
<p>## Implementing a new DataRetrieval class</p>
<p>If you have an API which you’d like to incorporate into matminer’s data
retrieval tools, using BaseDataRetrieval is the preferred way of doing so.
All DataRetrieval classes should subclass BaseDataRetrieval and implement
the following:</p>
<blockquote>
<div><ul class="simple">
<li><p>get_dataframe()</p></li>
<li><p>api_link()</p></li>
</ul>
</div></blockquote>
<p>Retrieving data should be done by the user with get_dataframe. Criteria
should be a dictionary which will be used to form a query to the database.
Properties should be a list which defines the columns that will be returned.
While the ‘criteria’ and ‘properties’ arguments may have different valid
values depending on the database, they should always have sensible formats
and names if possible. For example, the user should be calling this:</p>
<dl class="simple">
<dt>df = MyDataRetrieval().get_dataframe(criteria={‘band_gap’: 0.0},</dt><dd><p>properties=[‘structure’])</p>
</dd>
</dl>
<p>…or this:</p>
<dl class="simple">
<dt>df = MyDataRetrieval().get_dataframe(criteria={‘band_gap’: [0.0, 0.15]},</dt><dd><p>properties=[“density of states”])</p>
</dd>
</dl>
<p>NOT this:</p>
<dl class="simple">
<dt>df = MyDataRetrieval().get_dataframe(criteria={‘query.bg[0] && band_gap’: 0.0},</dt><dd><p>properties=[‘Struct.page[Value]’])</p>
</dd>
</dl>
<p>The implemented DataRetrieval class should handle the conversion from a
‘sensible’ query to a query fit for the individual API and database.</p>
<p>There may be cases where a ‘sensible’ query is not sufficient to define a
query to the API; in this case, use the get_dataframe kwargs sparingly to
augment the criteria, properties, or form of the underlying API query.</p>
<p>A method for accessing raw DB data with an API-native query <em>may</em> be
provided by overriding get_data. The link to the original API documentation
<em>must</em> be provided by overriding api_link().</p>
<p>## Documenting a DataRetrieval class</p>
<p>The class documentation for each DataRetrieval class must contain a brief
description of the possible data that can be retrieved with the API source.
It should also detail the form of the criteria and properties that can be
retrieved with the class, and/or should link to a web page showing this
information. The options of the class must all be defined in the <cite>__init__</cite>
function of the class, and we recommend documenting them using the
[Google style](<a class="reference external" href="https://google.github.io/styleguide/pyguide.html">https://google.github.io/styleguide/pyguide.html</a>).</p>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_base.BaseDataRetrieval.api_link">
<code class="sig-name descname">api_link</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval.api_link" title="Permalink to this definition">¶</a></dt>
<dd><p>The link to comprehensive API documentation or data source.</p>
<dl class="simple">
<dt>Returns:</dt><dd><p>(str): A link to the API documentation for this DataRetrieval class.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_base.BaseDataRetrieval.citations">
<code class="sig-name descname">citations</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval.citations" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve a list of formatted strings of bibtex citations which
should be cited when using a data retrieval method.</p>
<dl class="simple">
<dt>Returns:</dt><dd><p>([str]): Bibtext formatted entries</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="matminer.data_retrieval.retrieve_base.BaseDataRetrieval.get_dataframe">
<code class="sig-name descname">get_dataframe</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">criteria</span></em>, <em class="sig-param"><span class="n">properties</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#matminer.data_retrieval.retrieve_base.BaseDataRetrieval.get_dataframe" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve a dataframe of properties from the database which satisfy
criteria.</p>
<dl class="simple">
<dt>Args:</dt><dd><dl class="simple">
<dt>criteria (dict): The name of each criterion is the key; the value</dt><dd><p>or range of the criterion is the value.</p>
</dd>
<dt>properties (list): Properties to return from the query matching</dt><dd><p>the criteria. For example, [‘structure’, ‘formula’]</p>
</dd>
</dl>
</dd>
<dt>Returns:</dt><dd><dl class="simple">
<dt>(pandas DataFrame) The dataframe containing properties as columns</dt><dd><p>and samples as rows.</p>
</dd>
</dl>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-matminer.data_retrieval">
<span id="module-contents"></span><h2>Module contents<a class="headerlink" href="#module-matminer.data_retrieval" title="Permalink to this headline">¶</a></h2>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">matminer.data_retrieval package</a><ul>
<li><a class="reference internal" href="#subpackages">Subpackages</a></li>
<li><a class="reference internal" href="#submodules">Submodules</a></li>
<li><a class="reference internal" href="#matminer-data-retrieval-retrieve-aflow-module">matminer.data_retrieval.retrieve_AFLOW module</a></li>
<li><a class="reference internal" href="#matminer-data-retrieval-retrieve-citrine-module">matminer.data_retrieval.retrieve_Citrine module</a></li>
<li><a class="reference internal" href="#matminer-data-retrieval-retrieve-mdf-module">matminer.data_retrieval.retrieve_MDF module</a></li>
<li><a class="reference internal" href="#module-matminer.data_retrieval.retrieve_MP">matminer.data_retrieval.retrieve_MP module</a></li>
<li><a class="reference internal" href="#matminer-data-retrieval-retrieve-mpds-module">matminer.data_retrieval.retrieve_MPDS module</a></li>
<li><a class="reference internal" href="#module-matminer.data_retrieval.retrieve_MongoDB">matminer.data_retrieval.retrieve_MongoDB module</a></li>
<li><a class="reference internal" href="#module-matminer.data_retrieval.retrieve_base">matminer.data_retrieval.retrieve_base module</a></li>
<li><a class="reference internal" href="#module-matminer.data_retrieval">Module contents</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/matminer.data_retrieval.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">matminer 0.7.6 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">matminer.data_retrieval package</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015, Anubhav Jain.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>