-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathaxes.html
273 lines (260 loc) · 20.5 KB
/
axes.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Axis class overview — PyGeode 1.4.1-rc2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/pygtheme.css" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery.css" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-binder.css" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-dataframe.css" />
<link rel="stylesheet" type="text/css" href="_static/sg_gallery-rendered-html.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/pygeode_icon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Axis class reference" href="axis.html" />
<link rel="prev" title="Other operations" href="var.other.html" />
<link href="http://fonts.googleapis.com/css?family=Ubuntu:300,300italic,regular,italic,500,500italic,bold,bolditalic" rel="stylesheet" type="text/css">
<link href='http://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700' rel='stylesheet' type='text/css'>
</head><body>
<div class="header" role="banner"><img class="logo" src="_static/pygeode_logo.png" width=79px alt="Logo"/>
<h1 class="heading"><a href="index.html">
<span>PyGeode 1.4.1-rc2 documentation</span></a></h1>
<h2 class="heading"><span>Axis class overview</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="var.other.html">Other operations</a>
  ::  
<a class="uplink" href="reference.html">Reference</a>
  ::  
<a class="uplink" href="tutorial.html">Tutorial</a>
  ::  
<a class="uplink" href="gallery/index.html">Gallery</a>
  ::  
<a href="axis.html">Axis class reference</a>  »
</p>
</div>
<div class="content">
<div class="section" id="axis-class-overview">
<h1>Axis class overview<a class="headerlink" href="#axis-class-overview" title="Permalink to this headline">¶</a></h1>
<p>An Axis is a one-dimensional array of values, representing some kind of
coordinate. For example, a <code class="docutils literal notranslate"><span class="pre">Lat</span></code> axis represents a set of latitudes over the
globe. Axes are a subclass of <a class="reference internal" href="var.html#pygeode.Var" title="pygeode.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a>, and can be treated as such for many purposes
(such as arithmetic operations), though they have some specific behaviour, including
the fact that their values are always explicitly loaded into memory.</p>
<p>In practice the <a class="reference internal" href="#pygeode.Axis" title="pygeode.Axis"><code class="xref py py-class docutils literal notranslate"><span class="pre">Axis</span></code></a> class is rarely instantiated directly; one of its subclasses
are typically used to represent a dimension of a particular type.</p>
<div class="section" id="types-of-axes">
<h2>Types of axes<a class="headerlink" href="#types-of-axes" title="Permalink to this headline">¶</a></h2>
<p>The following is a (non-exhaustive) list of more commonly used axes built into PyGeode:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="namedaxis.html#pygeode.NamedAxis" title="pygeode.NamedAxis"><code class="xref py py-obj docutils literal notranslate"><span class="pre">NamedAxis</span></code></a></p></td>
<td><p>Generic axis object identified by its name.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="horizontalaxes.html#pygeode.Lon" title="pygeode.Lon"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Lon</span></code></a></p></td>
<td><p>Longitude axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="horizontalaxes.html#pygeode.Lat" title="pygeode.Lat"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Lat</span></code></a></p></td>
<td><p>Latitude axis.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="verticalaxes.html#pygeode.Height" title="pygeode.Height"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Height</span></code></a></p></td>
<td><p>Geometric height axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="verticalaxes.html#pygeode.Pres" title="pygeode.Pres"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Pres</span></code></a></p></td>
<td><p>Pressure height axis.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="verticalaxes.html#pygeode.Hybrid" title="pygeode.Hybrid"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Hybrid</span></code></a></p></td>
<td><p>Hybridized vertical coordinate axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="timeaxes.html#pygeode.StandardTime" title="pygeode.StandardTime"><code class="xref py py-obj docutils literal notranslate"><span class="pre">StandardTime</span></code></a></p></td>
<td><p>Time axis describing the standard Gregorian calendar.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="timeaxes.html#pygeode.ModelTime365" title="pygeode.ModelTime365"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ModelTime365</span></code></a></p></td>
<td><p>Time axis describing a model 365-day calendar.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="timeaxes.html#pygeode.ModelTime360" title="pygeode.ModelTime360"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ModelTime360</span></code></a></p></td>
<td><p>Time axis describing a model 360-day calendar.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="timeaxes.html#pygeode.Yearless" title="pygeode.Yearless"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Yearless</span></code></a></p></td>
<td><p>Time axis describing a calendar with no months or years.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="namedaxis.html#pygeode.NonCoordinateAxis" title="pygeode.NonCoordinateAxis"><code class="xref py py-obj docutils literal notranslate"><span class="pre">NonCoordinateAxis</span></code></a></p></td>
<td><p>Non-coordinate axis (disables nearest-neighbour value matching, etc.)</p></td>
</tr>
</tbody>
</table>
<p>If PyGeode doesn’t have a built-in representation of an axis that your input
data uses, it will default to a generic <a class="reference internal" href="namedaxis.html#pygeode.NamedAxis" title="pygeode.NamedAxis"><code class="xref py py-class docutils literal notranslate"><span class="pre">NamedAxis</span></code></a> object, with no additional
context on what that axis represents. To get around this, you can always
define your own <a class="reference internal" href="#axis-custom"><span class="std std-ref">custom</span></a> axis, and force your Var to use it
through <a class="reference internal" href="varops.html#pygeode.Var.replace_axes" title="pygeode.Var.replace_axes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Var.replace_axes()</span></code></a> or when importing from a data file.</p>
<p>In addition to the members listed below, <a class="reference internal" href="#pygeode.Axis" title="pygeode.Axis"><code class="xref py py-class docutils literal notranslate"><span class="pre">Axis</span></code></a> objects inherit methods from
the <a class="reference internal" href="var.html#pygeode.Var" title="pygeode.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a> class; see <a class="reference internal" href="var.html"><span class="doc">Var class overview</span></a> for this functionality.</p>
<dl class="py class">
<dt class="sig sig-object py" id="pygeode.Axis">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pygeode.</span></span><span class="sig-name descname"><span class="pre">Axis</span></span><a class="reference internal" href="_modules/pygeode/axis.html#Axis"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pygeode.Axis" title="Permalink to this definition">¶</a></dt>
<dd><p>Inherits from <a class="reference internal" href="var.html#pygeode.Var" title="pygeode.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a></p>
<p class="rubric">Generic attributes</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.auxarrays" title="pygeode.Axis.auxarrays"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.auxarrays</span></code></a></p></td>
<td><p>Auxiliary arrays.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.auxatts" title="pygeode.Axis.auxatts"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.auxatts</span></code></a></p></td>
<td><p>Auxiliary attributes.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.rtol" title="pygeode.Axis.rtol"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.rtol</span></code></a></p></td>
<td><p>The relative tolerance for identifying an element of this axis.</p></td>
</tr>
</tbody>
</table>
<p class="rubric">Generic Axis methods</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.__init__" title="pygeode.Axis.__init__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.__init__</span></code></a>(values[, name, atts, ...])</p></td>
<td><p>Create a new Axis object with the given values.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.argsort" title="pygeode.Axis.argsort"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.argsort</span></code></a>([reverse])</p></td>
<td><p>Generates a list of indices that would sort the Axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.auxasvar" title="pygeode.Axis.auxasvar"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.auxasvar</span></code></a>(name)</p></td>
<td><p>Returns auxiliary array as a new <a class="reference internal" href="var.html#pygeode.Var" title="pygeode.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a> object.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.rename" title="pygeode.Axis.rename"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.rename</span></code></a>(name)</p></td>
<td><p>Assigns a new name to this axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.sorted" title="pygeode.Axis.sorted"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.sorted</span></code></a>([reverse])</p></td>
<td><p>Sorts the points of the Axis.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.str_as_val" title="pygeode.Axis.str_as_val"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.str_as_val</span></code></a>(key, s)</p></td>
<td><p>str_as_val(self, key, s) - converts string s to a value corresponding to this axis.</p></td>
</tr>
</tbody>
</table>
<p class="rubric">Formatting and Plotting</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.formatstr" title="pygeode.Axis.formatstr"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.formatstr</span></code></a></p></td>
<td><p>Format specification for plotting values.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.formatter" title="pygeode.Axis.formatter"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.formatter</span></code></a>()</p></td>
<td><p>Returns a matplotlib formatter (pygeode.AxisFormatter) for use in plotting.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.locator" title="pygeode.Axis.locator"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.locator</span></code></a>()</p></td>
<td><p>Returns a matplotlib locator object for use in plotting.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.plotatts" title="pygeode.Axis.plotatts"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.plotatts</span></code></a></p></td>
<td><p>Dictionary of attributes for plotting; see plotting documentation.</p></td>
</tr>
</tbody>
</table>
<p class="rubric">Internal calls</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.__call__" title="pygeode.Axis.__call__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.__call__</span></code></a>(**kwargs)</p></td>
<td><p>Keyword-based data subsetting.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis._getitem_asvar" title="pygeode.Axis._getitem_asvar"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis._getitem_asvar</span></code></a>(slices)</p></td>
<td><p>Slice-based data subsetting.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.class_has_alias" title="pygeode.Axis.class_has_alias"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.class_has_alias</span></code></a>(name)</p></td>
<td><p></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.isparentof" title="pygeode.Axis.isparentof"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.isparentof</span></code></a>(other)</p></td>
<td><p>Determines if an axis object is an instance of a base class (or the same class) of another axis.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="axis.html#pygeode.Axis.map_to" title="pygeode.Axis.map_to"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Axis.map_to</span></code></a>(other)</p></td>
<td><p>Returns indices of this axis which correspond to the axis <code class="docutils literal notranslate"><span class="pre">other</span></code>.</p></td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="defining-a-new-type-of-axis">
<span id="axis-custom"></span><h2>Defining a new type of axis<a class="headerlink" href="#defining-a-new-type-of-axis" title="Permalink to this headline">¶</a></h2>
<p>It’s impossible (or at least improbable) for the standard PyGeode package to include every possible type of axis that people may want. However, it’s fairly straight-forward to define your own custom axis. Simply define a new class, as a subclass of <a class="reference internal" href="#pygeode.Axis" title="pygeode.Axis"><code class="xref py py-class docutils literal notranslate"><span class="pre">Axis</span></code></a>.</p>
<p>For example, suppose one of the dimensions of your data is solar zenith angle (SZA). You can make a simple Axis representation as follows:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pygeode</span> <span class="kn">import</span> <span class="n">Axis</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">SZA_Axis</span> <span class="p">(</span><span class="n">Axis</span><span class="p">):</span> <span class="k">pass</span>
<span class="gp">...</span>
</pre></div>
</div>
<p>You can now use it like any other axis:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">sza</span> <span class="o">=</span> <span class="n">SZA_Axis</span> <span class="p">([</span><span class="mf">20.1</span><span class="p">,</span> <span class="mf">20.2</span><span class="p">,</span> <span class="mf">20.3</span><span class="p">,</span> <span class="mf">20.4</span><span class="p">,</span> <span class="mf">20.5</span><span class="p">])</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">sza</span><span class="p">)</span>
<span class="go">sza_axis <SZA_Axis>: 20.1 to 20.5 (5 values)</span>
</pre></div>
</div>
<p>A more customized version:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span> <span class="nc">SZA_Axis</span> <span class="p">(</span><span class="n">Axis</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="s2">"sza"</span>
<span class="gp">... </span> <span class="n">units</span> <span class="o">=</span> <span class="s2">"degrees"</span>
<span class="gp">...</span>
<span class="gp">>>> </span><span class="n">sza</span> <span class="o">=</span> <span class="n">SZA_Axis</span> <span class="p">([</span><span class="mf">20.1</span><span class="p">,</span> <span class="mf">20.2</span><span class="p">,</span> <span class="mf">20.3</span><span class="p">,</span> <span class="mf">20.4</span><span class="p">,</span> <span class="mf">20.5</span><span class="p">])</span>
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">sza</span><span class="p">)</span>
<span class="go">sza_axis <SZA_Axis>: 20.1 degrees to 20.5 degrees (5 values)</span>
</pre></div>
</div>
<p>If you think your axis will be useful to others, please let us know, and we may include it in future versions.</p>
<p>Aspects of customizing an axis:</p>
<blockquote>
<div><ul class="simple">
<li><p>Defining its name</p></li>
<li><p>Customize how values are formatted as strings</p></li>
<li><p>Customize how strings are parsed into values</p></li>
<li><p>Customize matplotlib formatting and tick positioning</p></li>
<li><p>Customize CF-metadata encoding and decoding</p></li>
</ul>
</div></blockquote>
<div class="toctree-wrapper compound">
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="var.other.html">Other operations</a>
  ::  
<a class="uplink" href="reference.html">Reference</a>
  ::  
<a class="uplink" href="tutorial.html">Tutorial</a>
  ::  
<a class="uplink" href="gallery/index.html">Gallery</a>
  ::  
<a href="axis.html">Axis class reference</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2020, Mike Neish, Peter Hitchcock.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>