Carrying on from the previous edition, this is a short look at another project of mine. An Open Source package that my friends and I wrote for the language R as part of a course project for Time Series Analysis.

The Open Source domain is one which is peculiar in that it is deceptively easy to contribute but it’s also not well known where or how to contribute because of the lack of advertising.

I’ve summarised the algorithm that we implemented below but if you want to skip ahead to contributing to R then ignore this next section. The Package is TSeriesMMA and you can take a look here.

Multiscale Multifractal Analysis

The algorithm that we implemented was Multiscale Multifractal Analysis, as specified in this paper, used to describe the scaling properties of fluctuations of a time series.

Let’s go from the basics. A time series is a set of data points that record a given quantity with the passage of time. Next consider a fractal. In mathematics, a fractal is an abstract object which exhibits similar patterns at increasingly smaller scales.

So in the context of signals and time series what do we mean when we say fractal properties? Something like this.

The first thing that jumps out when you see the above figure is the size of the sliding window chosen to view the signal. It is obvious that if an incorrectly sized window is chosen then you would not be able to observe said fractal properties. The size of this window is known as the scale.

So we now know about fractals and scales but what is the purpose of multifractal multiscale analysis? The main result of this procedure is the so called Hurst surface which is a dependence of the local Hurst exponent on the multifractal parameter (Kantelhardt et al., 2002) and the scale of observation.

The Hurst Exponent of a time series is used to infer properties about a time series with respect to autocorrelation. For example a Hurst Exponent of 0.5 indicates that the Time Series is a random walk i.e. Brownian time series. It is calculated by dividing a series into segments and obtaining the fluctuation across the different segments. Mathematically the fluctuation is as follows:

So what we did was divide the time series into v segments of size s, and obtain a polynomial fit for each different segment. The squared error of each of these fits is what is represented by F(s,v). The exponent to which it is raised is known as the multifractal parameter q. Basically multifractal patterns can be represented using a power law that is described by the exponent q. More on multifractal patterns here if you’re interested.

Log(Fq(s)) as obtained from the above equation gives you the Hurst exponent at scale s and multifractal parameter q. Now we vary q and s so as to obtain the corresponsing Hurst exponent and observe the values in a 3D surface called the Hurst surface. Think of it as a way to find out what scale we need to break down our signal into for it to showcase fractal properties. Being able to predict if a series is following fractal patterns at smaller scales comes in handy in fields like atomic spectroscopy and medicine where knowing how a signal behaves when scaled down has massive implications.

Going Open Source

The successful implementation of the algorithm would have been the end of the project, but when we found out that it was not available in R we thought we would contribute our work as a package. R itself is an open source language which invites contributions by means of the CRAN Project (Comprehensive R Archived Network). CRAN is a network of FTP and web servers around the world that store identical, up-to-date, versions of code and documentation for R.

How to Contribute?

Lucky for us, R comes with a package called devtools that is aimed purely at making the work of developers simpler. Navigate to your main project directory and run: devtools::create(“your folder name”)

This creates an umbrella directory to hold your package that contains the Description file, Namespace, R.proj and R code folder.

Once your source code is safely tucked into R/ you can set up the manual in the folder man/ within the main directory. The manual put up on the website is generated from this so make sure you do it carefully. Directions to do the same are provided on the CRAN website and it’s fairly easy to do. It’s helpful to include examples on how to use the package as well in here.

you can set up the manual in the folder within the main directory. The manual put up on the website is generated from this so make sure you do it carefully. Directions to do the same are provided on the CRAN website and it’s fairly easy to do. It’s helpful to include examples on how to use the package as well in here. The Description file contains information about the authors of the package and a description of it’s working. What is important is that at least one author is mentioned as the maintainer and a valid email address provided for the same. The remaining fields are provided by devtools and needn’t be edited as such. This includes licensing information and encoding. The Namespace file is meant to be a list of dependencies for your source code. Standard format again. Just make sure you don’t miss any package. Include News.md file for versioning information as well.

It’s also important to document your source code properly. Each function – paramters and results have to be clearly stated and even documentation for long code snippets is useful.

Once you are satisfied with these, navigate to your main package folder and run R CMD build <Folder Name>

This creates a .tar.gz file containing everything pertaining to your project. Now you need to see that your code satisfies all the criteria mentioned by running: R CMD check <package>.tar.gz –as-cran

This checks the internal structure to make sure it is in line with what CRAN is expecting. Once you get a green light from here you’re good to go uploading your package.

You will probably hear back from one of the administrators over night with changes to be made. Once you’re done with these, update News.md and you can resubmit again and the process continues till you finally get acceptance. Be ready for a couple of rejections at least, they’re pretty strict about standards 😛

Wala! You are now a contributor and your package gets a dedicated page on the CRAN website. This can now be downloaded and used by anyone and everyone.

Here’s a link to the source code in case you need to check out the directory structure or anything.