2. Usage¶

RP Scripts has a Command Line Interface and a structure for Package usage.

2.1. Components¶

RP Scripts comprises the following programs:

Calculator
Plotter
Annotator
Labeler
Info
Utils
Stats
Converter
Trimmer

2.2. Command Line Interface¶

rpscript provides a high-level command line interface for the rhythmic partitioning tasks. Each program has a specific command line.

The command line below calls the help page.

rpscripts -h

This command outputs:

usage: rpscripts [-h] [-v]
                {calc,plot,annotate,label,info,utils,stats,convert,trim}
                ...

Rhythmic Partitioning Scripts.

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

Subcommands:
  Available subcommands

  {calc,plot,annotate,label,info,utils,stats,convert,trim}
    calc                Calculator
    plot                Charts plotter
    annotate            Digital score annotator
    label               JSON file labeler. Annotate JSON file with given
                        labels
    info                JSON data info.
    utils               Auxiliary tools
    stats               Statistical tools
    convert             JSON file converter. Convert JSON to CSV file
    trim                JSON file trimmer. Trim given measures

Further information available at https://github.com/msampaio/rpScripts

For subcommands help, try rpscripts 'subcommand' -h. For instance:

rpscripts plot -h

For further information about these programs, check Programs.

2.2.1. Quick start¶

For a quick start, run the commands below. They will create score.json file and plot all available charts:

rpscripts calc score.mxl
rpscripts plot -a score.json

2.3. Package usage¶

The user can import the entire rpscripts package or its main classes:

# import rpscripts package
import rpscripts as rp

# import only the desired classes
from rpscripts import Partition, ParsemaeSegment, RPData

2.3.1. Main classes¶

The RPScripts main classes are:

class rpscripts.Partition(parts=None)[source]¶: Main partition class.

class rpscripts.ParsemaeSegment(**kwargs)[source]¶: Parsema segment class.

class rpscripts.RPData(path=None)[source]¶: Main Rhythmic Partitioning Data class.

2.3.2. Calculator module usage¶

The snippet below parses a given score.mxl digital score file, calculates the rhythmic partitions and saves the data into the score.json file.

import music21
import pandas

import rpscripts as rp

# Generate Music21 score stream
sco = music21.converter.parse('score.mxl')
segment = rp.ParsemaeSegment()
segment.make_from_music21_score(sco)

# Get partitions data as a dictionary
dic, values_ape = segment.get_data()

# Generate Pandas Dataframe object and export to CSV.

df = pandas.DataFrame(dic)
df.to_csv('score.csv')

# Save data as a JSON file.
rpdata = segment.make_rpdata('score.json')
rpdata.save_to_file()

2.3.3. Plotter module usage¶

The snippet below loads a given score.json (generated in the previous snippet) and plots simple and bubble partitiograms.

import pandas

import rpscripts as rp

# Load the JSON data generated in the previous snippet.
rpdata = rp.RPData('score.json')

# Plot simple partitiogram (Jupyter).
# Jupyter needs %matplotlib inline to render the chart
chart = rp.plotter.SimplePartitiogramPlotter(rpdata)
chart.plot()

# Generate bubble partitiogram and save to file.
chart2 = rp.plotter.BubblePartitiogramPlotter(rpdata)
chart2.plot()
chart2.save()

# Change a default constant
rp.plotter.LABELS_SIZE = 20

2.3.4. Partition class usage¶

For rpscripts.Partition usage:

import rpscripts as rp

# Instantiate an object Partition
p = rp.Partition('1^2.2')

# Get agglomeration and dispersion indexes
p.get_agglomeration_index()
p.get_dispersion_index()

2.3.5. Hacking¶

The user can use RP Scripts’ classes to calculate rhythmic partitioning data and plot charts.

For instance, the code below extends the AbstractTimePlotter to plot the number of parts of partitions in time.

import rpscripts as rp

def count_parts(rpdata: rp.RPData) -> int:
  return [rp.Partition(p).get_parts_size() for p in rpdata.partitions]

class PartsSizeTimePlot(rp.plotter.AbstractTimePlotter):
  def __init__(self, rpdata: rp.RPData,
               image_format='svg', close_bubbles=False,
               show_labels=False) -> None:

      self.name = 'parts_size'
      super().__init__(rpdata, image_format, show_labels)
      self.parts_size = count_parts(rpdata)

  def plot(self):
      plt.clf()
      plt.plot(self.x_values, self.parts_size)
      self.make_xticks()
      plt.ylabel('Parts size')

      return super().plot()

rpdata = rp.RPData('score.json')
pstp = PartsSizeTimePlot(rpdata)
pstp.plot()
pstp.save()