Land, sky, and sea
Ruby
Pull request Compare This branch is 455 commits behind faradayio:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
features
lib
spec
vendor
.document
.gitignore
Gemfile
Guardfile
LICENSE
LICENSE-PREAMBLE
README.markdown
Rakefile
TODO
certification_changelog.markdown
earth.gemspec

README.markdown

earth

Earth is a collection of data models that represent various things found here on Earth, such as pet breeds, kinds of rail travel, zip codes, and Petroleum Administration for Defense Districts.

The data that these models represent can be pulled from preconfigured authoritative sources.

Usage

require 'earth'
Earth.init :automobile, :locality
ft = AutomobileFuel.first
# ...

Earth.init loads desired "data domains" as well as any supporting classes and plugins that each data model needs. A "data domain" is a grouping of related data models. For instance, all automobile-related data is in the :automobile domain.

Domains

Domain Models
:air Aircraft, Airline, Airport ...
:automobile AutomobileFuel, AutomobileMake, AutomobileModel ...
:bus BusClass, BusFuel ...
:computation ComputationCarrier, ComputationCarrierInstanceClass ...
:diet DietClass, FoodGroup ...
:fuel Fuel, FuelPrice, GreenhouseGas ...
:hospitality LodgingClass, CommercialBuildingEnergyConsumptionSurveyResponse ...
:industry Industry, CbecsEnergyIntensity ...
:locality CensusDivision, Country, ZipCode ...
:pet Breed, Gender, Species ...
:rail RailClass, RailFuel, RailCompany ...
:residence Urbanity, ResidenceClass, AirConditionerUse
:shipping Carrier, ShipmentMode ...

Data storage

You can store Earth data in any relational database. On your very first run, you will need to create the tables for data each model. This is done using minirecord with the apply_schemas option:

require 'activerecord'
ActiveRecord::Base.establish_connection :adapter => ...   # Not needed if using Rails

require 'earth'
Earth.init :all, :apply_schemas => true

Pulling data from data.brighterplanet.com

By default, Earth will pull data from data.brighterplanet.com, which continuously (and transparently) refreshes its data from authoritative sources. Simply call #run_data_miner! on whichever data model class you need. If there are any Earth classes that the chosen class depends on, they will be downloaded as well automatically:

require 'earth'
Earth.init :locality
ZipCode.run_data_miner!

Pulling data from the original sources

If you'd like to bypass the data.brighterplanet.com proxy and pull data directly from authoritative sources (e.g., automobile data from EPA), simply require the data\_miner file for the desired domain:

require 'earth'
Earth.init :automobile

require 'earth/automobile/data_miner'
AutomobileMake.run_data_miner!

Collaboration cycle

Brighter Planet vigorously encourages collaborative improvement.

You

  1. Fork the earth repository on GitHub.
  2. Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
  3. Improve the code until your new test passes and commit your changes.
  4. Push your changes to your GitHub fork.
  5. Submit a pull request to brighterplanet.

Brighter Planet

  1. Receive a pull request.
  2. Pull changes from forked repository.
  3. Ensure tests pass.
  4. Review changes for scientific accuracy.
  5. Merge changes to master repository and publish.
  6. Direct production environment to use new library version.