Contributing Guide

Danfo.js
Getting Started API Reference Contributing Guide Github
Search…
Danfo.js Documentation
Getting Started
API reference
User Guides
Building Data Driven Applications with Danfo.js - Book
Contributing Guide
Release Notes
Contributing Guide
Contributing guide to danfo.js including set up guide, and a brief intro to danfo internals.
Contributing to danfojs
Table of contents:
TL:DR
Where to start?
Working with the code
Version control, Git, and GitHub
Getting started with Git
Forking
Creating a development environment
Documentation Guidelines
Writing tests
Using mocha
Running the test suite
Contributing your changes to danfojs
Committing your code
Pushing your changes
Review your code and finally, make the pull request
Danfojs internal (Brief)
TL:DR
All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. 
For contributors familiar with open-source,  below is a quick guide to setting up danfojs locally.  
1
git clone https://github.com/opensource9ja/danfojs.git
2
cd danfojs
3
git checkout -b <your-branch-name>
Copied!
There are two folders, danfojs-browser and danfojs-node. If you are contributing a new feature, then you should include it in both versions. If you are doing a bug fix for a single version, then open that folder and install packages. 
For instance, if I want to do some bug fixes in danfojs-node. I can do the following:
1
cd danfojs-node 
2
yarn ##install all packages 
Copied!
Add my bug fixes and ensure test passes:
1
yarn test ## run test 
Copied!
Where to start?
For first time contributors, you can find pending issues on the GitHub “issues” page. There are a number of issues listed and "good first issue" where you could start out. Once you’ve found an interesting issue, and have an improvement in mind, next thing is to set up your development environment.
Working with the code
Now that you have an issue you want to fix, an enhancement to add, or documentation to improve, you need to learn how to work with GitHub and the danfojs code base.
Version control, Git, and GitHub
The danfojs code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on this project.
Some great resources for learning Git:
Official GitHub pages.
Getting started with Git¶
Find Instructions for installing git, setting up your SSH key, and configuring git. These steps need to be completed before you can work seamlessly between your local repository and GitHub.
Forking the danfojs repo
You will need your own fork to work on the code. Go to the danfojs project page and hit the Fork button.
Next, you will clone your fork to your local machine:
1
git clone https://github.com/opensource9ja/danfojs.git
2
cd danfojs
Copied!
This creates the directory danfojs and connects your repository to the upstream (main project) repository.
All development are done in two folders--danfojs-browser and danfojs-node folders. The two folders are similar and it is always recommended to pull latest changes from master before development in any of the folder. 
Some Javascript features are supported both in the browser and node environment, and it is recommended to add these to both versions. 
For features that work only in NodeJs environment, especially file related issues, these should be developed and tested in the danfojs-node folder, and the corresponding tests are written there.   
Creating a development environment
To test out code changes, you’ll need to build danfojs, which requires a Nodejs environment.
1
git clone https://github.com/opensource9ja/danfojs.git
2
cd danfojs
3
cd danfojs-browser && yarn ## installs required packages in browser version
4
cd .. && cd danfojs-node && yarn ## installs required packages in node version
5
cd .. ## Go back to root folder
6
yarn test ##Runs test in both node and browser folder
Copied!
Now you can start adding features or fixing bugs!
Documentation Guidelines
Documentation helps clarify what a function or a method is doing. It also gives insight to users of the function or methods on what parameters to pass in and know what the function will return.
Sample documentation:
1
 /**
2
 * Add two series of the same length
3
 * @param {series1} series1 [Series]
4
 * @param {series2} series2 [Series]
5
 * @returns Series
6
 */
7
function add_series(series1, series2){
8
​
9
        ...................
10
​
11
        return new Series()
12
}
13
​
Copied!
And for functions that contain more than two argument, keyword argument should be used. Parsing of keyword argument is also applicable to most of the methods in a class
1
/**
2
 * Join two or more dataframe together along an axis
3
 * @param {kwargs} kwargs --> {
4
 *                      df_list: [Array of DataFrame],
5
 *                      axis : int {0 or 1},
6
 *                      by_column : String {name of a column},
7
 *                    }
8
 * @returns DataFrame 
9
 */
10
function join_df(kwargs){
11
        ........
12
​
13
        return DataFrame
14
}
Copied!
Writing tests
We strongly encourage contributors to write tests for their code. Like many packages, danfojs uses mocha
All tests should go into the tests subdirectory and place in the corresponding module. The tests folder contains some current examples of tests, and we suggest looking to these for inspiration.
Below is the general Framework to write a test for each module.
JavaScript
1
import { assert } from "chai"
2
import { DataFrame } from '../../src/core/frame'
3
​
4
describe("Name of the class|module", function(){
5
 
6
  it("name of the methods| expected result",function(){
7
    
8
       //write your test code here
9
       //use assert.{proprty} to test your code
10
   })
11
​
12
});
Copied!
For a class with lots of methods.
1
import { assert } from "chai"
2
import { DataFrame } from '../../src/core/frame'
3
​
4
describe("Name of the class|module", function(){
5
 
6
 describe("method name 1", function(){
7
 
8
   it("expected result",function(){
9
     
10
        //write your test code here
11
        //use assert.{proprty} to test your code
12
    })
13
  })
14
  
15
  describe("method name 2", function(){
16
 
17
   it("expected result",function(){
18
     
19
        //write your test code here
20
        //use assert.{proprty} to test your code
21
    })
22
  })
23
  .......
24
});
Copied!
Example: Let write a test, to test if the values in a dataframe are off a certain length. Assuming the method to obtain length is values_len()
1
import { assert } from "chai"
2
import { DataFrame } from '../../src/core/frame'
3
​
4
describe("DataFrame", function(){
5
    
6
  describe("value_len", function(){
7
 
8
   it("check dataframe length",function(){
9
     
10
       let data = [[1,2],[4,5]]
11
       let columns = ["A","B"]
12
       let df = new DataFrame(data,{columns: columns})
13
       
14
       let expected_result = 2
15
       
16
       assert.deepEqual(sf.value_len(), expected_result))
17
       
18
       
19
    })
20
  })
21
​
22
});
Copied!
Running the test case
To run the test for the module you created,
1) Open the package.json 
2) change the name of the test file to the file name you want. and don't forget the file is in the test folder
1
"scripts": {
2
    "test": "....... danfojs/tests/sub_directory_name/filename",
Copied!
3)  run the test, in the danfojs directory terminal
1
yarn test
Copied!
Learn more about mocha here​
Contributing your changes to danfojs
Committing your code
Once you’ve made changes, you can see them by typing:
1
git status
Copied!
Next, you can track your changes using
1
git add .
Copied!
Next, you commit changes using:
1
git commit -m "Enter any commit message here"
Copied!
Pushing your changes
When you want your changes to appear publicly on your GitHub page, you can push to your forked repo with:
1
git push
Copied!
Review your code and finally, make a pull request
If everything looks good, you are ready to make a pull request. A pull request is how code from a local repository becomes available to the GitHub community and can be reviewed and eventually merged into the master version. To submit a pull request:
1.
Navigate to your repository on GitHub
2.
Click on the Pull Request button
3.
Write a description of your changes in the Preview Discussion tab
4.
Click Send Pull Request.
This request then goes to the repository maintainers, and they will review the code and everything looks good, merge it with the master.
Hooray! You're now a contributor to danfojs. Now go bask in the euphoria!
Danfojs Internals
In other to contribute to the code base of danfojs, there are some functions and properties provided to make implementation easy.
The main exposed modules are the Frame and Series module. This module inherits from the Generic module.
The Generic module consists of the following methods and properties
.dtypes    [source] is used to obtain the dtype for each column
.index [source] to obtain the index for Dataframe or Series
.__set_index(label)   [source] to set the index value
.__reset_index()  [source] to reset the index in DataFrame and Series
.values    Obtain the values in  DataFrame and Series per rows
.col_data Obtain the values in DataFrame and Series per columns
.column_names  [source] Obtain the list of column names
.__set_col_types [source] set the dtype for a column or infer the dtype from it
.columns to  access the column names directly
row_data_tensor  store the tensor representation of the data in DataFrame and Series
The Frame module consists of the following methods and properties to aid implementation.
__frame_is_compactible_for_operation  [source]:  check if all the values in a DataFrame are numerical. This helps to check if the numerical operation can be done using the dataframe.
.__get_ops_tensors(tensors, axis)   [source] : obtain tensors from dataframes along axis 0 or 1.
.__get_df_from_tensor(val, col_names)   [source]:  Obtain dataframe from tensor.
.__get_tensor_and_idx(df, axis)  [source]:  Obtain tensors, their index value and their axis from dataframe.
The Series module contains mostly Generic properties and less special internal properties.
__check_series_op_compactibility(other)  [source]  check if two series are compatible for numerical operation
Lastly, the Utils module contains important utility functions.