The following pages will introduce the Styleguide of Quantlets (Qs). An overview of the structure of a Q is given while explaining each part's relevance. You will find descriptions and instructions on how to format your code as well as detailed examples about the required information for your Q.
In the second section you will find basic instructions on how to work with the desktop client version of Github, which includes additional features to upload pictures and datafiles as separate files to your Q's repository.
Finally, several illustrative examples of correct QuantLets are listed in the Appendix.
Every QuantLet Repository consists of two elementary parts / files with equal relevance:
-
Metainfo.txt: Contains meta-information about the functionality, origin and purpose of your Q. Furthermore, lists of keywords and references to other related QuantLets are stated. You will need to create the file "metainfo.txt", which will be formatted in 'YAML' an easy and intuitive data serialization language. The formatted "metainfo.txt" will be used for [Visualization] (http://quantnet.wiwi.hu-berlin.de/d3/ia/) and data mining practices (e.g. Clustering, filtering and recommendation engines) and is therefore mandatory. In the next sections, you will find examples on how to format the "metainfo.txt". You can download the prepared [TEMPLATE_Metainfo.txt here.] (https://github.com/QuantLet/Validation-procedure-and-Styleguide/blob/master/TEMPLATE_Metainfo.txt)
-
QuantLetcode.r: A correctly working code represents the second elementary part. The described functionality in the metainfo.txt should practically be realizable by using the provided code. Besides correct functionality the code needs to be formatted according to the here provided styleguide. Formatting ensures human readability while comprehensibility is ensured by sufficient and precise comments.
- Name of QuantLet : e.g. SFEDAXlogreturns (Omit endings like .r .sas or .m)
- Published in : Book / Paper
- Description : at least 10 words; should begin with a verb and with capital letters, e.g. "Plots the time series ..."
- Keywords : at least 5 words (the more the merrier) from the keyword list only
- See also (optional) : mention related QuantLets
- Author : check for existing authors on the website [if new, then write [New] + Author in this field]
- Submitted (optional) : state the name and the time of the original submission
- Datafile : check whether all datafiles which are used in the code are listed here
- Input (optional) : Should contain some new info, which is not written in other metainfo fields
- Output (optional) : Should contain some new info, which is not written in other metainfo fields
- Example (optional) : Should contain a list of generated plots and descriptions, which are not written in other metainfo fields
Important: Make sure that the provided 'Name of QuantLet' and the actual filename of your provided Codefile is identical.
YAML™ (rhymes with “camel”) is a human-friendly, cross language data serialization language. You will use it almost intuitively. Thanks to YAML, there is no need to use the #-Symbol as in Quantnet 1.0 in the metainfo anymore. It is even robust against redundant space in description parts although we advise to avoid these. Besides that, there are alternative ways on how to structure enumerations in a YAML-File.
Name of QuantLet: MVAreturns
Published in: Applied Multivariate Statistical Analysis
Description: Shows monthly returns of six US firms from Jan 2000 to Dec 2009.
Keywords: financial, portfolio, returns, asset, time-series, plot
See also: MVAportfol_IBM_Ford, MVAportfol_IBM_PanAm
Author: Zografia Anastasiadou
Submitted: Fri, August 05 2011 by Awdesch Melzer
Datafile: apple.csv, bac.csv, ed.csv, ford.csv, ibm.csv, ms.csv
Input:
Output:
Example:
-
The colon ' : ' separates the data field (left) from its description (right)
-
Optional data fields, where no description is provided can be omitted completely (Above example includes them for illustration purposes anyway).
-
If you write multiple lines or use special characters you have to put your text in single quotes, i.e. 'Your text'. For single lines without special characters there is no need to do so.
-
If you want to use the apostrophe character <'> (represented by the single quote sign) inside your text just type the single quote sign twice.
...
Description: Shows monthly returns of six US firms from Jan 2000 to Dec 2009.
...
Description: 'Shows monthly returns of six US firms from Jan 2000 to Dec 2009.'
...
Description: 'Shows monthly returns of six US firms
from Jan 2000 to Dec 2009.'
...
Description: 'Shows monthly returns of six US firms
from Jan 2000 to Dec 2009.'
...
Description : 'Shows monthly returns
of six US firms from
Jan 2000 to Dec 2009.'
...
All of these 5 notations are accepted by YAML. We recomend to use such notations which display the text in the best human readable way, because the metainfo text is used later for the Readme file creation (this process is executed in an automatic way).
Characters like {_, -, :, ", ...} are meant to be special characters. In case of doubt simply put your text in single quotes.
...
Example : 'The comparison of estimated IE forecast across five different countries - U.K. (red),
Germany (blue), France (black), Italy (green) and Sweden (grey).'
...
This notation (with special characters and multiple lines) is accepted by the YAML parser. The following code is a counterexample to illustrate possible mistakes.
...
Example : The comparison of estimated IE forecast across five different countries - U.K. (red),
Germany (blue), France (black), Italy (green) and Sweden (grey).
...
This notation (with special characters and multiple lines) results to a YAML parser error.
...
Description : 'Computes a contingency table. Additionally, four different
correlation measures can be given: Chi-square, contingency correlation,
corrected contingency correlation and Cramer''s V.'
...
How to include the apostrophe character inside your text. Very important: use TWO single quote signs (Type ', Type ') and NOT ONE double quote sign (Type "), because both ways look nearly the same! After the parsing process this notation is automatically converted to the proper representation of the apostrophe character.
As mentioned above, there are different ways you can structure enumerations in YAML. Below you find the two possible alternatives:
...
Keywords: financial, portfolio, returns, asset, time-series, plot
...
Keywords:
- financial
- portfolio
- returns
- asset
- time-series
- plot
In many cases, the datafields "Input" and "Output" require you to add an additional description to your enumerated items. You can do this by using following syntax:
...
Input:
- t : time points
Output:
- k : kernel function
...For further details please check the complete YAML documentation or find additional information in our FAQ section
Use "FormatR package" to clean up your R code (In the case you are using another language like Matlab try to implement the following steps accordingly)
You can easily preprocess your code with the FormatR package. This will do 80% of the work for you. In the following you will find instructions on how to execute the relevant function.
# Cleaning up the source code in an R script file "input.R",
# The formatted code will be written into the new script file "output.R"
tidy_source(source = "input.R", file = "output.R")
# Similar to the previous example, but using the clipboard instead of an input file.
# When omitting function parameters the defaults
# indent = 4 and width. cutoff = 80 are being used.
# For simplicity, we recommend these for the use on QuantNet
tidy_source(file = "output.R")More details about the package FormatR are available in the package documentation.
- Change all "<-" with "="
A QuantNet specific style requirement adresses the assignment operator. All "<-" should be replaced with "=" like shown below.
# BAD
foo <- 5.0
bar <- function(x)
return x^2
}
# GOOD
foo = 5.0
bar = function(x){
return x^2
}- Align assignments in subsequent lines by "="
foo = 5.0
foobar = 7.0
bar = 8.0- Set four space characters for indentation (this should be done automatically by formatR)
while (i<n){
i = i + 1
}Besides the browser version of Github, there is also a desktop client for local use. Github desktop client is an easy to use graphical user interface for those who are not comfortable with Git (Commandline version). The desktop client allows to upload pictures and datafiles as separate files, which will be necessary if plots are generated by your code or whenever a dataset is required. However, you will need to understand some basics to avoid common errors. To find an appropriate client version for your operating system click here
Before you can locally work on your desired repository you need to 'clone' it first. This will create a local copy of the masterbranch on your local workspace. It now becomes critical to keep your local branch synced to any changes conducted to the remote master branch and vice versa. If you don't, you will encounter syncing errors due to differences between your local and the remote branch. We will now describe how to avoid this common error.
-
Local synchronization - Sync your local repository before beginning any work in that repository
-
Conduct local changes - Change/ add/ delete files
-
Commit - Commit your conducted changes within your Github Desktop Client
-
Back synchronization - Sync your local repository, so that changes are inherited in remote branch
It might happen that you forget to synchronize your repository as prescribed which could lead to Sync-errors. If that has happened to you, you will have to work with the Gitshell commandline to solve this error. Following articles might help you with that:
- Git Documentation-Getting started
- [Dealing with non-fast-forward errors] (https://help.github.com/articles/dealing-with-non-fast-forward-errors/)
You can easily add files to your local repositories which will be commited and therefore uploaded to the remote branch. Simply add pictures or datafiles to the desired local repository. If you have not specified a special directory upfront, the directory will most likely be C:\Users\Username\Documents\GitHub\Repository_xy.
- Check if your code runs properly and complies to the style requirements
- Check if MetaInfo is complete and that you have sufficient keywords from the keyword list
Example's of correctly formatted QuantLets with all required meta-information: Pick out any of the "bubbles" in this [Visualization] (http://quantnet.wiwi.hu-berlin.de/d3/ia/), then click on it and examine the files in the shown GitHub-folder. In particular the related "metainfo.txt".
Some Examples: