Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit72d6bed

Browse files
authored
Merge pull request#14654 from timhoffm/doc-scale
Cleanup of docstrings of scales
2 parentsf0b110e +9b1a26f commit72d6bed

File tree

2 files changed

+95
-87
lines changed

2 files changed

+95
-87
lines changed

‎lib/matplotlib/scale.py

Lines changed: 66 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
"""
2+
Scales define the distribution of data values on an axis, e.g. a log scaling.
3+
4+
They are attached to an `~.axis.Axis` and hold a `.Transform`, which is
5+
responsible for the actual data transformation.
6+
7+
See also `.axes.Axes.set_xscale` and the scales examples in the documentation.
8+
"""
9+
110
importinspect
211
importtextwrap
312

@@ -20,12 +29,14 @@ class ScaleBase:
2029
2130
Any subclasses will want to override:
2231
23-
- :attr:`name`
24-
- :meth:`get_transform`
25-
- :meth:`set_default_locators_and_formatters`
32+
- :attr:`name`
33+
- :meth:`get_transform`
34+
- :meth:`set_default_locators_and_formatters`
2635
2736
And optionally:
28-
- :meth:`limit_range_for_scale`
37+
38+
- :meth:`limit_range_for_scale`
39+
2940
"""
3041

3142
def__init__(self,axis,**kwargs):
@@ -51,9 +62,8 @@ def get_transform(self):
5162

5263
defset_default_locators_and_formatters(self,axis):
5364
"""
54-
Set the :class:`~matplotlib.ticker.Locator` and
55-
:class:`~matplotlib.ticker.Formatter` objects on the given
56-
axis to match this scale.
65+
Set the locators and formatters of *axis* to instances suitable for
66+
this scale.
5767
"""
5868
raiseNotImplementedError()
5969

@@ -63,7 +73,7 @@ def limit_range_for_scale(self, vmin, vmax, minpos):
6373
domain supported by this scale.
6474
6575
*minpos* should be the minimum positive value in the data.
66-
This is used by log scales to determine a minimum value.
76+
This is used by log scales to determine a minimum value.
6777
"""
6878
returnvmin,vmax
6979

@@ -84,10 +94,7 @@ def __init__(self, axis, **kwargs):
8494
super().__init__(axis,**kwargs)
8595

8696
defset_default_locators_and_formatters(self,axis):
87-
"""
88-
Set the locators and formatters to reasonable defaults for
89-
linear scaling.
90-
"""
97+
# docstring inherited
9198
axis.set_major_locator(AutoLocator())
9299
axis.set_major_formatter(ScalarFormatter())
93100
axis.set_minor_formatter(NullFormatter())
@@ -100,8 +107,8 @@ def set_default_locators_and_formatters(self, axis):
100107

101108
defget_transform(self):
102109
"""
103-
Thetransform for linear scaling is just the
104-
:class:`~matplotlib.transforms.IdentityTransform`.
110+
Return thetransform for linear scaling, which is just the
111+
`~matplotlib.transforms.IdentityTransform`.
105112
"""
106113
returnIdentityTransform()
107114

@@ -157,8 +164,8 @@ def __init__(self, axis, functions):
157164
"""
158165
Parameters
159166
----------
160-
axis: theaxis for the scale
161-
167+
axis : `~matplotlib.axis.Axis`
168+
The axis for the scale.
162169
functions : (callable, callable)
163170
two-tuple of the forward and inverse functions for the scale.
164171
The forward function must be monotonic.
@@ -172,16 +179,11 @@ def forward(values: array-like) -> array-like
172179
self._transform=transform
173180

174181
defget_transform(self):
175-
"""
176-
The transform for arbitrary scaling
177-
"""
182+
"""Return the `.FuncTransform` associated with this scale."""
178183
returnself._transform
179184

180185
defset_default_locators_and_formatters(self,axis):
181-
"""
182-
Set the locators and formatters to the same defaults as the
183-
linear scale.
184-
"""
186+
# docstring inherited
185187
axis.set_major_locator(AutoLocator())
186188
axis.set_major_formatter(ScalarFormatter())
187189
axis.set_minor_formatter(NullFormatter())
@@ -293,7 +295,7 @@ def transform_non_affine(self, a):
293295
# Ignore invalid values due to nans being passed to the transform.
294296
withnp.errstate(divide="ignore",invalid="ignore"):
295297
log= {np.e:np.log,2:np.log2,10:np.log10}.get(self.base)
296-
iflog:# If possible, do everything in a single call toNumpy.
298+
iflog:# If possible, do everything in a single call toNumPy.
297299
out=log(a)
298300
else:
299301
out=np.log(a)
@@ -354,20 +356,20 @@ class LogScale(ScaleBase):
354356

355357
def__init__(self,axis,**kwargs):
356358
"""
357-
*basex*/*basey*:
358-
The base of the logarithm
359-
360-
*nonposx*/*nonposy*: {'mask', 'clip'}
361-
non-positive values in *x* or *y* can be masked as
362-
invalid, or clipped to a very small positive number
363-
364-
*subsx*/*subsy*:
365-
Where to place the subticks between each major tick.
366-
Should be asequence ofintegers. For example, in a log10
367-
scale: ``[2, 3, 4, 5, 6, 7, 8, 9]``
368-
369-
will place 8 logarithmically spaced minor ticks between
370-
each major tick.
359+
Parameters
360+
----------
361+
axis : `~matplotlib.axis.Axis`
362+
The axis for the scale.
363+
basex, basey : float, default: 10
364+
The base of the logarithm.
365+
nonposx, nonposy : {'clip', 'mask'}, default: 'clip'
366+
Determines the behavior for non-positive values. They can either
367+
be masked as invalid, or clipped to a very small positive number.
368+
subsx, subsy :sequence ofint, default: None
369+
Where to place the subticks between each major tick.
370+
For example, in a log10 scale: ``[2, 3, 4, 5, 6, 7, 8, 9]``
371+
will place 8 logarithmically spaced minor ticks between
372+
each major tick.
371373
"""
372374
ifaxis.axis_name=='x':
373375
base=kwargs.pop('basex',10.0)
@@ -397,10 +399,7 @@ def base(self):
397399
returnself._transform.base
398400

399401
defset_default_locators_and_formatters(self,axis):
400-
"""
401-
Set the locators and formatters to specialized versions for
402-
log scaling.
403-
"""
402+
# docstring inherited
404403
axis.set_major_locator(LogLocator(self.base))
405404
axis.set_major_formatter(LogFormatterSciNotation(self.base))
406405
axis.set_minor_locator(LogLocator(self.base,self.subs))
@@ -409,16 +408,11 @@ def set_default_locators_and_formatters(self, axis):
409408
labelOnlyBase=(self.subsisnotNone)))
410409

411410
defget_transform(self):
412-
"""
413-
Return a :class:`~matplotlib.transforms.Transform` instance
414-
appropriate for the given logarithm base.
415-
"""
411+
"""Return the `.LogTransform` associated with this scale."""
416412
returnself._transform
417413

418414
deflimit_range_for_scale(self,vmin,vmax,minpos):
419-
"""
420-
Limit the domain to positive values.
421-
"""
415+
"""Limit the domain to positive values."""
422416
ifnotnp.isfinite(minpos):
423417
minpos=1e-300# Should rarely (if ever) have a visible effect.
424418

@@ -438,8 +432,8 @@ def __init__(self, axis, functions, base=10):
438432
"""
439433
Parameters
440434
----------
441-
axis: theaxis for the scale
442-
435+
axis : `matplotlib.axis.Axis`
436+
The axis for the scale.
443437
functions : (callable, callable)
444438
two-tuple of the forward and inverse functions for the scale.
445439
The forward function must be monotonic.
@@ -461,9 +455,7 @@ def base(self):
461455
returnself._transform._b.base# Base of the LogTransform.
462456

463457
defget_transform(self):
464-
"""
465-
The transform for arbitrary scaling
466-
"""
458+
"""Return the `.Transform` associated with this scale."""
467459
returnself._transform
468460

469461

@@ -592,20 +584,15 @@ def __init__(self, axis, **kwargs):
592584
self.subs=subs
593585

594586
defset_default_locators_and_formatters(self,axis):
595-
"""
596-
Set the locators and formatters to specialized versions for
597-
symmetrical log scaling.
598-
"""
587+
# docstring inherited
599588
axis.set_major_locator(SymmetricalLogLocator(self.get_transform()))
600589
axis.set_major_formatter(LogFormatterSciNotation(self.base))
601590
axis.set_minor_locator(SymmetricalLogLocator(self.get_transform(),
602591
self.subs))
603592
axis.set_minor_formatter(NullFormatter())
604593

605594
defget_transform(self):
606-
"""
607-
Return a :class:`SymmetricalLogTransform` instance.
608-
"""
595+
"""Return the `.SymmetricalLogTransform` associated with this scale."""
609596
returnself._transform
610597

611598

@@ -669,19 +656,23 @@ class LogitScale(ScaleBase):
669656

670657
def__init__(self,axis,nonpos='mask'):
671658
"""
672-
*nonpos*: {'mask', 'clip'}
673-
values beyond ]0, 1[ can be masked as invalid, or clipped to a number
674-
very close to 0 or 1
659+
Parameters
660+
----------
661+
axis : `matplotlib.axis.Axis`
662+
Currently unused.
663+
nonpos : {'mask', 'clip'}
664+
Determines the behavior for values beyond the open interval ]0, 1[.
665+
They can either be masked as invalid, or clipped to a number very
666+
close to 0 or 1.
675667
"""
676668
self._transform=LogitTransform(nonpos)
677669

678670
defget_transform(self):
679-
"""
680-
Return a :class:`LogitTransform` instance.
681-
"""
671+
"""Return the `.LogitTransform` associated with this scale."""
682672
returnself._transform
683673

684674
defset_default_locators_and_formatters(self,axis):
675+
# docstring inherited
685676
# ..., 0.01, 0.1, 0.5, 0.9, 0.99, ...
686677
axis.set_major_locator(LogitLocator())
687678
axis.set_major_formatter(LogitFormatter())
@@ -709,6 +700,7 @@ def limit_range_for_scale(self, vmin, vmax, minpos):
709700

710701

711702
defget_scale_names():
703+
"""Return the names of the available scales."""
712704
returnsorted(_scale_mapping)
713705

714706

@@ -719,22 +711,26 @@ def scale_factory(scale, axis, **kwargs):
719711
Parameters
720712
----------
721713
scale : {%(names)s}
722-
axis : Axis
714+
axis :`matplotlib.axis.Axis`
723715
"""
724716
scale=scale.lower()
725717
cbook._check_in_list(_scale_mapping,scale=scale)
726718
return_scale_mapping[scale](axis,**kwargs)
727719

720+
728721
ifscale_factory.__doc__:
729722
scale_factory.__doc__=scale_factory.__doc__% {
730-
"names":", ".join(get_scale_names())}
723+
"names":", ".join(map(repr,get_scale_names()))}
731724

732725

733726
defregister_scale(scale_class):
734727
"""
735728
Register a new kind of scale.
736729
737-
*scale_class* must be a subclass of :class:`ScaleBase`.
730+
Parameters
731+
----------
732+
scale_class : subclass of `ScaleBase`
733+
The scale to register.
738734
"""
739735
_scale_mapping[scale_class.name]=scale_class
740736

‎lib/matplotlib/transforms.py

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1188,18 +1188,18 @@ class Transform(TransformNode):
11881188
Subclasses of this class should override the following members (at
11891189
minimum):
11901190
1191-
- :attr:`input_dims`
1192-
- :attr:`output_dims`
1193-
- :meth:`transform`
1194-
- :attr:`is_separable`
1195-
- :attr:`has_inverse`
1196-
- :meth:`inverted` (if :attr:`has_inverse` is True)
1191+
- :attr:`input_dims`
1192+
- :attr:`output_dims`
1193+
- :meth:`transform`
1194+
- :attr:`is_separable`
1195+
- :attr:`has_inverse`
1196+
- :meth:`inverted` (if :attr:`has_inverse` is True)
11971197
11981198
If the transform needs to do something non-standard with
11991199
:class:`matplotlib.path.Path` objects, such as adding curves
12001200
where there were once line segments, it should override:
12011201
1202-
- :meth:`transform_path`
1202+
- :meth:`transform_path`
12031203
"""
12041204
input_dims=None
12051205
"""
@@ -1403,11 +1403,17 @@ def transform_affine(self, values):
14031403
affine transformations, this is equivalent to
14041404
``transform(values)``.
14051405
1406-
Accepts a numpy array of shape (N x :attr:`input_dims`) and
1407-
returns a numpy array of shape (N x :attr:`output_dims`).
1406+
Parameters
1407+
----------
1408+
values : array
1409+
The input values as NumPy array of length :attr:`input_dims` or
1410+
shape (N x :attr:`input_dims`).
14081411
1409-
Alternatively, accepts a numpy array of length :attr:`input_dims`
1410-
and returns a numpy array of length :attr:`output_dims`.
1412+
Returns
1413+
-------
1414+
values : array
1415+
The output values as NumPy array of length :attr:`input_dims` or
1416+
shape (N x :attr:`output_dims`), depending on the input.
14111417
"""
14121418
returnself.get_affine().transform(values)
14131419

@@ -1422,11 +1428,17 @@ def transform_non_affine(self, values):
14221428
``transform(values)``. In affine transformations, this is
14231429
always a no-op.
14241430
1425-
Accepts a numpy array of shape (N x :attr:`input_dims`) and
1426-
returns a numpy array of shape (N x :attr:`output_dims`).
1431+
Parameters
1432+
----------
1433+
values : array
1434+
The input values as NumPy array of length :attr:`input_dims` or
1435+
shape (N x :attr:`input_dims`).
14271436
1428-
Alternatively, accepts a numpy array of length :attr:`input_dims`
1429-
and returns a numpy array of length :attr:`output_dims`.
1437+
Returns
1438+
-------
1439+
values : array
1440+
The output values as NumPy array of length :attr:`input_dims` or
1441+
shape (N x :attr:`output_dims`), depending on the input.
14301442
"""
14311443
returnvalues
14321444

@@ -1558,11 +1570,11 @@ def inverted(self):
15581570
"""
15591571
Return the corresponding inverse transformation.
15601572
1573+
It holds ``x == self.inverted().transform(self.transform(x))``.
1574+
15611575
The return value of this method should be treated as
15621576
temporary. An update to *self* does not cause a corresponding
15631577
update to its inverted copy.
1564-
1565-
``x === self.inverted().transform(self.transform(x))``
15661578
"""
15671579
raiseNotImplementedError()
15681580

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp