Package: pyanthem
Features:Converts three-dimensional datasets to visually pleasing, audible representationsA variety of video and audio parametersIn-place video and audio mergeGUI and Command-line interface for maximum flexibilityExample datasets to get you startedHeadache-free installation with an Anaconda environmentpyanthem was primarily developed to interpret matrix-decomposed functional imaging datasets - for example, a datasetVwith shape[height,width,time], is decomposed into two matrixes:Wwith shape[height*width,n], andHwith shape[n,time]such thatH x W = V. Here, n represents the number of variables represented by the decomposition. There are various techniques used to decompose matrixes - two popular techniques include Non-negative Matrix Factorization (NMF), and Singular Value Decomposition (SVD).If you would prefer to keep things simple, you can skip matrix decomposition altogether and focus solely on converting raw data to audio - only working with theHmatrix, where each row represents a variable and each column represents a time point.If this is too much information to digest, don’t worry! Try the example below to get more familiar with what the data looks like, and how pyanthem transforms it.InstallationEasy Installation Using AnacondaFirst, make sure you haveAnaconda(or Miniconda) installed before proceeding.Create an environment and install the required packages:condacreate-npyanthempython=3.8pipffmpegfluidsynth--channelconda-forge--channelnicthibNext, activate the environment:condaactivatepyanthemFinally, install the pyanthem Python package using pip:pipinstallpyanthemManual InstallationFirst, install ffmpeg and FluidSynth:FFmpeg:ffmpeg enables video creation and merging.FluidSynth:FluidSynth enables conversion of MIDI files to crisp, high quality sound files.Finally, install pyanthem using pip:pipinstallpyanthemNote: Currently, pyanthem is tested to work on Python 3.8. Please use this version to minimize headaches.Optional: Using pyanthem in a Jupyter NotebookTo access the pyanthem environment in a Jupyter notebook, first install ipykernel in your environment:condainstall-canacondaipykernelAfter this, create the kernel:python-mipykernelinstall--user--name=pyanthemOnce in a notebook, switch to the pyanthem kernel by selectingKernel > Change kernel > pyanthemNote: While the pyanthem kernel will now be available in any Jupyter notebook session, pyanthem will not function properly unless the Jupyter notebook is launched inside the pyanthem environment.UsageBefore getting started, download some example datasetshere. For this, we are using the file called ‘demo1.mat’Using pyanthem in GUI modeFirst, import pyanthem and begin a pyanthem session:importpyanthempyanthem.run()Note: You may run into an error here where some packages are missing. Simply install them using pip, and try running pyanthem again.The first time you run pyanthem, it will download a necessary soundfont file - this will take a minute or two.♫ Initializing soundfont library...
♫ Downloading 17QuXRbApe0JTlYfBs7iSMCMu3xRWMHOV into...
♫ 238.3 MiB Done.Once completed, the pyanthem GUI will initialize:Next, load a dataset by clickingFile > Load data.... For this section, we will load the datasetdemo1.mat. Currently, you can import any .mat or hdf5 file that contains the following variables:Temporal variable (H, required): A 2D matrix of shape[n,t], where each row is a component and each column is a time-point. This variable is referred to as“H”in the pyanthem environment.Spatial variable (W, optional): A 3D matrix of shape[h,w,n], where h and w represent the spatial height and width of your dataset. If this variable is not given, no video output is possible.Framerate (fr, optional): A single float value, representing the frame rate of your dataset in Hz. If a framerate is not given, pyanthem will provide a default.Note: Make sure to only include these variables in your file to avoid any errors. You can name them however you like, but make sure there are only one of each variable.Once loading is complete, the GUI should update with default options, and plots ofHandW:The bottom left plots show two representations of the dataset: A preview of the output movie (left), and a visualization of what components are included and the colormap selection. The right two plots show raw representations ofH(top), and a visualization of the audio output file (right). Lighter colors indicate loud notes, and darker colors indicate quiet notes, with black indicating silence.From here, you can adjust parameters, preview the output, and finally save video and audio files. If you want to check how your parameter adjustments impact your audivisualization, click theUpdatebutton, and your changes will be reflected. Any issues with your selected parameters will be indicated in the white status box. Try adjusting a few parameters and observing how the plots change.Finally, render output files with theSave --> Audio + Videomenu command.Congratulations - you’ve created your first audiovisualization!Using pyanthem in CLI (command-line interface) modepyanthem’s CLI mode is useful for running batch conversions of large amounts of data once you are happy with your audiovisualization parameters, or creating more complex audiovisualizions that use multiple datasets and instruments. CLI mode is not recommended to use until you have used the GUI and are comfortable with the parameters and usage.To run pyanthem in CLI mode, pass the argumentdisplay=False, and assign the.run()method to a variable:importpyanthemg=pyanthem.run(display=False)Next, load a dataset and config file using the.load_data()and.load_config()methods. You can pass an explicit file name to thefile_inargument, or pass none to recieve a file select prompt (note the use of the leadingrwhen naming a file location):g.load_data(file_in=r'path/to/your/file.mat')g.load_config(file_in=r'path/to/your/config.p')Finally, render the audio and video file, then merge the files using the.write_audio(),.write_video()and.merge()methods:g.write_audio()g.write_video()g.merge()Once you’re comfortable with this syntax, you can combine all of these steps into a single line, write a merged video with the.write_AV()method, and even remove the intermediate files using the.cleanup()method:data_file=r'path/to/your/file.mat'config_file=r'path/to/your/config.p'g.load_data(file_in=data_file).load_config(file_in=config_file).write_AV().cleanup()Congratulations - you’ve created your first audiovisualization in CLI mode!Decomposing raw datasetsThis feature is still a work in progress - results may vary for your specific dataset!If you have some of your own data you would like to decompose into components for audiovisualization, you can utilize the CLI command process_raw() to accomplish this.Example usage:importpyanthemg=pyanthem.run(display=False)g.process_raw(file_in=r'path/to/your/file.mat',n_clusters=20,save=True)Here, we first begin a CLI session using the display=False flag. Then, we load a .mat file for decomposition, clustering it into 20 components, and then create a decomposition using these clusters. The output - temporal and spatial components, are assigned to the workspace for further processing, and are also saved as a new file where the dataset was loaded from. Save is disabled by default, so make sure to set the save flag to True if you want to save the processed data.Note: You can also decompose a raw dataset in GUI mode using theFile --> Load raw...menu command.TeamNic Thibodeauxhttp://github.com/nicthibFAQUnder construction!SupportEmail:dnt2111@gmail.com