matplotlib.github.com/2.2.2/_modules/matplotlib/spines.html at main · matplotlib/matplotlib.github.com

History

678 lines (582 loc) · 85.5 KB

Raw

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

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>matplotlib.spines — Matplotlib 2.2.2 documentation</title>

type="text/css" />

type="text/css" />

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../../',

VERSION: '2.2.2',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true,

SOURCELINK_SUFFIX: '.txt'

};

</script>

title="Search within Matplotlib 2.2.2 documentation"

href="../../_static/opensearch.xml"/>

</head>

<body>

<div id="unreleased-message"> You are reading an old version of the documentation (v2.2.2). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px">Version 2.2.2</div>

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>

</div>

<h3>Navigation</h3>

<ul>

<a href="../../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<li><a href="../../gallery/index.html">examples</a>| </li>

<li><a href="../../tutorials/index.html">tutorials</a>| </li>

<li><a href="../../api/pyplot_summary.html">pyplot</a>| </li>

<li><a href="../index.html" >Module code</a> »</li>

<li><a href="../matplotlib.html" accesskey="U">matplotlib</a> »</li>

</ul>

</div>

<h3>Quick search</h3>

</form>

</div>

<h3>Related Topics</h3>

<ul>

<li><a href="../../contents.html">Documentation overview</a><ul>

<li><a href="../index.html">Module code</a><ul>

<li><a href="../matplotlib.html">matplotlib</a><ul>

</ul></li>

</ul>

</div>

<h1>Source code for matplotlib.spines</h1><div class="highlight"><pre>

from __future__ import (absolute_import, division, print_function,

unicode_literals)

import six

import matplotlib

from matplotlib.artist import allow_rasterization

from matplotlib import docstring

import matplotlib.transforms as mtransforms

import matplotlib.patches as mpatches

import matplotlib.path as mpath

import numpy as np

import warnings

rcParams = matplotlib.rcParams

<div class="viewcode-block" id="Spine"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine">[docs]</a>class Spine(mpatches.Patch):

"""an axis spine -- the line noting the data area boundaries

Spines are the lines connecting the axis tick marks and noting the

boundaries of the data area. They can be placed at arbitrary

positions. See function:`~matplotlib.spines.Spine.set_position`

for more information.

The default position is ``('outward',0)``.

Spines are subclasses of class:`~matplotlib.patches.Patch`, and

inherit much of their behavior.

Spines draw a line, a circle, or an arc depending if

function:`~matplotlib.spines.Spine.set_patch_line`,

function:`~matplotlib.spines.Spine.set_patch_circle`, or

function:`~matplotlib.spines.Spine.set_patch_arc` has been called.

Line-like is the default.

"""

def __str__(self):

return "Spine"

@docstring.dedent_interpd

def __init__(self, axes, spine_type, path, **kwargs):

"""

- *axes* : the Axes instance containing the spine

- *spine_type* : a string specifying the spine type

- *path* : the path instance used to draw the spine

Valid kwargs are:

%(Patch)s

"""

super(Spine, self).__init__(**kwargs)

self.axes = axes

self.set_figure(self.axes.figure)

self.spine_type = spine_type

self.set_facecolor('none')

self.set_edgecolor(rcParams['axes.edgecolor'])

self.set_linewidth(rcParams['axes.linewidth'])

self.set_capstyle('projecting')

self.axis = None

self.set_zorder(2.5)

self.set_transform(self.axes.transData) # default transform

self._bounds = None # default bounds

self._smart_bounds = False

# Defer initial position determination. (Not much support for

# non-rectangular axes is currently implemented, and this lets

# them pass through the spines machinery without errors.)

self._position = None

if not isinstance(path, matplotlib.path.Path):

raise ValueError(

"'path' must be an instance of 'matplotlib.path.Path'")

self._path = path

# To support drawing both linear and circular spines, this

# class implements Patch behavior three ways. If

# self._patch_type == 'line', behave like a mpatches.PathPatch

# instance. If self._patch_type == 'circle', behave like a

# mpatches.Ellipse instance. If self._patch_type == 'arc', behave like

# a mpatches.Arc instance.

self._patch_type = 'line'

# Behavior copied from mpatches.Ellipse:

# Note: This cannot be calculated until this is added to an Axes

self._patch_transform = mtransforms.IdentityTransform()

<div class="viewcode-block" id="Spine.set_smart_bounds"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_smart_bounds">[docs]</a> def set_smart_bounds(self, value):

"""set the spine and associated axis to have smart bounds"""

self._smart_bounds = value

# also set the axis if possible

if self.spine_type in ('left', 'right'):

self.axes.yaxis.set_smart_bounds(value)

elif self.spine_type in ('top', 'bottom'):

self.axes.xaxis.set_smart_bounds(value)

self.stale = True</div>

<div class="viewcode-block" id="Spine.get_smart_bounds"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_smart_bounds">[docs]</a> def get_smart_bounds(self):

"""get whether the spine has smart bounds"""

return self._smart_bounds</div>

<div class="viewcode-block" id="Spine.set_patch_arc"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_patch_arc">[docs]</a> def set_patch_arc(self, center, radius, theta1, theta2):

"""set the spine to be arc-like"""

self._patch_type = 'arc'

self._center = center

self._width = radius * 2

self._height = radius * 2

self._theta1 = theta1

self._theta2 = theta2

# arc drawn on axes transform

self.stale = True</div>

<div class="viewcode-block" id="Spine.set_patch_circle"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_patch_circle">[docs]</a> def set_patch_circle(self, center, radius):

"""set the spine to be circular"""

self._patch_type = 'circle'

self._center = center

self._width = radius * 2

self._height = radius * 2

# circle drawn on axes transform

self.stale = True</div>

<div class="viewcode-block" id="Spine.set_patch_line"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_patch_line">[docs]</a> def set_patch_line(self):

"""set the spine to be linear"""

self._patch_type = 'line'

self.stale = True</div>

# Behavior copied from mpatches.Ellipse:

def _recompute_transform(self):

"""NOTE: This cannot be called until after this has been added

to an Axes, otherwise unit conversion will fail. This

makes it very important to call the accessor method and

not directly access the transformation member variable.

"""

assert self._patch_type in ('arc', 'circle')

center = (self.convert_xunits(self._center[0]),

self.convert_yunits(self._center[1]))

width = self.convert_xunits(self._width)

height = self.convert_yunits(self._height)

.scale(width * 0.5, height * 0.5) \

.translate(*center)

<div class="viewcode-block" id="Spine.get_patch_transform"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_patch_transform">[docs]</a> def get_patch_transform(self):

if self._patch_type in ('arc', 'circle'):

self._recompute_transform()

return self._patch_transform

else:

return super(Spine, self).get_patch_transform()</div>

<div class="viewcode-block" id="Spine.get_path"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_path">[docs]</a> def get_path(self):

return self._path</div>

def _ensure_position_is_set(self):

if self._position is None:

# default position

self._position = ('outward', 0.0) # in points

self.set_position(self._position)

<div class="viewcode-block" id="Spine.register_axis"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.register_axis">[docs]</a> def register_axis(self, axis):

"""register an axis

An axis should be registered with its corresponding spine from

the Axes instance. This allows the spine to clear any axis

properties when needed.

"""

self.axis = axis

if self.axis is not None:

self.axis.cla()

self.stale = True</div>

<div class="viewcode-block" id="Spine.cla"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.cla">[docs]</a> def cla(self):

"""Clear the current spine"""

self._position = None # clear position

self.axis.cla()</div>

<div class="viewcode-block" id="Spine.is_frame_like"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.is_frame_like">[docs]</a> def is_frame_like(self):

"""return True if directly on axes frame

This is useful for determining if a spine is the edge of an

old style MPL plot. If so, this function will return True.

"""

self._ensure_position_is_set()

position = self._position

if isinstance(position, six.string_types):

if position == 'center':

position = ('axes', 0.5)

elif position == 'zero':

position = ('data', 0)

if len(position) != 2:

raise ValueError("position should be 2-tuple")

position_type, amount = position

if position_type == 'outward' and amount == 0:

return True

else:

return False</div>

def _adjust_location(self):

"""automatically set spine bounds to the view interval"""

if self.spine_type == 'circle':

return

if self._bounds is None:

low, high = self.axes.viewLim.intervaly

else:

raise ValueError('unknown spine spine_type: %s' %

self.spine_type)

if self._smart_bounds:

# attempt to set bounds in sophisticated way

# handle inverted limits

viewlim_low, viewlim_high = sorted([low, high])

datalim_low, datalim_high = self.axes.dataLim.intervaly

ticks = self.axes.get_yticks()

# handle inverted limits

ticks = np.sort(ticks)

datalim_low, datalim_high = sorted([datalim_low, datalim_high])

if datalim_low < viewlim_low:

# Data extends past view. Clip line to view.

low = viewlim_low

else:

# Data ends before view ends.

cond = (ticks <= datalim_low) & (ticks >= viewlim_low)

tickvals = ticks[cond]

if len(tickvals):

# A tick is less than or equal to lowest data point.

low = tickvals[-1]

else:

# No tick is available

low = datalim_low

low = max(low, viewlim_low)

if datalim_high > viewlim_high:

# Data extends past view. Clip line to view.

high = viewlim_high

else:

# Data ends before view ends.

cond = (ticks >= datalim_high) & (ticks <= viewlim_high)

tickvals = ticks[cond]

if len(tickvals):

# A tick is greater than or equal to highest data

# point.

high = tickvals[0]

else:

# No tick is available

high = datalim_high

high = min(high, viewlim_high)

else:

low, high = self._bounds

if self._patch_type == 'arc':

if self.spine_type in ('bottom', 'top'):

try:

direction = self.axes.get_theta_direction()

except AttributeError:

direction = 1

try:

offset = self.axes.get_theta_offset()

except AttributeError:

offset = 0

low = low * direction + offset

high = high * direction + offset

if low > high:

low, high = high, low

self._path = mpath.Path.arc(np.rad2deg(low), np.rad2deg(high))

if self.spine_type == 'bottom':

rmin, rmax = self.axes.viewLim.intervaly

try:

rorigin = self.axes.get_rorigin()

except AttributeError:

rorigin = rmin

scaled_diameter = (rmin - rorigin) / (rmax - rorigin)

self._height = scaled_diameter

self._width = scaled_diameter

else:

raise ValueError('unable to set bounds for spine "%s"' %

self.spine_type)

else:

v1 = self._path.vertices

assert v1.shape == (2, 2), 'unexpected vertices shape'

if self.spine_type in ['left', 'right']:

v1[0, 1] = low

v1[1, 1] = high

elif self.spine_type in ['bottom', 'top']:

v1[0, 0] = low

v1[1, 0] = high

else:

self.spine_type)

<div class="viewcode-block" id="Spine.draw"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.draw">[docs]</a> @allow_rasterization

def draw(self, renderer):

self._adjust_location()

ret = super(Spine, self).draw(renderer)

self.stale = False

return ret</div>

def _calc_offset_transform(self):

"""calculate the offset transform performed by the spine"""

self._ensure_position_is_set()

position = self._position

if position == 'center':

position = ('axes', 0.5)

elif position == 'zero':

position = ('data', 0)

assert len(position) == 2, "position should be 2-tuple"

position_type, amount = position

assert position_type in ('axes', 'outward', 'data')

if position_type == 'outward':

if amount == 0:

# short circuit commonest case

self._spine_transform = ('identity',

mtransforms.IdentityTransform())

elif self.spine_type in ['left', 'right', 'top', 'bottom']:

offset_vec = {'left': (-1, 0),

'right': (1, 0),

'bottom': (0, -1),

'top': (0, 1),

}[self.spine_type]

# calculate x and y offset in dots

offset_x = amount * offset_vec[0] / 72.0

offset_y = amount * offset_vec[1] / 72.0

self._spine_transform = ('post',

mtransforms.ScaledTranslation(

offset_x,

offset_y,

self.figure.dpi_scale_trans))

else:

warnings.warn('unknown spine type "%s": no spine '

'offset performed' % self.spine_type)

self._spine_transform = ('identity',

mtransforms.IdentityTransform())

elif position_type == 'axes':

self._spine_transform = ('pre',

mtransforms.Affine2D.from_values(

# keep y unchanged, fix x at

# amount

0, 0, 0, 1, amount, 0))

elif self.spine_type in ('bottom', 'top'):

self._spine_transform = ('pre',

mtransforms.Affine2D.from_values(

# keep x unchanged, fix y at

# amount

1, 0, 0, 0, 0, amount))

else:

'offset performed' % self.spine_type)

self._spine_transform = ('identity',

mtransforms.IdentityTransform())

elif position_type == 'data':

if self.spine_type in ('right', 'top'):

# The right and top spines have a default position of 1 in

# axes coordinates. When specifying the position in data

# coordinates, we need to calculate the position relative to 0.

amount -= 1

self._spine_transform = ('data',

mtransforms.Affine2D().translate(

amount, 0))

elif self.spine_type in ('bottom', 'top'):

self._spine_transform = ('data',

mtransforms.Affine2D().translate(

0, amount))

else:

'offset performed' % self.spine_type)

self._spine_transform = ('identity',

mtransforms.IdentityTransform())

<div class="viewcode-block" id="Spine.set_position"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_position">[docs]</a> def set_position(self, position):

"""set the position of the spine

Spine position is specified by a 2 tuple of (position type,

amount). The position types are:

* 'outward' : place the spine out from the data area by the

specified number of points. (Negative values specify placing the

spine inward.)

* 'axes' : place the spine at the specified Axes coordinate (from

0.0-1.0).

* 'data' : place the spine at the specified data coordinate.

Additionally, shorthand notations define a special positions:

* 'center' -> ('axes',0.5)

* 'zero' -> ('data', 0.0)

"""

if position in ('center', 'zero'):

# special positions

pass

else:

raise ValueError("position should be 'center' or 2-tuple")

if position[0] not in ['outward', 'axes', 'data']:

raise ValueError("position[0] should be one of 'outward', "

"'axes', or 'data' ")

self._position = position

self._calc_offset_transform()

self.set_transform(self.get_spine_transform())

self.axis.reset_ticks()

self.stale = True</div>

<div class="viewcode-block" id="Spine.get_position"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_position">[docs]</a> def get_position(self):

"""get the spine position"""

self._ensure_position_is_set()

return self._position</div>

<div class="viewcode-block" id="Spine.get_spine_transform"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_spine_transform">[docs]</a> def get_spine_transform(self):

"""get the spine transform"""

self._ensure_position_is_set()

what, how = self._spine_transform

if what == 'data':

# special case data based spine locations

data_xform = self.axes.transScale + \

(how + self.axes.transLimits + self.axes.transAxes)

result = mtransforms.blended_transform_factory(

data_xform, self.axes.transData)

elif self.spine_type in ['top', 'bottom']:

result = mtransforms.blended_transform_factory(

self.axes.transData, data_xform)

else:

self.spine_type)

return result

base_transform = self.axes.get_yaxis_transform(which='grid')

elif self.spine_type in ['top', 'bottom']:

base_transform = self.axes.get_xaxis_transform(which='grid')

else:

self.spine_type)

if what == 'identity':

return base_transform

elif what == 'post':

return base_transform + how

elif what == 'pre':

return how + base_transform

else:

raise ValueError("unknown spine_transform type: %s" % what)</div>

<div class="viewcode-block" id="Spine.set_bounds"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_bounds">[docs]</a> def set_bounds(self, low, high):

"""Set the bounds of the spine."""

if self.spine_type == 'circle':

raise ValueError(

'set_bounds() method incompatible with circular spines')

self._bounds = (low, high)

self.stale = True</div>

<div class="viewcode-block" id="Spine.get_bounds"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.get_bounds">[docs]</a> def get_bounds(self):

"""Get the bounds of the spine."""

return self._bounds</div>

<div class="viewcode-block" id="Spine.linear_spine"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.linear_spine">[docs]</a> @classmethod

def linear_spine(cls, axes, spine_type, **kwargs):

"""

(staticmethod) Returns a linear :class:`Spine`.

"""

# all values of 13 get replaced upon call to set_bounds()

if spine_type == 'left':

path = mpath.Path([(0.0, 13), (0.0, 13)])

elif spine_type == 'right':

path = mpath.Path([(1.0, 13), (1.0, 13)])

elif spine_type == 'bottom':

path = mpath.Path([(13, 0.0), (13, 0.0)])

elif spine_type == 'top':

path = mpath.Path([(13, 1.0), (13, 1.0)])

else:

raise ValueError('unable to make path for spine "%s"' % spine_type)

result = cls(axes, spine_type, path, **kwargs)

result.set_visible(rcParams['axes.spines.{0}'.format(spine_type)])

return result</div>

<div class="viewcode-block" id="Spine.arc_spine"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.arc_spine">[docs]</a> @classmethod

def arc_spine(cls, axes, spine_type, center, radius, theta1, theta2,

**kwargs):

"""

(classmethod) Returns an arc :class:`Spine`.

"""

path = mpath.Path.arc(theta1, theta2)

result.set_patch_arc(center, radius, theta1, theta2)

return result</div>

<div class="viewcode-block" id="Spine.circular_spine"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.circular_spine">[docs]</a> @classmethod

def circular_spine(cls, axes, center, radius, **kwargs):

"""

(staticmethod) Returns a circular :class:`Spine`.

"""

spine_type = 'circle'

result.set_patch_circle(center, radius)

return result</div>

<div class="viewcode-block" id="Spine.set_color"><a class="viewcode-back" href="../../api/spines_api.html#matplotlib.spines.Spine.set_color">[docs]</a> def set_color(self, c):

"""

Set the edgecolor.

ACCEPTS: matplotlib color arg or sequence of rgba tuples

.. seealso::

:meth:`set_facecolor`, :meth:`set_edgecolor`

For setting the edge or face color individually.

"""

# The facecolor of a spine is always 'none' by default -- let

# the user change it manually if desired.

self.set_edgecolor(c)

self.stale = True</div></div>

</pre></div>

</div>

</div>

Last updated on Jun 28, 2018.

Created using

<ahref="http://sphinx-doc.org/">Sphinx</a> 1.7.5.

Doc version v2.2.2-101-g15e1eadd0.

</div>

</body>

</footer>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

spines.html

Latest commit

History

spines.html

File metadata and controls