
    rh:#                       S r SSKJr  / SQrSSKrSSKrSSKJr  SSKJ	r	  SSK
Jr  SSK
Jr  SS	K
Jr  SS
K
Jr  SSK
Jr  \R                   (       a  SSKJr  \	R$                  " S5      r    S   SS jjr " S S\R*                  5      r " S S\R*                  5      r\/r\S:X  a  SSKr\R4                  " \5        gg)aC  
Tools for graphing, plotting, or otherwise visualizing :class:`~music21.stream.Stream` objects.

The easiest and most common way of using plotting functions is to call
`.plot('typeOfGraph')` on a Stream.  See :meth:`~music21.stream.Stream.plot`.
That method uses tools from the `music21.graph.findPlot` module to map between
names of plots and classes that can show them.

The :class:`~music21.graph.plot.PlotStream`
subclasses in the `music21.graph.plot` module give easy to use
and configurable ways of graphing data and structures in
:class:`~music21.stream.Stream` objects.  These Plot objects use classes from
the `music21.graph.axis` module to automatically extract relevant data for you.

At a lower level, the :class:`~music21.graph.primitives.Graph` subclasses
in the `music21.graph.primitives` modules give abstract fundamental
graphing archetypes using the matplotlib library.  They are to be used when
you already have data extracted on your own but still want to take advantage
of musically-aware axes and scaling.

From highest level to lowest level usage, ways of graphing are as follows:

    1. `streamObj.plot('graphName')`
    2. `graph.plot.Class(streamObj).run()`
    3. `plotter = graph.primitives.Class(); plotter.data = ...; plotter.process()`
    4. Use `matplotlib` directly to create any graph, musical or non-musical.
    )annotations)axisfindPlotplot
primitives	utilities
plotStreamN)common)environment)r   )r   )r   )r   )r   streamgraphc           
     N   [         R                  " XX45      nSnU H  n[        R                  " U5      (       d  Un	Sn
OUu  pU	" U 40 UD6nU
(       a>  U
R	                  5        H*  u  pSUR                  5       -   n[        X}U" X{5      5        M,     UR                  5         M     U$ )a
  
Given a stream and any keyword configuration arguments, create and display a plot.

Note: plots require matplotlib to be installed.

Plot methods can be specified as additional arguments or by keyword.
Two keyword arguments can be given: `format` and `values`.
If positional arguments are given, the first is taken as `format`
and the rest are collected as `values`. If `format` is the class
name, that class is collected. Additionally, every
:class:`~music21.graph.PlotStream` subclass defines one `format`
string and a list of `values` strings. The `format` parameter
defines the type of Graph (e.g. scatter, histogram, colorGrid). The
`values` list defines what values are graphed
(e.g. quarterLength, pitch, pitchClass).

If a user provides a `format` and one or more `values` strings, a plot with
the corresponding profile, if found, will be generated. If not, the first
Plot to match any of the defined specifiers will be created.

In the case of :class:`~music21.graph.PlotWindowedAnalysis` subclasses,
the :class:`~music21.analysis.discrete.DiscreteAnalysis`
subclass :attr:`~music21.analysis.discrete.DiscreteAnalysis.identifiers` list
is added to the Plot's `values` list.

Available plots include the following:

* :class:`~music21.graph.plot.HistogramPitchSpace`
* :class:`~music21.graph.plot.HistogramPitchClass`
* :class:`~music21.graph.plot.HistogramQuarterLength`
* :class:`~music21.graph.plot.ScatterPitchSpaceQuarterLength`
* :class:`~music21.graph.plot.ScatterPitchClassQuarterLength`
* :class:`~music21.graph.plot.ScatterPitchClassOffset`
* :class:`~music21.graph.plot.ScatterPitchSpaceDynamicSymbol`
* :class:`~music21.graph.plot.HorizontalBarPitchSpaceOffset`
* :class:`~music21.graph.plot.HorizontalBarPitchClassOffset`
* :class:`~music21.graph.plot.ScatterWeightedPitchSpaceQuarterLength`
* :class:`~music21.graph.plot.ScatterWeightedPitchClassQuarterLength`
* :class:`~music21.graph.plot.ScatterWeightedPitchSpaceDynamicSymbol`
* :class:`~music21.graph.plot.Plot3DBarsPitchSpaceQuarterLength`
* :class:`~music21.graph.plot.WindowedKey`
* :class:`~music21.graph.plot.WindowedAmbitus`
* :class:`~music21.graph.plot.Dolan`


>>> s = corpus.parse('bach/bwv324.xml') #_DOCS_HIDE
>>> thePlot = s.plot('histogram', 'pitch', doneAction=None) #_DOCS_HIDE
>>> #_DOCS_SHOW s = corpus.parse('bach/bwv57.8')
>>> #_DOCS_SHOW thePlot = s.plot('histogram', 'pitch')

.. image:: images/HistogramPitchSpace.*
    :width: 600


>>> s = corpus.parse('bach/bwv324.xml') #_DOCS_HIDE
>>> thePlot = s.plot('pianoroll', doneAction=None) #_DOCS_HIDE
>>> #_DOCS_SHOW s = corpus.parse('bach/bwv57.8')
>>> #_DOCS_SHOW thePlot = s.plot('pianoroll')

.. image:: images/HorizontalBarPitchSpaceOffset.*
    :width: 600

Nr   )r   getPlotsToMaker
   
isIterableitemsuppersetattrrun)	streamObjgraphFormatxValueyValuezValuekeywordsplotMakeobjplotInfoplotClassNameplotDictaxisName	axisClassattrNames                 P/home/james-whalen/.local/lib/python3.13/site-packages/music21/graph/__init__.pyr	   r	   C   s    N &&{FKH C  **$MH&.#MI22'/~~'7#!HNN$44y'?@ (8 		  J    c                      \ rS rSrSrS rSrg)TestExternal   Tc                2   SSK Jn  SSK Jn  UR                  S5      nUR                  S   R                  SUR                  S5      5        UR                  S   R                  SUR                  S5      5        U R                  (       a  [        US5        g g )	Nr   corpusdynamicsbach/bwv57.8mf
   fall)	music21r+   r-   parsepartsinsertDynamicshowr	   )selfr+   r-   as       r$   testAllTestExternal.testAll   sr    "$LL(	
!X--d34	
"h..s3499q%  r%    N)__name__
__module____qualname____firstlineno__r8   r;   __static_attributes__r=   r%   r$   r'   r'      s    D!r%   r'   c                  ,    \ rS rSrS rS rS rS rSrg)Test   c                2    SSK Jn  U" U [        5       5        g )Nr   )testCopyAll)music21.test.commonTestrG   globals)r9   rG   s     r$   testCopyAndDeepcopyTest.testCopyAndDeepcopy   s    7D')$r%   c                b    SSK Jn  UR                  S5      n[        UR	                  5       S S9  g )Nr   r*   r.   )
doneAction)r3   r+   r4   r	   flatten)r9   r+   r:   s      r$   r;   Test.testAll   s#    "LL(199;40r%   c                   SSK Jn  SSK Jn  SSK Jn  SSK Jn  UR                  S5      nUR                  " 5       nUR                  UR                  S5      5        UR                  UR                  S5      5        UR                  UR                  SS	S
S95        UR                  UR                  S5      5        UR                  UR                  SSSS95        UR                  UR                  S5      5        UR                  UR                  SSSS95        UR                  UR                  SSSS95        UR                  UR                  SSS95        S H  u  pxn	UR                  XxU	S S9  M     g )Nr   r,   )noter   )scalec4r1   e3a3g      ?)quarterLengthr/   b3e4g      ?ppf4g5   c5))	histogrampitchN)r^   
pitchclassN)r^   quarterlengthN)scatterr_   ra   )rb   
pitchspaceoffset)rb   r_   rd   )rb   r-   N)barr_   N)re   pcN)weightedrf   duration)rg   r-   N)r   r   rM   )r3   r-   rQ   r   rR   
MajorScaleStreamappendr7   NotegetChordr   )
r9   r-   rQ   r   rR   scsplotTyper   r   s
             r$   testPlotChordsCTest.testPlotChordsC   s,   $ "!d#MMO	!!#&'	4!	T4s;<	!!$'(	T4s;<	!!$'(	T4q9:	T4q9:	4q12)
$Hf FF86dFK)
r%   c                L   SSK Jn  SSK Jn  SSK Jn  UR	                  S5      n/ SQnSnUR
                   HY  nUR                  UR                  5       H7  nUR                  SUR                  XV[        U5      -     5      5        US-  nM9     M[     UR                  SS	S	S S
9  g )Nr   r*   r,   r   zbwv66.6)pr/   r1   ffmpfffppp   dolanT)fillByMeasuresegmentByTargetrM   )r3   r+   r-   r   r4   r5   getElementsByClassMeasurer6   r7   lenr   )	r9   r+   r-   r   ro   dynirt   ms	            r$   testHorizontalInstrumentationB#Test.testHorizontalInstrumentationB   s    "$"LL#8A))&..9H,,SSX->?@Q :  	
wdDTRr%   r=   N)	r>   r?   r@   rA   rJ   r;   rq   r   rB   r=   r%   r$   rD   rD      s    %1
!LFSr%   rD   __main__)NNNN)r   zstream.Streamr   z
str | None)__doc__
__future__r   __all__typingtunittestr3   r
   r   music21.graphr   r   r   r   r   TYPE_CHECKINGr   EnvironmentenvironLocalr	   TestCaser'   rD   
_DOC_ORDERr>   mainTestr=   r%   r$   <module>r      s   6 #
      "  $ # ?? &&w/
 !XXXv
!8$$ 
!9S8 9Sz \
 zT r%   