1562044263
Ruby Algorithm Documentation with AsciiDoc and Knitr
In this article, walks us through prototyping an algorithm and creating a functional specification with the help of AsciiDoc and R for a Ruby on Rails project…
Every non-trivial project needs documentation, and it needs to be engaging with great explanations, and even illustrations, so that it’s actually read and used. Engineers make software to solve business problems, generally without having extensive experience in that particular business, so documenting the business is just as important as documenting the software.
Documentation can be bolted on after the fact, but I find that writing a functional specification before coding is a big help. A functional specification is a source of truth for every member of the team across disciplines, and forces high-level design before implementation, preventing wasted effort. In this post, I’m going to go through an example project from prototyping to writing a functional specification for an example Ruby on Rails project to describe what the app is supposed to do and be a reference during development. My goal is to show that Ruby projects can use AsciiDoc and R to:
- Easily prototype new calculations, algorithms, etc. using R
- Easily show results from R in your functional specification and other written AsciiDoc documentation
- Tie it into the build process so documentation is always updated with the latest data and algorithms
A functional spec isn’t a replacement for documenting your API with RDoc or YARD–it’s a vital addition that can be used as a reference for all stakeholders (programmers and non-programmers alike) in a project.
Prototype
I like salmon fishing, and I want a way for myself and others to keep track of and share details about the fish they’re catching. It also needs a scoreboard to showcase the top users. Right now there are forums used for this purpose, but structured data with a scoreboard is way cooler.
I could make a prototype in Ruby, but Ruby doesn’t have the best support for graphing, so I’m going to use R. Using R gives me a lot of easy ways to play with the math and visualization, and it’s cross-platform.
# Read in some example data
data <- read.csv("func_spec/example_user_data.csv")
# Compute the score, weighted by base-10 log of number of reports
score <- mean(data$Fish.Caught) * log(length(data$Date)) / log(10)
In just two lines, I read in some example data and calculated a score using my proprietary score. R can do this and show a plot with a vanilla install, while languages like Ruby or Python will require more code and extra packages to be installed.
Documenting the Algorithm
After making my scoring system, I could go straight to code. In fact, I could have skipped prototyping in R and just prototyped directly in my Ruby on Rails app. However, prototyping in R was fast and very close to the underlying math. Here’s how I’ll set up the documentation:
kingfisher/
Rakefile
doc/
func_spec.Radoc
My example Rails project is called kingfisher, and I’m putting the documentation into a “doc” folder. I’m not going to go over AsciiDoc syntax as the Asciidoctor site has a bunch of great documentation for that, but here’s how to stick a chart into the AsciiDoc with knitr:
//begin.rcode freq_change, fig.asp=0.618, fig.width=12, fig.align="center"
times_fished <- 1:50
plot(times_fished, 5 * log(times_fished) / log(10),
ylab="User score when average 5 catches per trip",
xlab="Number of fishing trips in the past 12 months")
//end.rcode
Stick that into func_spec.Radoc, run knitr and AsciiDoc, and you’ll get something like this in your documentation:
Hopefully most developers intuitively understand the score would go up logarithmically with the number of times fished; even so, this is a great way to display that just to make sure. Around this chart, I’d have some text explaining why this is desirable so developers who don’t fish can understand what’s going on here. This example is contrived, but I’ve used this type of prototyping and documentation in the past for other projects (e.g. finance, construction estimating) where the results of the calculations may not always be obvious.
Now that the score is prototyped and we have a plot to stick in the documentation, all that’s left is to transform the input AsciiDoc to some sort of output format. I use a few rules in my Rakefile to transform to HTML:
require 'asciidoctor'
require 'pathname'
task docs: %w[doc/func_spec.html]
rule '.adoc' => '.Radoc' do |t|
Dir.chdir(Pathname.new(t.name).dirname) do
sh "R -e 'library(knitr);knit(\"#{Pathname.new(t.source).basename}\", " +
"\"#{Pathname.new(t.name).basename}\")'"
end
end
rule '.html' => '.adoc' do |t|
Dir.chdir(Pathname.new(t.name).dirname) do
Asciidoctor.convert_file Pathname.new(t.source).basename,
backend: :html5,
to_file: true,
safe: :safe
end
end
Now I can run “rake docs” and get the documentation to build and always be up to date, even if I change the underlying data or scoring calculation.
Other Solutions
For anything involving Ruby on Rails, documenting with AsciiDoc is a great choice whether there are custom graphics in the documentation or not. AsciiDoc gives you a Ruby-native way to write in a wonderful markup format. That said, there are other great documentation tools that will be a bit more to manage and tie into your build process for a Rails project.
Sphinx processes reStructuredText (also a nice markup format) and can incorporate output from Matplotlib. For a Python project, this is perfect–Sphinx + Matplotlib give you a Python-native way to produce nice documentation with custom graphics. However, if you’re working on a Rails project, it’s less than desirable to have to manage multiple sets of dependencies for a separate environment just to produce your documentation.
There are tons of other solutions for producing documentation, including programs like doxygen and LaTeX, which may require more or less glue to fit into your build system. If you need a system like LaTeX, use it; if you have a fairly standard Rails project and you just have a bit of math that should be documented, use AsciiDoc and R.
Conclusion
Ruby and AsciiDoc make a great team, and it’s easy to throw R into the mix to make nice visualizations in your documentation. You can throw in any package in the R ecosystem, like ggplot2, to get beautiful charts in your documentation.
#ruby #ruby-on-rails #web-development
What is GEEK
Buddha Community
1596485520
Algorithms: Calculating Combination with Ruby
Background
When I learned to code, I hadn’t slept in a math classroom in 14 years.
I studied philosophy and taught courses on Symbolic Logic. I can talk about deductive proofs for days, but when people pull out a f of n’s… x²…_ [insert Greek letter] — _I nod along, but trust me, I have no idea what’s happening.
For this reason, I got a huge boost of empowerment when I figured out an algorithm question asking, “How can you determine the mathematical combination (nCr) of two numbers?”
If you’re like ‘what the…?’, then hell yeah, you are me a day ago. Let’s go!
The Meat
Defining the Problem
I’ll try my best to explain a combination:
Imagine you’re losing a high stakes poker game. You have sweat on your neck as a couple Mafia grunts stare daggers at you. As the big one cracks his knuckles, you think “It’s a shame I never learned to count cards. But maybe start now?”
Your mind is racing. You start thinking, how do I start? How many possible hands are there in the deck? Well, there are 52 cards. You get 5 distinct cards in each hand, and they can come in any order. Let’s see, some quick math in your head and…
Yeah, the answer is not obvious. But, you’re attempting a combination. A combination is when you have a collection of items and you want to find all the possible selections from that collection — for example, every possible hand from a deck of cards.
By the way, the answer is 2,598,960. Each hand has a 1/2,598,960th chance of being drawn. With numbers that big, it’s good we can train a computer to solve the problem.
#ruby #combination #ruby-on-rails #algorithms #dev #algorithms
1562044263
Ruby Algorithm Documentation with AsciiDoc and Knitr
In this article, walks us through prototyping an algorithm and creating a functional specification with the help of AsciiDoc and R for a Ruby on Rails project…
Every non-trivial project needs documentation, and it needs to be engaging with great explanations, and even illustrations, so that it’s actually read and used. Engineers make software to solve business problems, generally without having extensive experience in that particular business, so documenting the business is just as important as documenting the software.
Documentation can be bolted on after the fact, but I find that writing a functional specification before coding is a big help. A functional specification is a source of truth for every member of the team across disciplines, and forces high-level design before implementation, preventing wasted effort. In this post, I’m going to go through an example project from prototyping to writing a functional specification for an example Ruby on Rails project to describe what the app is supposed to do and be a reference during development. My goal is to show that Ruby projects can use AsciiDoc and R to:
- Easily prototype new calculations, algorithms, etc. using R
- Easily show results from R in your functional specification and other written AsciiDoc documentation
- Tie it into the build process so documentation is always updated with the latest data and algorithms
A functional spec isn’t a replacement for documenting your API with RDoc or YARD–it’s a vital addition that can be used as a reference for all stakeholders (programmers and non-programmers alike) in a project.
Prototype
I like salmon fishing, and I want a way for myself and others to keep track of and share details about the fish they’re catching. It also needs a scoreboard to showcase the top users. Right now there are forums used for this purpose, but structured data with a scoreboard is way cooler.
I could make a prototype in Ruby, but Ruby doesn’t have the best support for graphing, so I’m going to use R. Using R gives me a lot of easy ways to play with the math and visualization, and it’s cross-platform.
# Read in some example data
data <- read.csv("func_spec/example_user_data.csv")
# Compute the score, weighted by base-10 log of number of reports
score <- mean(data$Fish.Caught) * log(length(data$Date)) / log(10)
In just two lines, I read in some example data and calculated a score using my proprietary score. R can do this and show a plot with a vanilla install, while languages like Ruby or Python will require more code and extra packages to be installed.
Documenting the Algorithm
After making my scoring system, I could go straight to code. In fact, I could have skipped prototyping in R and just prototyped directly in my Ruby on Rails app. However, prototyping in R was fast and very close to the underlying math. Here’s how I’ll set up the documentation:
kingfisher/
Rakefile
doc/
func_spec.Radoc
My example Rails project is called kingfisher, and I’m putting the documentation into a “doc” folder. I’m not going to go over AsciiDoc syntax as the Asciidoctor site has a bunch of great documentation for that, but here’s how to stick a chart into the AsciiDoc with knitr:
//begin.rcode freq_change, fig.asp=0.618, fig.width=12, fig.align="center"
times_fished <- 1:50
plot(times_fished, 5 * log(times_fished) / log(10),
ylab="User score when average 5 catches per trip",
xlab="Number of fishing trips in the past 12 months")
//end.rcode
Stick that into func_spec.Radoc, run knitr and AsciiDoc, and you’ll get something like this in your documentation:
Hopefully most developers intuitively understand the score would go up logarithmically with the number of times fished; even so, this is a great way to display that just to make sure. Around this chart, I’d have some text explaining why this is desirable so developers who don’t fish can understand what’s going on here. This example is contrived, but I’ve used this type of prototyping and documentation in the past for other projects (e.g. finance, construction estimating) where the results of the calculations may not always be obvious.
Now that the score is prototyped and we have a plot to stick in the documentation, all that’s left is to transform the input AsciiDoc to some sort of output format. I use a few rules in my Rakefile to transform to HTML:
require 'asciidoctor'
require 'pathname'
task docs: %w[doc/func_spec.html]
rule '.adoc' => '.Radoc' do |t|
Dir.chdir(Pathname.new(t.name).dirname) do
sh "R -e 'library(knitr);knit(\"#{Pathname.new(t.source).basename}\", " +
"\"#{Pathname.new(t.name).basename}\")'"
end
end
rule '.html' => '.adoc' do |t|
Dir.chdir(Pathname.new(t.name).dirname) do
Asciidoctor.convert_file Pathname.new(t.source).basename,
backend: :html5,
to_file: true,
safe: :safe
end
end
Now I can run “rake docs” and get the documentation to build and always be up to date, even if I change the underlying data or scoring calculation.
Other Solutions
For anything involving Ruby on Rails, documenting with AsciiDoc is a great choice whether there are custom graphics in the documentation or not. AsciiDoc gives you a Ruby-native way to write in a wonderful markup format. That said, there are other great documentation tools that will be a bit more to manage and tie into your build process for a Rails project.
Sphinx processes reStructuredText (also a nice markup format) and can incorporate output from Matplotlib. For a Python project, this is perfect–Sphinx + Matplotlib give you a Python-native way to produce nice documentation with custom graphics. However, if you’re working on a Rails project, it’s less than desirable to have to manage multiple sets of dependencies for a separate environment just to produce your documentation.
There are tons of other solutions for producing documentation, including programs like doxygen and LaTeX, which may require more or less glue to fit into your build system. If you need a system like LaTeX, use it; if you have a fairly standard Rails project and you just have a bit of math that should be documented, use AsciiDoc and R.
Conclusion
Ruby and AsciiDoc make a great team, and it’s easy to throw R into the mix to make nice visualizations in your documentation. You can throw in any package in the R ecosystem, like ggplot2, to get beautiful charts in your documentation.
#ruby #ruby-on-rails #web-development
1622462142
Ruby on Rails Development Services | Ruby on Rails Development
Ruby on Rails is a development tool that offers Web & Mobile App Developers a structure for all the codes they write resulting in time-saving with all the common repetitive tasks during the development stage.
Want to build a Website or Mobile App with Ruby on Rails Framework
Connect with WebClues Infotech, the top Web & Mobile App development company that has served more than 600 clients worldwide. After serving them with our services WebClues Infotech is ready to serve you in fulfilling your Web & Mobile App Development Requirements.
Want to know more about development on the Ruby on Rails framework?
Visit: https://www.webcluesinfotech.com/ruby-on-rails-development/
Share your requirements https://www.webcluesinfotech.com/contact-us/
View Portfolio https://www.webcluesinfotech.com/portfolio/
#ruby on rails development services #ruby on rails development #ruby on rails web development company #ruby on rails development company #hire ruby on rails developer #hire ruby on rails developers
1594674000
Day 14 of 30 Ruby Coding Challenge - Fibonacci Sequence the Ruby Way
Day 14 of 30. We’re going to solve the famous Fibonacci sequence in a more Ruby Way, which will be much better (hopefully!) than the previous solution
Hey friends!
This is the blog post version of the Youtube video from the 30 Ruby Coding Challenges in 30 Days series
Fibonacci Sequence
It’s time to organize the kitchen and to get a better code design to solve the Fibonacci Sequence, which was the previous coding challenge:
We want to calculate the first N numbers in a Fibonacci sequence
This was the last coding solution:
Ruby
def fibonacci(count)
n1 = 0
n2 = 1
sequence = [n1, n2]
while count > 2
# sum of the previous 2 numbers
n3 = n1 + n2
sequence.push(n3)
# assigning the new numbers to calculate the next number in the sequence
n1 = n2
n2 = n3
count = count - 1
end
return sequence
end
puts fibonacci(8)
# 0 1 1 2 3 5 8 13
```
You can be honest, it's not that great.
## The Ruby Way to Solve the Fibonacci Problem
### **Step 1**
Ruby allows us to go from one number to another in a sequence like this:
Ruby
```
(0..10).each do |number|
end
In our example we want to avoid the count mutation (fancy name for change). We can do that by the following code:
Ruby
(0…count).each do |number|
end
```
That’s great because Ruby will **automatically iterate over the array**
### **Step 2**
A better way to store the number in the sequence would be:
Ruby
```
sequence << number if number <= 1
sequence << sequence[-1] + sequence[-2] if sequence.length >= 2
The complete code, a little bit leaner with a better strategy, would be:
Ruby
def fibonacci(count)
sequence = []
(0…count).each do |number|
sequence << number if number <= 1
sequence << sequence[-1] + sequence[-2] if sequence.length >= 2
end
sequence
end
```
Fantastic! Ruby deals with the problem really well!#ruby #programming #coding #ruby on rails #algorithm #fibonacci #tutorial for beginners #algorithm analysis #coding basics #coding challenges
1594449660
Day 16 of 30 Ruby Coding Challenge - Sum Even Numbers
DZone > Web Dev Zone > Day 16 of 30 Ruby Coding Challenge - Sum Even Numbers in a Fibonacci Sequence
Day 16 of 30 Ruby Coding Challenge - Sum Even Numbers in a Fibonacci Sequence
Hey friends!
This is the blog post version of the Youtube video from the 30 Ruby Coding Challenges in 30 Days series
We’ve solved the Fibonacci sequence here, here and here, which means that we have some clues of how to create a Fibonacci sequence :)
Today we want to be a little bit daring by solving the following problem:
I want to sum all even numbers in a Fibonacci sequence
Fibonacci Sequence in Ruby
As you already know, this is one of the solutions:
Ruby
1
def fibonacci_sum(count)
2
number = 0
3
sequence = []
4
(0..count).each do |item|
5
number = item if item <= 1
6
number = sequence[-1] + sequence[-2] if item > 1
7
sequence << number
8
end
9
sequence
10
end
We’re returning a Fibonacci sequence, however, that’s not what we’re looking for
Sum Even Numbers in a Fibonacci Sequence in Ruby
We’re going to:
- add a local variable called sum
- then update this variable only if the number is even
- return the sum variable
Ruby
1
def fibonacci_sum(count)
2
sum = 0
3
number = 0
4
sequence = []
5
(0..count).each do |item|
6
number = item if item <= 1
7
number = sequence[-1] + sequence[-2] if item > 1
8
sequence << number
9
10
sum += number if number % 2 == 0
11
end
12
sum
13
end
#ruby #programming #coding #ruby on rails #algorithm #challenges #tutorial for beginners #algorithm analysis #coding basics