~ubuntu-branches/debian/sid/pyx/sid

.. class:: graphxy(xpos=0, ypos=0, width=None, height=None, ratio=goldenmean, key=None, backgroundattrs=None, axesdist=0.8*unit.v_cm, xaxisat=None, yaxisat=None, **axes)

142

143

This class provides an x-y-graph. A graph instance is also a fully functional

144

canvas.

145

146

The position of the graph on its own canvas is specified by *xpos* and *ypos*.

147

The size of the graph is specified by *width*, *height*, and *ratio*. These

148

parameters define the size of the graph area not taking into account the

149

additional space needed for the axes. Note that you have to specify at least

150

*width* or *height*. *ratio* will be used as the ratio between *width* and

151

*height* when only one of these is provided.

152

153

*key* can be set to a :class:`graph.key.key` instance to create an automatic

154

graph key. ``None`` omits the graph key.

155

156

*backgroundattrs* is a list of attributes for drawing the background of the

157

graph. Allowed are decorators, strokestyles, and fillstyles. ``None`` disables

158

background drawing.

159

160

*axisdist* is the distance between axes drawn at the same side of a graph.

161

162

*xaxisat* and *yaxisat* specify a value at the y and x axis, where the

163

corresponding axis should be moved to. It's a shortcut for corresonding calls of

164

:meth:`axisatv` described below. Moving an axis by *xaxisat* or *yaxisat*

165

disables the automatic creation of a linked axis at the opposite side of the

166

graph.

167

168

*\*\*axes* receives axes instances. Allowed keywords (axes names) are ``x``,

169

``x2``, ``x3``, *etc.* and ``y``, ``y2``, ``y3``, *etc.* When not providing an

170

``x`` or ``y`` axis, linear axes instances will be used automatically. When not

171

providing a ``x2`` or ``y2`` axis, linked axes to the ``x`` and ``y`` axes are

172

created automatically and *vice versa*. As an exception, a linked axis is not

173

created automatically when the axis is placed at a specific position by

174

*xaxisat* or *yaxisat*. You can disable the automatic creation of axes by

175

setting the linked axes to ``None``. The even numbered axes are plotted at the

176

top (``x`` axes) and right (``y`` axes) while the others are plotted at the

177

bottom (``x`` axes) and left (``y`` axes) in ascending order each.

178

179

Some instance attributes might be useful for outside read-access. Those are:

180

181

182

.. attribute:: graphxy.axes

183

184

A dictionary mapping axes names to the :class:`anchoredaxis` instances.

185

186

To actually plot something into the graph, the following instance method

187

:meth:`plot` is provided:

188

189

190

.. method:: graphxy.plot(data, styles=None)

191

192

Adds *data* to the list of data to be plotted. Sets *styles* to be used for

193

plotting the data. When *styles* is ``None``, the default styles for the data as

194

provided by *data* is used.

195

196

*data* should be an instance of any of the data described in section

197

:mod:`graph.data`.

198

199

When the same combination of styles (*i.e.* the same references) are used

200

several times within the same graph instance, the styles are kindly asked by the

201

graph to iterate their appearance. Its up to the styles how this is performed.

202

203

Instead of calling the plot method several times with different *data* but the

204

same style, you can use a list (or something iterateable) for *data*.

205

206

While a graph instance only collects data initially, at a certain point it must

207

create the whole plot. Once this is done, further calls of :meth:`plot` will

208

fail. Usually you do not need to take care about the finalization of the graph,

209

because it happens automatically once you write the plot into a file. However,

210

sometimes position methods (described below) are nice to be accessible. For

211

that, at least the layout of the graph must have been finished. By calling the

212

:meth:`do`\ -methods yourself you can also alter the order in which the graph

213

components are plotted. Multiple calls to any of the :meth:`do`\ -methods have

214

no effect (only the first call counts). The orginal order in which the

215

:meth:`do`\ -methods are called is:

216

217

218

.. method:: graphxy.dolayout()

219

220

Fixes the layout of the graph. As part of this work, the ranges of the axes are

221

fitted to the data when the axes ranges are allowed to adjust themselves to the

222

data ranges. The other :meth:`do`\ -methods ensure, that this method is always

223

called first.

224

225

226

.. method:: graphxy.dobackground()

227

228

Draws the background.

229

230

231

.. method:: graphxy.doaxes()

232

233

Inserts the axes.

234

235

236

.. method:: graphxy.doplotitem(plotitem)

237

238

Plots the plotitem as returned by the graphs plot method.

239

240

241

.. method:: graphxy.doplot()

242

243

Plots all (remaining) plotitems.

244

245

246

.. method:: graphxy.dokeyitem()

247

248

Inserts a plotitem in the graph key as returned by the graphs plot method.

249

250

251

.. method:: graphxy.dokey()

252

253

Inserts the graph key.

254

255

256

.. method:: graphxy.finish()

257

258

Finishes the graph by calling all pending :meth:`do`\ -methods. This is done

259

automatically, when the output is created.

260

261

The graph provides some methods to access its geometry:

262

263

264

.. method:: graphxy.pos(x, y, xaxis=None, yaxis=None)

265

266

Returns the given point at *x* and *y* as a tuple ``(xpos, ypos)`` at the graph

267

canvas. *x* and *y* are anchoredaxis instances for the two axes *xaxis* and

268

*yaxis*. When *xaxis* or *yaxis* are ``None``, the axes with names ``x`` and

269

``y`` are used. This method fails if called before :meth:`dolayout`.

270

271

272

.. method:: graphxy.vpos(vx, vy)

273

274

Returns the given point at *vx* and *vy* as a tuple ``(xpos, ypos)`` at the

275

graph canvas. *vx* and *vy* are graph coordinates with range [0:1].

276

277

278

.. method:: graphxy.vgeodesic(vx1, vy1, vx2, vy2)

279

280

Returns the geodesic between points *vx1*, *vy1* and *vx2*, *vy2* as a path. All

281

parameters are in graph coordinates with range [0:1]. For :class:`graphxy` this

282

is a straight line.

283

284

285

.. method:: graphxy.vgeodesic_el(vx1, vy1, vx2, vy2)

286

287

Like :meth:`vgeodesic` but this method returns the path element to connect the

288

two points.

289

290

.. index::

291

single: xbasepath()@xbasepath() (graphxy method)

292

single: xvbasepath()@xvbasepath() (graphxy method)

293

single: xgridpath()@xgridpath() (graphxy method)

294

single: xvgridpath()@xvgridpath() (graphxy method)

295

single: xtickpoint()@xtickpoint() (graphxy method)

296

single: xvtickpoint()@xvtickpoint() (graphxy method)

297

single: xtickdirection()@xtickdirection() (graphxy method)

298

single: xvtickdirection()@xvtickdirection() (graphxy method)

299

single: ybasepath()@ybasepath() (graphxy method)

300

single: yvbasepath()@yvbasepath() (graphxy method)

301

single: ygridpath()@ygridpath() (graphxy method)

302

single: yvgridpath()@yvgridpath() (graphxy method)

303

single: ytickpoint()@ytickpoint() (graphxy method)

304

single: yvtickpoint()@yvtickpoint() (graphxy method)

305

single: ytickdirection()@ytickdirection() (graphxy method)

306

single: yvtickdirection()@yvtickdirection() (graphxy method)

307

308

Further geometry information is available by the :attr:`axes` instance variable,

309

with is a dictionary mapping axis names to :class:`anchoredaxis` instances.

310

Shortcuts to the anchoredaxis positioner methods for the ``x``\ - and ``y``\

311

-axis become available after :meth:`dolayout` as :class:`graphxy` methods

312

``Xbasepath``, ``Xvbasepath``, ``Xgridpath``, ``Xvgridpath``, ``Xtickpoint``,

313

``Xvtickpoint``, ``Xtickdirection``, and ``Xvtickdirection`` where the prefix

314

``X`` stands for ``x`` and ``y``.

315

316

317

.. method:: graphxy.axistrafo(axis, t)

318

319

This method can be used to apply a transformation *t* to an

320

:class:`anchoredaxis` instance *axis* to modify the axis position and the like.

321

This method fails when called on a not yet finished axis, i.e. it should be used

322

after :meth:`dolayout`.

323

324

325

.. method:: graphxy.axisatv(axis, v)

326

327

This method calls :meth:`axistrafo` with a transformation to move the axis

328

*axis* to a graph position *v* (in graph coordinates).

329

330

The class :class:`graphxyz` is very similar to the :class:`graphxy` class,

331

except for its additional dimension. In the following documentation only the

332

differences to the :class:`graphxy` class are described.

333

334

335

.. class:: graphxyz(xpos=0, ypos=0, size=None, xscale=1, yscale=1, zscale=1/goldenmean, projector=central(10, -30, 30), key=None, **axes)

336

337

This class provides an x-y-z-graph.

338

339

The position of the graph on its own canvas is specified by *xpos* and *ypos*.

340

The size of the graph is specified by *size* and the length factors *xscale*,

341

*yscale*, and *zscale*. The final size of the graph depends on the projector

342

*projector*, which is called with ``x``, ``y``, and ``z`` values up to *xscale*,

343

*yscale*, and *zscale* respectively and scaling the result by *size*. For a

344

parallel projector changing *size* is thus identical to changing *xscale*,

345

*yscale*, and *zscale* by the same factor. For the central projector the

346

projectors internal distance would also need to be changed by this factor. Thus

347

*size* changes the size of the whole graph without changing the projection.

348

349

*projector* defines the conversion of 3d coordinates to 2d coordinates. It can

350

be an instance of :class:`central` or :class:`parallel` described below.

351

352

*\*\*axes* receives axes instances as for :class:`graphxyz`. The graphxyz allows

353

for 4 axes per graph dimension ``x``, ``x2``, ``x3``, ``x4``, ``y``, ``y2``,

354

``y3``, ``y4``, ``z``, ``z2``, ``z3``, and ``z4``. The x-y-plane is the

355

horizontal plane at the bottom and the ``x``, ``x2``, ``y``, and ``y2`` axes are

356

placed at the boundary of this plane with ``x`` and ``y`` always being in front.

357

``x3``, ``x4``, ``y3``, and ``y4`` are handled similar, but for the top plane of

358

the graph. The ``z`` axis is placed at the origin of the ``x`` and ``y``

359

dimension, whereas ``z2`` is placed at the final point of the ``x`` dimension,

360

``z3`` at the final point of the ``y`` dimension and ``z4`` at the final point

361

of the ``x`` and ``y`` dimension together.

362

363

364

.. attribute:: graphxyz.central

365

366

The central attribute of the graphxyz is the :class:`central` class. See the

367

class description below.

368

369

370

.. attribute:: graphxyz.parallel

371

372

The parallel attribute of the graphxyz is the :class:`parallel` class. See the

373

class description below.

374

375

Regarding the 3d to 2d transformation the methods :meth:`pos`, :meth:`vpos`,

376

:meth:`vgeodesic`, and :meth:`vgeodesic_el` are available as for class

377

:class:`graphxy` and just take an additional argument for the dimension. Note

378

that a similar transformation method (3d to 2d) is available as part of the

379

projector as well already, but only the graph acknowledges its size, the scaling

380

and the internal tranformation of the graph coordinates to the scaled

381

coordinates. As the projector also implements a :meth:`zindex` and a

382

:meth:`angle` method, those are also available at the graph level in the graph

383

coordinate variant (i.e. having an additional v in its name and using values

384

from 0 to 1 per dimension).

385

386

387

.. method:: graphxyz.vzindex(vx, vy, vz)

388

389

The depths of the point defined by *vx*, *vy*, and *vz* scaled to a range [-1:1]

390

where 1 in closed to the viewer. All arguments passed to the method are in graph

391

coordinates with range [0:1].

392

393

394

.. method:: graphxyz.vangle(vx1, vy1, vz1, vx2, vy2, vz2, vx3, vy3, vz3)

395

396

The cosine of the angle of the view ray thru point ``(vx1, vy1, vz1)`` and the

397

plane defined by the points ``(vx1, vy1, vz1)``, ``(vx2, vy2, vz2)``, and

398

``(vx3, vy3, vz3)``. All arguments passed to the method are in graph coordinates

399

with range [0:1].

400

401

There are two projector classes :class:`central` and :class:`parallel`:

402

403

404

.. class:: central(distance, phi, theta, anglefactor=math.pi/180)

405

406

Instances of this class implement a central projection for the given parameters.

407

408

*distance* is the distance of the viewer from the origin. Note that the

409

:class:`graphxyz` class uses the range ``-xscale`` to ``xscale``, ``-yscale`` to

410

``yscale``, and ``-zscale`` to ``zscale`` for the coordinates ``x``, ``y``, and

411

``z``. As those scales are of the order of one (by default), the distance should

412

be of the order of 10 to give nice results. Smaller distances increase the

413

central projection character while for huge distances the central projection

414

becomes identical to the parallel projection.

415

416

``phi`` is the angle of the viewer in the x-y-plane and ``theta`` is the angle

417

of the viewer to the x-y-plane. The standard notation for spheric coordinates

418

are used. The angles are multiplied by *anglefactor* which is initialized to do

419

a degree in radiant transformation such that you can specify ``phi`` and

420

``theta`` in degree while the internal computation is always done in radiants.

421

422

423

.. class:: parallel(phi, theta, anglefactor=math.pi/180)

424

425

Instances of this class implement a parallel projection for the given

426

parameters. There is no distance for that transformation (compared to the

427

central projection). All other parameters are identical to the :class:`central`

428

class.

429

430

431

.. module:: graph.data

432

433

Module :mod:`graph.data`: Graph data

434

====================================

435

436

437

The following classes provide data for the :meth:`plot` method of a graph. The

438

classes are implemented in :mod:`graph.data`.

439

440

441

.. class:: file(filename, commentpattern=defaultcommentpattern, columnpattern=defaultcolumnpattern, stringpattern=defaultstringpattern, skiphead=0, skiptail=0, every=1, title=notitle, context={}, copy=1, replacedollar=1, columncallback="__column__", **columns)

442

443

This class reads data from a file and makes them available to the graph system.

444

*filename* is the name of the file to be read. The data should be organized in

445

columns.

446

447

The arguments *commentpattern*, *columnpattern*, and *stringpattern* are

448

responsible for identifying the data in each line of the file. Lines matching

449

*commentpattern* are ignored except for the column name search of the last non-

450

empty comment line before the data. By default a line starting with one of the

451

characters ``'#'``, ``'%'``, or ``'!'`` as well as an empty line is treated as a

452

comment.

453

454

A non-comment line is analysed by repeatedly matching *stringpattern* and,

455

whenever the stringpattern does not match, by *columnpattern*. When the

456

*stringpattern* matches, the result is taken as the value for the next column

457

without further transformations. When *columnpattern* matches, it is tried to

458

convert the result to a float. When this fails the result is taken as a string

459

as well. By default, you can write strings with spaces surrounded by ``'"'``

460

immediately surrounded by spaces or begin/end of line in the data file.

461

Otherwise ``'"'`` is not taken to be special.

462

463

*skiphead* and *skiptail* are numbers of data lines to be ignored at the

464

beginning and end of the file while *every* selects only every *every* line from

465

the data.

466

467

*title* is the title of the data to be used in the graph key. A default title is

468

constructed out of *filename* and *\*\*columns*. You may set *title* to ``None``

469

to disable the title.

470

471

Finally, *columns* define columns out of the existing columns from the file by a

472

column number or a mathematical expression (see below). When *copy* is set the

473

names of the columns in the file (file column names) and the freshly created

474

columns having the names of the dictionary key (data column names) are passed as

475

data to the graph styles. The data columns may hide file columns when names are

476

equal. For unset *copy* the file columns are not available to the graph styles.

477

478

File column names occur when the data file contains a comment line immediately

479

in front of the data (except for empty or empty comment lines). This line will

480

be parsed skipping the matched comment identifier as if the line would be

481

regular data, but it will not be converted to floats even if it would be

482

possible to convert the items. The result is taken as file column names, *i.e.*

483

a string representation for the columns in the file.

484

485

The values of *\*\*columns* can refer to column numbers in the file starting at

486

``1``. The column ``0`` is also available and contains the line number starting

487

from ``1`` not counting comment lines, but lines skipped by *skiphead*,

488

*skiptail*, and *every*. Furthermore values of *\*\*columns* can be strings:

489

file column names or complex mathematical expressions. To refer to columns

490

within mathematical expressions you can also use file column names when they are

491

valid variable identifiers. Equal named items in context will then be hidden.

492

Alternatively columns can be access by the syntax ``$<number>`` when

493

*replacedollar* is set. They will be translated into function calls to

494

*columncallback*, which is a function to access column data by index or name.

495

496

*context* allows for accessing external variables and functions when evaluating

497

mathematical expressions for columns. Additionally to the identifiers in

498

*context*, the file column names, the *columncallback* function and the

499

functions shown in the table "builtins in math expressions" at the end of the

500

section are available.

501

502

Example::

503

504

graph.data.file("test.dat", a=1, b="B", c="2*B+$3")

505

506

with :file:`test.dat` looking like::

507

508

# A B C

509

1.234 1 2

510

5.678 3 4

511

512

The columns with name ``"a"``, ``"b"``, ``"c"`` will become ``"[1.234,

513

5.678]"``, ``"[1.0, 3.0]"``, and ``"[4.0, 10.0]"``, respectively. The columns

514

``"A"``, ``"B"``, ``"C"`` will be available as well, since *copy* is enabled by

515

default.

516

517

When creating several data instances accessing the same file, the file is read

518

only once. There is an inherent caching of the file contents.

519

520

For the sake of completeness we list the default patterns:

521

522

523

.. attribute:: file.defaultcommentpattern

524

525

``re.compile(r"(#+|!+|%+)\s*")``

526

527

528

.. attribute:: file.defaultcolumnpattern

529

530

``re.compile(r"\"(.*?)\"(\s+|$)")``

531

532

533

.. attribute:: file.defaultstringpattern

534

535

``re.compile(r"(.*?)(\s+|$)")``

536

537

538

.. class:: function(expression, title=notitle, min=None, max=None, points=100, context={})

539

540

This class creates graph data from a function. *expression* is the mathematical

541

expression of the function. It must also contain the result variable name

542

including the variable the function depends on by assignment. A typical example

543

looks like ``"y(x)=sin(x)"``.

544

545

*title* is the title of the data to be used in the graph key. By default

546

*expression* is used. You may set *title* to ``None`` to disable the title.

547

548

*min* and *max* give the range of the variable. If not set, the range spans the

549

whole axis range. The axis range might be set explicitly or implicitly by ranges

550

of other data. *points* is the number of points for which the function is

551

calculated. The points are choosen linearly in terms of graph coordinates.

552

553

*context* allows for accessing external variables and functions. Additionally to

554

the identifiers in *context*, the variable name and the functions shown in the

555

table "builtins in math expressions" at the end of the section are available.

556

557

558

.. class:: paramfunction(varname, min, max, expression, title=notitle, points=100, context={})

559

560

This class creates graph data from a parametric function. *varname* is the

561

parameter of the function. *min* and *max* give the range for that variable.

562

*points* is the number of points for which the function is calculated. The

563

points are choosen lineary in terms of the parameter.

564

565

*expression* is the mathematical expression for the parametric function. It

566

contains an assignment of a tuple of functions to a tuple of variables. A

567

typical example looks like ``"x, y = cos(k), sin(k)"``.

568

569

*title* is the title of the data to be used in the graph key. By default

570

*expression* is used. You may set *title* to ``None`` to disable the title.

571

572

*context* allows for accessing external variables and functions. Additionally to

573

the identifiers in *context*, *varname* and the functions shown in the table

574

"builtins in math expressions" at the end of the section are available.

575

576

577

.. class:: values(title="user provided values", **columns)

578

579

This class creates graph data from externally provided data. Each column is a

580

list of values to be used for that column.

581

582

*title* is the title of the data to be used in the graph key.

583

584

585

.. class:: points(data, title="user provided points", addlinenumbers=1, **columns)

586

587

This class creates graph data from externally provided data. *data* is a list of

588

lines, where each line is a list of data values for the columns.

589

590

*title* is the title of the data to be used in the graph key.

591

592

The keywords of *\*\*columns* become the data column names. The values are the

593

column numbers starting from one, when *addlinenumbers* is turned on (the zeroth

594

column is added to contain a line number in that case), while the column numbers

595

starts from zero, when *addlinenumbers* is switched off.

596

597

598

.. class:: data(data, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)

599

600

This class provides graph data out of other graph data. *data* is the source of

601

the data. All other parameters work like the equally called parameters in

602

:class:`graph.data.file`. Indeed, the latter is built on top of this class by

603

reading the file and caching its contents in a :class:`graph.data.list`

604

instance.

605

606

607

.. class:: conffile(filename, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)

608

609

This class reads data from a config file with the file name *filename*. The

610

format of a config file is described within the documentation of the

611

:mod:`ConfigParser` module of the Python Standard Library.

612

613

Each section of the config file becomes a data line. The options in a section

614

are the columns. The name of the options will be used as file column names. All

615

other parameters work as in *graph.data.file* and *graph.data.data* since they

616

all use the same code.

617

618

619

.. class:: cbdfile(filename, minrank=None, maxrank=None, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns)

620

621

This is an experimental class to read map data from cbd-files. See

622

`<http://sepwww.stanford.edu/ftp/World_Map/>`_ for some world-map data.

623

624

The builtins in math expressions are listed in the following table:

625

626

+------------------+--------------------------------------------+

627

| name | value |

628

+==================+============================================+

629

| ``neg`` | ``lambda x: -x`` |

630

+------------------+--------------------------------------------+

631

| ``abs`` | ``lambda x: x < 0 and -x or x`` |

632

+------------------+--------------------------------------------+

633

| ``sgn`` | ``lambda x: x < 0 and -1 or 1`` |

634

+------------------+--------------------------------------------+

635

| ``sqrt`` | ``math.sqrt`` |

636

+------------------+--------------------------------------------+

637

| ``exp`` | ``math.exp`` |

638

+------------------+--------------------------------------------+

639

| ``log`` | ``math.log`` |

640

+------------------+--------------------------------------------+

641

| ``sin`` | ``math.sin`` |

642

+------------------+--------------------------------------------+

643

| ``cos`` | ``math.cos`` |

644

+------------------+--------------------------------------------+

645

| ``tan`` | ``math.tan`` |

646

+------------------+--------------------------------------------+

647

| ``asin`` | ``math.asin`` |

648

+------------------+--------------------------------------------+

649

| ``acos`` | ``math.acos`` |

650

+------------------+--------------------------------------------+

651

| ``atan`` | ``math.atan`` |

652

+------------------+--------------------------------------------+

653

| ``sind`` | ``lambda x: math.sin(math.pi/180*x)`` |

654

+------------------+--------------------------------------------+

655

| ``cosd`` | ``lambda x: math.cos(math.pi/180*x)`` |

656

+------------------+--------------------------------------------+

657

| ``tand`` | ``lambda x: math.tan(math.pi/180*x)`` |

658

+------------------+--------------------------------------------+

659

| ``asind`` | ``lambda x: 180/math.pi*math.asin(x)`` |

660

+------------------+--------------------------------------------+

661

| ``acosd`` | ``lambda x: 180/math.pi*math.acos(x)`` |

662

+------------------+--------------------------------------------+

663

| ``atand`` | ``lambda x: 180/math.pi*math.atan(x)`` |

664

+------------------+--------------------------------------------+

665

| ``norm`` | ``lambda x, y: math.hypot(x, y)`` |

666

+------------------+--------------------------------------------+

667

| ``splitatvalue`` | see the ``splitatvalue`` description below |

668

+------------------+--------------------------------------------+

669

| ``pi`` | ``math.pi`` |

670

+------------------+--------------------------------------------+

671

| ``e`` | ``math.e`` |

672

+------------------+--------------------------------------------+

673

674

``math`` refers to Pythons :mod:`math` module. The ``splitatvalue`` function is

675

defined as:

676

677

678

.. function:: splitatvalue(value, *splitpoints)

679

680

This method returns a tuple ``(section, value)``. The section is calculated by

681

comparing *value* with the values of splitpoints. If *splitpoints* contains only

682

a single item, ``section`` is ``0`` when value is lower or equal this item and

683

``1`` else. For multiple splitpoints, ``section`` is ``0`` when its lower or

684

equal the first item, ``None`` when its bigger than the first item but lower or

685

equal the second item, ``1`` when its even bigger the second item, but lower or

686

equal the third item. It continues to alter between ``None`` and ``2``, ``3``,

687

etc.

688

689

690

.. module:: graph.style

691

692

Module :mod:`graph.style`: Graph styles

693

=======================================

694

695

Please note that we are talking about graph styles here. Those are responsible

696

for plotting symbols, lines, bars and whatever else into a graph. Do not mix it

697

up with path styles like the line width, the line style (solid, dashed, dotted

698

*etc.*) and others.

699

700

The following classes provide styles to be used at the :meth:`plot` method of a

701

graph. The plot method accepts a list of styles. By that you can combine several

702

styles at the very same time.

703

704

Some of the styles below are hidden styles. Those do not create any output, but

705

they perform internal data handling and thus help on modularization of the

706

styles. Usually, a visible style will depend on data provided by one or more

707

hidden styles but most of the time it is not necessary to specify the hidden

708

styles manually. The hidden styles register themself to be the default for

709

providing certain internal data.

710

711

712

.. class:: pos(epsilon=1e-10)

713

714

This class is a hidden style providing a position in the graph. It needs a data

715

column for each graph dimension. For that the column names need to be equal to

716

an axis name. Data points are considered to be out of graph when their position

717

in graph coordinates exceeds the range [0:1] by more than *epsilon*.

718

719

720

.. class:: range(usenames=, epsilon=1e-10)

721

722

This class is a hidden style providing an errorbar range. It needs data column

723

names constructed out of a axis name ``X`` for each dimension errorbar data

724

should be provided as follows:

725

726

+-----------+---------------------------+

727

| data name | description |

728

+===========+===========================+

729

| ``Xmin`` | minimal value |

730

+-----------+---------------------------+

731

| ``Xmax`` | maximal value |

732

+-----------+---------------------------+

733

| ``dX`` | minimal and maximal delta |

734

+-----------+---------------------------+

735

| ``dXmin`` | minimal delta |

736

+-----------+---------------------------+

737

| ``dXmax`` | maximal delta |

738

+-----------+---------------------------+

739

740

When delta data are provided the style will also read column data for the axis

741

name ``X`` itself. *usenames* allows to insert a translation dictionary from

742

axis names to the identifiers ``X``.

743

744

*epsilon* is a comparison precision when checking for invalid errorbar ranges.

745

746

747

.. class:: symbol(symbol=changecross, size=0.2*unit.v_cm, symbolattrs=[])

748

749

This class is a style for plotting symbols in a graph. *symbol* refers to a

750

(changeable) symbol function with the prototype ``symbol(c, x_pt, y_pt, size_pt,

751

attrs)`` and draws the symbol into the canvas ``c`` at the position ``(x_pt,

752

y_pt)`` with size ``size_pt`` and attributes ``attrs``. Some predefined symbols

753

are available in member variables listed below. The symbol is drawn at size

754

*size* using *symbolattrs*. *symbolattrs* is merged with ``defaultsymbolattrs``

755

which is a list containing the decorator :class:`deco.stroked`. An instance of

756

:class:`symbol` is the default style for all graph data classes described in

757

section :mod:`graph.data` except for :class:`function` and

758

:class:`paramfunction`.

759

760

The class :class:`symbol` provides some symbol functions as member variables,

761

namely:

762

763

764

.. attribute:: symbol.cross

765

766

A cross. Should be used for stroking only.

767

768

769

.. attribute:: symbol.plus

770

771

A plus. Should be used for stroking only.

772

773

774

.. attribute:: symbol.square

775

776

A square. Might be stroked or filled or both.

777

778

779

.. attribute:: symbol.triangle

780

781

A triangle. Might be stroked or filled or both.

782

783

784

.. attribute:: symbol.circle

785

786

A circle. Might be stroked or filled or both.

787

788

789

.. attribute:: symbol.diamond

790

791

A diamond. Might be stroked or filled or both.

792

793

:class:`symbol` provides some changeable symbol functions as member variables,

794

namely:

795

796

797

.. attribute:: symbol.changecross

798

799

attr.changelist([cross, plus, square, triangle, circle, diamond])

800

801

802

.. attribute:: symbol.changeplus

803

804

attr.changelist([plus, square, triangle, circle, diamond, cross])

805

806

807

.. attribute:: symbol.changesquare

808

809

attr.changelist([square, triangle, circle, diamond, cross, plus])

810

811

812

.. attribute:: symbol.changetriangle

813

814

attr.changelist([triangle, circle, diamond, cross, plus, square])

815

816

817

.. attribute:: symbol.changecircle

818

819

attr.changelist([circle, diamond, cross, plus, square, triangle])

820

821

822

.. attribute:: symbol.changediamond

823

824

attr.changelist([diamond, cross, plus, square, triangle, circle])

825

826

827

.. attribute:: symbol.changesquaretwice

828

829

attr.changelist([square, square, triangle, triangle, circle, circle, diamond,

830

diamond])

831

832

833

.. attribute:: symbol.changetriangletwice

834

835

attr.changelist([triangle, triangle, circle, circle, diamond, diamond, square,

836

square])

837

838

839

.. attribute:: symbol.changecircletwice

840

841

attr.changelist([circle, circle, diamond, diamond, square, square, triangle,

842

triangle])

843

844

845

.. attribute:: symbol.changediamondtwice

846

847

attr.changelist([diamond, diamond, square, square, triangle, triangle, circle,

848

circle])

849

850

The class :class:`symbol` provides two changeable decorators for alternated

851

filling and stroking. Those are especially useful in combination with the

852

:meth:`change`\ -\ :meth:`twice`\ -symbol methods above. They are:

853

854

855

.. attribute:: symbol.changestrokedfilled

856

857

attr.changelist([deco.stroked, deco.filled])

858

859

860

.. attribute:: symbol.changefilledstroked

861

862

attr.changelist([deco.filled, deco.stroked])

863

864

865

.. class:: line(lineattrs=[])

866

867

This class is a style to stroke lines in a graph. *lineattrs* is merged with

868

``defaultlineattrs`` which is a list containing the member variable

869

``changelinestyle`` as described below. An instance of :class:`line` is the

870

default style of the graph data classes :class:`function` and

871

:class:`paramfunction` described in section :mod:`graph.data`.

872

873

The class :class:`line` provides a changeable line style. Its definition is:

874

875

876

.. attribute:: line.changelinestyle

877

878

attr.changelist([style.linestyle.solid, style.linestyle.dashed,

879

style.linestyle.dotted, style.linestyle.dashdotted])

880

881

882

.. class:: impulses(lineattrs=[], fromvalue=0, frompathattrs=[], valueaxisindex=1)

883

884

This class is a style to plot impulses. *lineattrs* is merged with

885

``defaultlineattrs`` which is a list containing the member variable

886

``changelinestyle`` of the :class:`line` class. *fromvalue* is the baseline

887

value of the impulses. When set to ``None``, the impulses will start at the

888

baseline. When fromvalue is set, *frompathattrs* are the stroke attributes used

889

to show the impulses baseline path.

890

891

892

.. class:: errorbar(size=0.1*unit.v_cm, errorbarattrs=[], epsilon=1e-10)

893

894

This class is a style to stroke errorbars in a graph. *size* is the size of the

895

caps of the errorbars and *errorbarattrs* are the stroke attributes. Errorbars

896

and error caps are considered to be out of the graph when their position in

897

graph coordinates exceeds the range [0:1] by more that *epsilon*. Out of graph

898

caps are omitted and the errorbars are cut to the valid graph range.

899

900

901

.. class:: text(textname="text", dxname=None, dyname=None, dxunit=0.3*unit.v_cm, dyunit=0.3*unit.v_cm, textdx=0*unit.v_cm, textdy=0.3*unit.v_cm, textattrs=[])

902

903

This class is a style to stroke text in a graph. The text to be written has to

904

be provided in the data column named ``textname``. *textdx* and *textdy* are the

905

position of the text with respect to the position in the graph. Alternatively

906

you can specify a ``dxname`` and a ``dyname`` and provide appropriate data in

907

those columns to be taken in units of *dxunit* and *dyunit* to specify the

908

position of the text for each point separately. *textattrs* are text attributes

909

for the output of the text. Those attributes are merged with the default

910

attributes ``textmodule.halign.center`` and ``textmodule.vshift.mathaxis``.

911

912

913

.. class:: arrow(linelength=0.25*unit.v_cm, arrowsize=0.15*unit.v_cm, lineattrs=[], arrowattrs=[], arrowpos=0.5, epsilon=1e-10, decorator=deco.earrow)

914

915

This class is a style to plot short lines with arrows into a two-dimensional

916

graph to a given graph position. The arrow parameters are defined by two

917

additional data columns named ``size`` and ``angle`` define the size and angle

918

for each arrow. ``size`` is taken as a factor to *arrowsize* and *linelength*,

919

the size of the arrow and the length of the line the arrow is plotted at.

920

``angle`` is the angle the arrow points to with respect to a horizontal line.

921

The ``angle`` is taken in degrees and used in mathematically positive sense.

922

*lineattrs* and *arrowattrs* are styles for the arrow line and arrow head,

923

respectively. *arrowpos* defines the position of the arrow line with respect to

924

the position at the graph. The default ``0.5`` means centered at the graph

925

position, whereas ``0`` and ``1`` creates the arrows to start or end at the

926

graph position, respectively. *epsilon* is used as a cutoff for short arrows in

927

order to prevent numerical instabilities. *decorator* defines the decorator to

928

be added to the line.

929

930

931

.. class:: rect(gradient=color.gradient.Grey)

932

933

This class is a style to plot colored rectangles into a two-dimensional graph.

934

The size of the rectangles is taken from the data provided by the :class:`range`

935

style. The additional data column named ``color`` specifies the color of the

936

rectangle defined by *gradient*. The valid color range is [0:1].

937

938

939

.. class:: histogram(lineattrs=[], steps=0, fromvalue=0, frompathattrs=[], fillable=0, rectkey=0, autohistogramaxisindex=0, autohistogrampointpos=0.5, epsilon=1e-10)

940

941

This class is a style to plot histograms. *lineattrs* is merged with

942

``defaultlineattrs`` which is ``[deco.stroked]``. When *steps* is set, the

943

histrogram is plotted as steps instead of the default being a boxed histogram.

944

*fromvalue* is the baseline value of the histogram. When set to ``None``, the

945

histogram will start at the baseline. When fromvalue is set, *frompathattrs* are

946

the stroke attributes used to show the histogram baseline path.

947

948

The *fillable* flag changes the stoke line of the histogram to make it fillable

949

properly. This is important on non-steped histograms or on histograms, which hit

950

the graph boundary. *rectkey* can be set to generate a rectanglar area instead

951

of a line in the graph key.

952

953

In the most general case, a histogram is defined by a range specification (like

954

for an errorbar) in one graph dimension (say, along the x-axis) and a value for

955

the other graph dimension. This allows for the widths of the histogram boxes

956

being variable. Often, however, all histogram bin ranges are equally sized, and

957

instead of passing the range, the position of the bin along the x-axis fully

958

specifies the histogram - assuming that there are at least two bins. This common

959

case is supported via two parameters: *autohistogramaxisindex*, which defines

960

the index of the independent histogram axis (in the case just described this

961

would be ``0`` designating the x axis). *autohistogrampointpos*, defines the

962

relative position of the center of the histogram bin: ``0.5`` means that the bin

963

is centered at the values passed to the style, ``0`` (``1``) means that the bin

964

is aligned at the right-(left-)hand side.

965

966

XXX describe, how to specify general histograms with varying bin widths

967

968

Positions of the histograms are considered to be out of graph when they exceed

969

the graph coordinate range [0:1] by more than *epsilon*.

970

971

972

.. class:: barpos(fromvalue=None, frompathattrs=[], epsilon=1e-10)

973

974

This class is a hidden style providing position information in a bar graph.

975

Those graphs need to contain a specialized axis, namely a bar axis. The data

976

column for this bar axis is named ``Xname`` where ``X`` is an axis name. In the

977

other graph dimension the data column name must be equal to an axis name. To

978

plot several bars in a single graph side by side, you need to have a nested bar

979

axis and provide a tuple as data for nested bar axis.

980

981

The bars start at *fromvalue* when provided. The *fromvalue* is marked by a

982

gridline stroked using *frompathattrs*. Thus this hidden style might actually

983

create some output. The value of a bar axis is considered to be out of graph

984

when its position in graph coordinates exceeds the range [0:1] by more than

985

*epsilon*.

986

987

988

.. class:: stackedbarpos(stackname, addontop=0, epsilon=1e-10)

989

990

This class is a hidden style providing position information in a bar graph by

991

stacking a new bar on top of another bar. The value of the new bar is taken from

992

the data column named *stackname*. When *addontop* is set, the values is taken

993

relative to the previous top of the bar.

994

995

996

.. class:: bar(barattrs=[], epsilon=1e-10, gradient=color.gradient.RedBlack)

997

998

This class draws bars in a bar graph. The bars are filled using *barattrs*.

999

*barattrs* is merged with ``defaultbarattrs`` which is a list containing

1000

``[color.gradient.Rainbow, deco.stroked([color.grey.black])]``.

1001

1002

The bar style has limited support for 3d graphs: Occlusion does not work

1003

properly on stacked bars or multiple dataset. *epsilon* is used in 3d to prevent

1004

numerical instabilities on bars without hight. When *gradient* is not ``None``

1005

it is used to calculate a lighting coloring taking into account the angle

1006

between the view ray and the bar and the distance between viewer and bar. The

1007

precise conversion is defined in the :meth:`lighting` method.

1008

1009

1010

.. class:: changebar(barattrs=[])

1011

1012

This style works like the :class:`bar` style, but instead of the *barattrs* to

1013

be changed on subsequent data instances the *barattrs* are changed for each

1014

value within a single data instance. In the result the style can't be applied to

1015

several data instances and does not support 3d. The style raises an error

1016

instead.

1017

1018

1019

.. class:: gridpos(index1=0, index2=1, gridlines1=1, gridlines2=1, gridattrs=[], epsilon=1e-10)

1020

1021

This class is a hidden style providing rectangular grid information out of graph

1022

positions for graph dimensions *index1* and *index2*. Data points are considered

1023

to be out of graph when their position in graph coordinates exceeds the range

1024

[0:1] by more than *epsilon*. Data points are merged to a single graph

1025

coordinate value when their difference in graph coordinates is below *epsilon*.

1026

1027

1028

.. class:: grid(gridlines1=1, gridlines2=1, gridattrs=[])

1029

1030

Strokes a rectangular grid in the first grid direction, when *gridlines1* is set

1031

and in the second grid direction, when *gridlines2* is set. *gridattrs* is

1032

merged with ``defaultgridattrs`` which is a list containing the member variable

1033

``changelinestyle`` of the :class:`line` class.

1034

1035

1036

.. class:: surface(colorname="color", gradient=color.gradient.Grey, mincolor=None, maxcolor=None, gridlines1=0.05, gridlines2=0.05, gridcolor=None, backcolor=color.gray.black)

1037

1038

Draws a surface of a rectangular grid. Each rectangle is divided into 4

1039

triangles.

1040

1041

The grid can be colored using values provided by the data column named

1042

*colorname*. The values are rescaled to the range [0:1] using mincolor and

1043

maxcolor (which are taken from the minimal and maximal values, but larger bounds

1044

could be set).

1045

1046

If no *colorname* column exists, the surface style falls back to a lighting

1047

coloring taking into account the angle between the view ray and the triangle and

1048

the distance between viewer and triangle. The precise conversion is defined in

1049

the :meth:`lighting` method.

1050

1051

If a *gridcolor* is set, the rectangular grid is marked by small stripes of the

1052

relative (compared to each rectangle) size of *gridlines1* and *gridlines2* for

1053

the first and second grid direction, respectively.

1054

1055

*backcolor* is used to fill triangles shown from the back. If *backcolor* is set

1056

to ``None``, back sides are not drawn differently from the front sides.

1057

1058

The surface is encoded using a single mesh. While this is quite space efficient,

1059

it has the following implications:

1060

1061

* All colors must use the same color space.

1062

1063

* HSB colors are not allowed, whereas Gray, RGB, and CMYK are allowed. You can

1064

convert HSB colors into a different color space before passing them to the

1065

surface.

1066

1067

* The grid itself is also constructed out of triangles. The grid is transformed

1068

along with the triangles thus looking quite different from a stroked grid (as

1069

done by the grid style).

1070

1071

* Occlusion is handled by proper painting order.

1072

1073

* Color changes are continuous (in the selected color space) for each triangle.

1074

1075

1076

1077

.. module:: graph.key

1078

1079

Module :mod:`graph.key`: Graph keys

1080

===================================

1081

1082

The following class provides a key, whose instances can be passed to the

1083

constructor keyword argument ``key`` of a graph. The class is implemented in

1084

:mod:`graph.key`.

1085

1086

1087

.. class:: key(dist=0.2*unit.v_cm, pos="tr", hpos=None, vpos=None, hinside=1, vinside=1, hdist=0.6*unit.v_cm, vdist=0.4*unit.v_cm, symbolwidth=0.5*unit.v_cm, symbolheight=0.25*unit.v_cm, symbolspace=0.2*unit.v_cm, textattrs=[], columns=1, columndist=0.5*unit.v_cm, border=0.3*unit.v_cm, keyattrs=None)

1088

1089

This class writes the title of the data in a plot together with a small

1090

illustration of the style. The style is responsible for its illustration.

1091

1092

*dist* is a visual length and a distance between the key entries. *pos* is the

1093

position of the key with respect to the graph. Allowed values are combinations

1094

of ``"t"`` (top), ``"m"`` (middle) and ``"b"`` (bottom) with ``"l"`` (left),

1095

``"c"`` (center) and ``"r"`` (right). Alternatively, you may use *hpos* and

1096

*vpos* to specify the relative position using the range [0:1]. *hdist* and

1097

*vdist* are the distances from the specified corner of the graph. *hinside* and

1098

*vinside* are numbers to be set to 0 or 1 to define whether the key should be

1099

placed horizontally and vertically inside of the graph or not.

1100

1101

*symbolwidth* and *symbolheight* are passed to the style to control the size of

1102

the style illustration. *symbolspace* is the space between the illustration and

1103

the text. *textattrs* are attributes for the text creation. They are merged with

1104

``[text.vshift.mathaxis]``.

1105

1106

*columns* is a number of columns of the graph key and *columndist* is the

1107

distance between those columns.

1108

1109

When *keyattrs* is set to contain some draw attributes, the graph key is

1110

enlarged by *border* and the key area is drawn using *keyattrs*.

1111

1112

Older »