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 the active_record_inline_schema library if you pass 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
- Fork the earth repository on GitHub.
- Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
- Improve the code until your new test passes and commit your changes.
- Push your changes to your GitHub fork.
- Submit a pull request to brighterplanet.
Brighter Planet
- Receive a pull request.
- Pull changes from forked repository.
- Ensure tests pass.
- Review changes for scientific accuracy.
- Merge changes to master repository and publish.
- Direct production environment to use new library version.