Skip to content

Latest commit

 

History

History
145 lines (121 loc) · 5.38 KB

Userguide.md

File metadata and controls

145 lines (121 loc) · 5.38 KB
Raw

Styleguide of Quantlets

The following pages will introduce the Styleguide of Quantlets. An overview of the structre of a Quantlet is given and 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 in the header of your Quantlet. Several illustrative examples of correct Quantlets are listed in the Appendix.

Structure of Quantlets

Every Quantlet consists of two elementary parts with equal relevance:

  • Header-Section: Contains Meta-Information about the functionality, origin and purpose. Furthermore, a list of keywords and references to other related Quantlets are stated. The relevance of the header lies in its functionality as an information source for all suceeding data mining activities (e.g. Clustering, filtering and recommendation engines). Because clustering is an integral part of QuantNet the provision of sufficient meta-information is mandatory.

  • Code-Section: A correctly working code represents the second elementary part. The described functionality in the metainfo should practically be realizable by using the provided code. Besides correct functionality the code needs to be formatted according to the provided styleguide. Formatting ensures readability while comprehensibility is ensured by sufficient comments.

Header

Required Meta-Information

  1. Name of Quantlet (e.g. SFEDAXlogreturns)
  2. Published in Book / Paper
  3. Description - at least 10 words; should begin with a verb and with capital letters, e.g. "Plots the time series ..."
  4. Keywords - at least 5 words (the more the merrier) from the keyword list only
  5. See also - mention related Quantlets
  6. Author - check for existing authors on the website [if new, than write [New] in this field]
  7. Submitted - state your name and the time of submission
  8. Datafile
  9. Input (optional) - Should contain some new info, which is not written in other meta-info fields
  10. Output (optional) - Should contain some new info, which is not written in other meta-info fields
  11. Example - check whether there is appropriate info on the website. Should contain some new info, which is not written in other meta-info fields

Example of complete and correct header

# ------------------------------------------------------  
# Name of QuantLet:  
# ------------------------------------------------------  
# Published in:  
# ------------------------------------------------------  
# Description:  
# ------------------------------------------------------  
# Keywords:  
# ------------------------------------------------------  
# See also:  
# ------------------------------------------------------  
# Author:  
# ------------------------------------------------------  
# Submitted:  
# ------------------------------------------------------  
# Datafile:  
# ------------------------------------------------------  
# Input:  
# ------------------------------------------------------  
# Output:  
# ------------------------------------------------------  
# Example:  
# ------------------------------------------------------

Code

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",  
# Indentation is set to two space characters and maximum line width is 80 characters.
# The formatted code will be written into the new script file "output.R"

tidy_source(source = "input.R", indent = 2, width.cutoff = 80, file = "output.R")

# similar to the previous example, but using the clipboard instead of an input file

tidy_source(indent = 2, width.cutoff = 80, file = "output.R")

# 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.

Style requirements

  • 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 or a single tab per indentation level (this should be done automatically by formatR)
while (i<n){
  i = i + 1
}

Final Check

  1. Check if your code runs properly and complies to the style requirements
  2. Check if MetaInfo is complete and that you have sufficient keywords from the list

Appendix

Example's of correctly formatted Quantlets with all required meta-information

  1. http://quantnet.wiwi.hu-berlin.de/index.php?p=SFE_hq
  2. http://quantnet.wiwi.hu-berlin.de/index.php?p=SFS_hq