medic 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de19fe133b21f0149428e905fed5cae6920e29d1
-  data.tar.gz: 7481827c1465cc8695b4edcb18e5e89a89244d1a
+  metadata.gz: bf3a75beba5a3f3be3df75476d6d18d188752bac
+  data.tar.gz: 01bb258ba550c735090e7d04df792972562f4f91
 SHA512:
-  metadata.gz: 2ba5162cf3304ba27edbf19e9b7c99d09035d295c4f1815f66bced596d30021717f9ec6c0dd4865b8b9cc375edd094407221cbf02709b3c5876cfda0f6069680
-  data.tar.gz: 625255212fed825cae342212d3d944c61c2317c459b3ccc5507545feccb7fc141f3176b03d7eae8fc367b0e87cb9c52b48cb2ad9e7051a28365ee8f6e81fbd20
+  metadata.gz: 02ff5adbb1f076e1e95fee777d4d5289e0bd1eb73808f32d3ee90a6b2a45aafc27b13e323ea96885e55294e4356d2eb783cbd02e7b271287a7dc1afa07df7fa1
+  data.tar.gz: 780718864993970ea3889ac42df1627066152d3862aab9be21f7f5eded7b146195874fff3c1a68497dc46b14482aa5348f089c70eac31e9572250511ee34ca8e

data/README.md

@@ -1,24 +1,224 @@
-# medic
+# Medic [![Gem Version](https://badge.fury.io/rb/medic.svg)](http://badge.fury.io/rb/medic) [![Build Status](https://travis-ci.org/ryanlntn/medic.svg)](https://travis-ci.org/ryanlntn/medic) [![Code Climate](https://codeclimate.com/github/ryanlntn/medic/badges/gpa.svg)](https://codeclimate.com/github/ryanlntn/medic) [![Dependency Status](https://gemnasium.com/ryanlntn/medic.svg)](https://gemnasium.com/ryanlntn/medic)
 
-TODO: Write a gem description
+Is HealthKit's verbose and convoluted API driving you to autolobotomization? Quick! You need a medic!
 
 ## Installation
 
-Add this line to your application's Gemfile:
+1. Add this line to your application's Gemfile:
 
-    gem 'medic'
+  ```ruby
+  gem 'medic'
+  ```
 
-And then execute:
+1. Add the following lines to your Rakefile:
 
-    $ bundle
+  ```ruby
+  app.entitlements['com.apple.developer.healthkit'] = true
+  app.frameworks += ['HealthKit']
+  ```
 
-Or install it yourself as:
-
-    $ gem install medic
+1. Run `bundle` and `rake`.
 
 ## Usage
 
-TODO: Write usage instructions here
+### Authorization
+
+To request authorization to read or share (i.e. write) a data type implement the following in `viewDidAppear` of your `UIViewController`:
+
+```ruby
+if Medic.available?
+  types = { share: :step_count, read: [:step_count, :date_of_birth] }
+
+  Medic.authorize types do |success, error|
+    NSLog "Success!" if success
+  end
+end
+```
+
+This will open the permissions modal. `success` will be `false` if the user canceled the prompt without selecting permissions; `true` otherwise.
+
+You can subsequently check if you're authorized to share a data type:
+
+```ruby
+Medic.authorized?(:step_count)
+```
+
+Note: For privacy reasons Apple does not allow you to check if you're authorized to read data types.
+
+### Sharing Samples
+
+Coming soon...
+
+### Reading Data
+
+HealthKit provides a number of methods for accessing its data, mostly in the form of query objects with verbose initializers that return more `HKObject`s with repetitive method names. For example, if I wanted to get the total number of steps taken per day for the last week I could use a `HKStatisticsCollectionQuery` like so:
+
+```ruby
+@store = HKHealthStore.new
+
+today = NSDate.date
+one_week_ago = NSCalendar.currentCalendar.dateByAddingComponents(NSDateComponents.new.setDay(-7), toDate: today, options: 0)
+
+query = HKStatisticsCollectionQuery.initWithQuantityType(
+          HKObjectType.quantityTypeForIdentifier(HKQuantityTypeIdentifierStepCount),
+          quantitySamplePredicate: nil,
+          options: HKStatisticsOptionCumulativeSum,
+          anchorDate: one_week_ago,
+          intervalComponents: (NSDateComponents.new.day = 1)
+        )
+
+query.initialResultsHandler = ->(query, results, error){
+  results.enumerateStatisticsFromDate(one_week_ago, toDate: today, withBlock: ->(result, stop){
+    if quantity = result.sumQuantity
+      NSLog quantity.doubleValueForUnit(HKUnit.countUnit).to_s
+    end
+  })
+}
+
+@store.executeQuery(query)
+```
+
+This doesn't make for the most readable code. As a Ruby developer you might find this downright distasteful. Let's check out the Medic equivalent:
+
+```ruby
+options = { options: :sum, anchor: :one_week_ago, interval: :day}
+
+Medic.find_statistics_collection :step_count, options do |statistics|
+  statistics.each do |stats|
+    NSLog stats[:sum].to_s
+  end
+end
+```
+
+Now that's more like it! Instead of constructing `HKObjectType` by hand we can now just pass in a symbol. We also don't have to work directly with `HKStatisticsCollection` anymore. The result is parsed into an array of hashes with reasonable values for us.
+
+#### Finders
+
+Medic provides a finder for each class of `HKQuery`:
+
+##### find_anchored
+
+Provide an easy way to search for new data in the HealthKit store.
+
+```ruby
+@anchor = nil
+
+Medic.find_anchored :step_count, anchor: @anchor do |results, new_anchor|
+  @anchor = new_anchor
+  results.each do |sample|
+    NSLog sample.to_s
+  end
+end
+```
+
+##### find_correlation
+
+Search for correlations in the HealthKit store.
+
+```ruby
+high_cal = HKQuantity.quantityWithUnit(HKUnit.kilocalorieUnit, doubleValue: 800.0)
+greater_than_high_cal = HKQuery.predicateForQuantitySamplesWithOperatorType(NSGreaterThanOrEqualToPredicateOperatorType, quantity: high_cal)
+
+sample_predicates = { dietary_energy_consumed: greater_than_high_cal }
+
+Medic.find_correlations :food, sample_predicates: sample_predicates do |correlations|
+  correlations.each do |correlation|
+    NSLog correlation.to_s
+  end
+end
+```
+
+##### observe
+
+Set up a long-running task on a background queue.
+
+```ruby
+Medic.observe :step_count do |completion, error|
+  Medic.find_sources :step_count do |sources|
+    sources.each do |source|
+      NSLog source
+    end
+  end
+end
+```
+
+##### find_samples
+
+Search for sample data in the HealthKit store.
+
+```ruby
+Medic.find_samples :blood_pressure, sort: :start_date, limit: 7 do |samples|
+  samples.each do |sample|
+    NSLog sample.to_s
+  end
+end
+```
+
+##### find_sources
+
+Search for the sources (apps and devices) that have saved data to the HealthKit store.
+
+```ruby
+Medic.find_sources :step_count do |sources|
+  sources.each do |source|
+    NSLog source
+  end
+end
+```
+
+##### find_statistics
+
+Perform statistical calculations over the set of matching quantity samples.
+
+```ruby
+Medic.find_statistics :step_count, options: :sum do |statistics|
+  NSLog statistics.to_s
+end
+```
+
+##### find_statistics_collection
+
+Perform multiple statistics queries over a series of fixed-length time intervals.
+
+```ruby
+options = { options: :sum, anchor: :one_week_ago, interval: :day}
+
+Medic.find_statistics_collection :step_count, options do |statistics|
+  statistics.each do |stats|
+    NSLog stats[:sum].to_s
+  end
+end
+```
+
+#### Characteristic Data
+
+Characteristic data like biological sex or blood type have their own methods:
+
+```ruby
+Medic.biological_sex # => :male
+Medic.date_of_birth  # => 1987-11-07 00:00:00 -0800
+Medic.blood_type     # => :o_negative
+```
+
+#### Queries
+
+If for some reason you need to access the `HKSample` objects directly you can use Medic's Query objects:
+
+```ruby
+query_params = { type: :dietary_protein, sort_desc: :start_date, limit: 7 }
+
+query = Medic::SampleQuery.new query_params do |query, results, error|
+  if results
+    results.each do |sample|
+      NSLog "#{sample.startDate} - #{sample.quantity.doubleValueForUnit(HKUnit.gramUnit)}"
+    end
+  else
+    NSLog "no results"
+  end
+end
+
+Medic.execute(query)
+```
 
 ## Contributing
 

data/lib/medic.rb

@@ -1,10 +1,8 @@
-# encoding: utf-8
-
 unless defined?(Motion::Project::Config)
   raise "This file must be required within a RubyMotion project Rakefile."
 end
 
 lib_dir_path = File.dirname(File.expand_path(__FILE__))
 Motion::Project::App.setup do |app|
-  app.files.unshift(Dir.glob(File.join(lib_dir_path, "project/**/*.rb")))
+  app.files.unshift(Dir.glob(File.join(lib_dir_path, "medic/**/*.rb")))
 end

data/lib/medic/anchor.rb

@@ -0,0 +1,32 @@
+module Medic
+  module Anchor
+
+    NUMBER_WORDS = {
+      'zero' => 0, 'one' => 1, 'two' => 2, 'three' => 3, 'four' => 4, 'five' => 5,
+      'six' => 6, 'seven' => 7, 'eight' => 8, 'nine' => 9, 'ten' => 10, 'eleven' => 11,
+      'twelve' => 12, 'thirteen' => 13, 'fourteen' => 14, 'fifteen' => 15, 'sixteen' => 16,
+      'seventeen' => 17, 'eighteen' => 18, 'nineteen' => 19, 'twenty' => 20, 'thirty' => 30,
+      'fourty' => 40, 'fifty' => 50, 'sixty' => 60, 'seventy' => 70, 'eighty' => 80,
+      'ninety' => 90, 'hundred' => 100
+    }
+
+    def anchor_for_symbol(sym)
+      return unless sym
+      return sym if sym.to_s == '0'
+      return sym if sym.is_a? NSDate
+      parts = sym.to_s.gsub('_', ' ').split.reject{ |part| part == 'ago' }
+      component = parts.pop.chomp('s')
+      n = parts.map{|p| NUMBER_WORDS[p] || p.to_i}.reduce do |sum, p|
+        if p == 100 && sum > 0
+          sum * p
+        else
+          sum + p
+        end
+      end
+      n ||= 1
+      date_comp = NSDateComponents.new.send("#{component}=", -n)
+      NSCalendar.currentCalendar.dateByAddingComponents(date_comp, toDate: NSDate.date, options: 0)
+    end
+
+  end
+end

data/lib/medic/anchored_object_query.rb

@@ -0,0 +1,18 @@
+module Medic
+  class AnchoredObjectQuery < HKAnchoredObjectQuery
+
+    include Medic::Types
+    include Medic::Predicate
+    include Medic::Anchor
+
+    def initialize(args={}, block=Proc.new)
+      self.initWithType(object_type(args[:type]),
+        predicate: predicate(args),
+        anchor: anchor_for_symbol(args[:anchor_date] || args[:anchor] || args[:date] || HKAnchoredObjectQueryNoAnchor),
+        limit: args[:limit] || HKObjectQueryNoLimit,
+        completionHandler: block
+      )
+    end
+
+  end
+end

data/lib/medic/correlation_query.rb

@@ -0,0 +1,22 @@
+module Medic
+  class CorrelationQuery < HKCorrelationQuery
+
+    include Medic::Types
+    include Medic::Predicate
+
+    def initialize(args={}, block=Proc.new)
+      self.initWithType(object_type(args[:type]),
+        predicate: predicate(args),
+        samplePredicates: sample_predicates(args[:sample_predicates]),
+        completion: block
+      )
+    end
+
+  private
+
+    def sample_predicates(predicates)
+      Hash[ predicates.map{ |type, pred| [object_type(type), predicate(pred)] } ]
+    end
+
+  end
+end

data/lib/medic/finders.rb

@@ -0,0 +1,122 @@
+module Medic
+  module Finders
+
+    def observe(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::ObserverQuery.new query_params do |query, completion, error|
+        block.call(completion, error)
+      end
+      Medic.execute(query)
+    end
+
+    def find_sources(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::SourceQuery.new query_params do |query, results, error|
+        sources = results ? results.allObjects.map{ |source| source.name.to_s } : []
+        block.call(sources)
+      end
+      Medic.execute(query)
+    end
+
+    def find_samples(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::SampleQuery.new query_params do |query, results, error|
+        block.call(samples_to_hashes(Array(results)))
+      end
+      Medic.execute(query)
+    end
+
+    def find_correlations(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::CorrelationQuery.new query_params do |query, correlations, error|
+        block.call(samples_to_hashes(Array(correlations)))
+      end
+      Medic.execute(query)
+    end
+
+    def find_anchored(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::AnchoredObjectQuery.new query_params do |query, results, new_anchor, error|
+        block.call(samples_to_hashes(Array(results)), new_anchor)
+      end
+      Medic.execute(query)
+    end
+
+    def find_statistics(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::StatisticsQuery.new query_params do |query, statistics, error|
+        block.call(statistics_to_hash(statistics)) if statistics
+      end
+      Medic.execute(query)
+    end
+
+    def find_statistics_collection(type, options={}, block=Proc.new)
+      query_params = options.merge(type: type)
+      query = Medic::StatisticsCollectionQuery.new query_params do |query, collection, error|
+        formatted_stats = []
+        collection.enumerateStatisticsFromDate(collection.anchorDate, toDate: NSDate.date, withBlock: ->(result, stop){
+          formatted_stats << statistics_to_hash(result)
+        })
+        block.call(formatted_stats)
+      end
+      Medic.execute(query)
+    end
+
+  private
+
+    def samples_to_hashes(samples)
+      samples.map do |sample|
+        h = {}
+        h[:uuid] = sample.UUID.UUIDString
+        h[:metadata] = sample.metadata
+        h[:source] = sample.source.name
+        h[:start_date] = sample.startDate
+        h[:end_date] = sample.endDate
+        h[:sample_type] = Medic::Types::TYPE_IDENTIFIERS.index(sample.sampleType.identifier)
+
+        if sample.respond_to?(:categoryType) && sample.respond_to?(:value)
+          h[:category_type] = Medic::Types::TYPE_IDENTIFIERS.index(sample.categoryType.identifier)
+          h[:value] = [:in_bed, :asleep][sample.value] # SleepAnalysis is the only category type at the moment
+        end
+
+        if sample.respond_to?(:correlationType) && sample.respond_to?(:objects)
+          h[:correlation_type] = Medic::Types::TYPE_IDENTIFIERS.index(sample.correlationType.identifier)
+          h[:objects] = samples_to_hashes(Array(sample.objects.allObjects))
+        end
+
+        if sample.respond_to?(:quantity) && sample.respond_to?(:quantityType)
+          h[:quantity] = sample.quantity.doubleValueForUnit(sample.quantityType.canonicalUnit)
+          h[:quantity_type] = Medic::Types::TYPE_IDENTIFIERS.index(sample.quantityType.identifier)
+          h[:canonical_unit] = sample.quantityType.canonicalUnit.unitString
+        end
+
+        h[:duration] = sample.duration if sample.respond_to?(:duration)
+        h[:total_distance] = sample.totalDistance if sample.respond_to?(:totalDistance)
+        h[:total_energy_burned] = sample.totalEnergyBurned if sample.respond_to?(:totalEnergyBurned)
+        h[:workout_activity_type] = sample.workoutActivityType if sample.respond_to?(:workoutActivityType)
+        h[:workout_events] = sample.workoutEvents  if sample.respond_to?(:workoutEvents)
+        h
+      end
+    end
+
+    def statistics_to_hash(stats)
+      h = {}
+      h[:start_date] = stats.startDate
+      h[:end_date] = stats.endDate
+      h[:sources] = stats.sources.map(&:name) if stats.sources
+      h[:quantity_type] = Medic::Types::TYPE_IDENTIFIERS.index(stats.quantityType.identifier)
+      h[:canonical_unit] = stats.quantityType.canonicalUnit.unitString
+      h[:data_count] = stats.dataCount
+      h[:average] = stats.averageQuantity.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.averageQuantity
+      h[:minimum] = stats.minimumQuantity.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.minimumQuantity
+      h[:maximum] = stats.maximumQuantity.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.maximumQuantity
+      h[:sum] = stats.sumQuantity.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.sumQuantity
+      h[:average_by_source] = stats.averageQuantityBySource.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.averageQuantityBySource
+      h[:minimum_by_source] = stats.minimumQuantityBySource.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.minimumQuantityBySource
+      h[:maximum_by_source] = stats.maximumQuantityBySource.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.maximumQuantityBySource
+      h[:sum_by_source] = stats.sumQuantityBySource.doubleValueForUnit(stats.quantityType.canonicalUnit) if stats.sumQuantityBySource
+      h
+    end
+
+  end
+end