sciolyff-duosmium 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f8d723a4b5265cf85a60231c83d8f1eeea0558cc0f6c8f2e51572bca2a86e6f
+  data.tar.gz: b733acad947c8c180011279e4681c086bc94d78efb920433f6e0d72333c3b8e9
+SHA512:
+  metadata.gz: 62fddbdf4bb9e9e953678a9cf87487c9f68b97b082cc9be825f384933ae06093923dfbc1966aa7c1a5f8ff7fd60107216f43ef9014fb09d5d57b6eba9fff76cb
+  data.tar.gz: beef2bd6cad0cf430f7699b515a85459881ef1c3f4602ef622046e2f62024d52917eafe63418aa27825ea8dc41c5aa1601b57c327b8376456940c001e17816cf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Em Zhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# SciolyFF (Science Olympiad File Format)
+
+[![Gem Version](https://badge.fury.io/rb/sciolyff.svg)](https://badge.fury.io/rb/sciolyff)
+
+We propose a standardized file format called SciolyFF to represent Science
+Olympiad tournament results. This will allow for a more universal record of
+tournament performance and also make it easier to do sabermetric-like stats and
+other fun stuff. The format is a subset of YAML for easy implementation of
+parsers across many programming languages.
+
+A website that generates results tables based off SciolyFF files can be found
+[here](https://unosmium.org/results/) and the source code for the website
+[here](https://github.com/unosmium/unosmium.org).
+
+## Specification
+
+Reading through the demo file [here](examples/demo.yaml) is probably the fastest
+way to get acquainted with the format. Officially, any file that passes the
+validation (see Usage -- Validation) is valid, but the intentions of the format
+outlined in the comments of the demo file should be respected.
+
+## Installation
+
+```
+gem install sciolyff
+```
+
+This gem is currently in an alpha stage. To get the latest changes before
+official releases, build from source:
+
+```
+git clone https://github.com/unosmium/sciolyff.git && cd sciolyff
+gem build sciolyff.gemspec
+gem install ./sciolyff-0.12.0.gem
+```
+
+## Usage
+
+### Validation
+
+A Ruby gem provided in this repository contains a command line utility that can
+validate if a given file meets the SciolyFF. The files found in
+`lib/sciolyff/validator` also serve as the specification for the format.
+
+From the command line, e.g.
+
+```
+sciolyff 2017-05-20_nationals_c.yaml
+```
+
+Inside Ruby code, e.g.
+
+```ruby
+require 'sciolyff'
+
+validator = SciolyFF::Validator.new
+puts validator.valid? File.read('2017-05-20_nationals_c.yaml') #=> true
+print validator.last_log #=> error or warning messages
+```
+
+### Parsing
+
+Although the SciolyFF makes the results file human-readable without the
+ambiguity of spreadsheet results, it can be a bit awkward to parse overall
+results -- for instance, when trying to regenerate a results spreadsheet from a
+SciolyFF file.
+
+To make this easier, a `SciolyFF::Interpreter` class has been provided to wrap
+the output of Ruby's yaml parser. For example:
+
+```ruby
+require 'sciolyff'
+
+i = SciolyFF::Interpreter.new(File.read('2017-05-20_nationals_c.yaml'))
+
+a_and_p = i.events.find { |e| e.name == 'Anatomy and Physiology' }
+a_and_p.trialed? #=> false
+
+team_one = i.teams.find { |t| t.number == 1 }
+team_one.placing_for(a_and_p).points #=> 7
+team_one.points #=> 448
+
+# sorted by rank
+i.teams #=> [#<...{:school=>"Troy H.S.", :number=>3, :state=>"CA"}>, ... ]
+```
+
+A fuller example can be found here in the code for the Unosmium Results website,
+found
+[here](https://github.com/unosmium/unosmium.org/blob/master/source/results/template.html.erb).
+There is also of course the
+[documentation](https://www.rubydoc.info/gems/sciolyff/0.12.0), a bit sparse
+currently.

data/bin/sciolyff

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optimist'
+require 'sciolyff'
+
+opts = Optimist.options do
+  version 'sciolyff 0.13.0'
+  banner <<~STRING
+    Checks if a given file is in the Scioly File Format
+
+    Usage:
+            #{File.basename(__FILE__)} [options] <file>
+
+    where [options] are:
+  STRING
+  opt :loglevel, 'Log verbosity from 0 to 3', default: 1
+  opt :nocanon, 'Disable canonical name checks'
+end
+
+Optimist.educate if ARGV.empty?
+puts 'More than one file given, ignoring all but first.' if ARGV.length > 1
+
+begin
+  contents = File.read(ARGV.first)
+rescue StandardError => e
+  puts "Could not read file: #{e}"
+  exit 1
+end
+
+validator = SciolyFF::Validator.new(
+  loglevel: opts[:loglevel],
+  canonical: !opts[:nocanon]
+)
+validity = validator.valid? contents
+print validator.last_log
+
+exit validity

data/lib/sciolyff.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'open-uri'
+require 'psych'
+require 'date'
+
+require 'sciolyff/interpreter'
+require 'sciolyff/validator'

data/lib/sciolyff/interpreter.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module SciolyFF
+  # Interprets the YAML representation of a SciolyFF file through objects that
+  # respond to idiomatic Ruby method calls
+  class Interpreter
+    require 'sciolyff/interpreter/tournament'
+    require 'sciolyff/interpreter/event'
+    require 'sciolyff/interpreter/team'
+    require 'sciolyff/interpreter/placing'
+    require 'sciolyff/interpreter/penalty'
+
+    require 'sciolyff/interpreter/tiebreaks'
+    require 'sciolyff/interpreter/subdivisions'
+    require 'sciolyff/interpreter/html'
+
+    attr_reader :tournament, :events, :teams, :placings, :penalties
+
+    def initialize(rep)
+      if rep.instance_of? String
+        rep = Psych.safe_load(rep,
+                              permitted_classes: [Date],
+                              symbolize_names: true)
+      end
+      create_models(@rep = rep)
+      link_models(self)
+
+      sort_events_naturally
+      sort_teams_by_rank
+    end
+
+    def subdivisions
+      @subdivisions ||=
+        teams.map(&:subdivision)
+             .uniq
+             .compact
+             .map { |sub| [sub, Interpreter.new(subdivision_rep(sub))] }
+             .to_h
+    end
+
+    def raws?
+      placings.any?(&:raw?)
+    end
+
+    private
+
+    def create_models(rep)
+      @tournament = Tournament.new(rep)
+      @events     = map_array_to_models rep[:Events],    Event,   rep
+      @teams      = map_array_to_models rep[:Teams],     Team,    rep
+      @placings   = map_array_to_models rep[:Placings],  Placing, rep
+      @penalties  = map_array_to_models rep[:Penalties], Penalty, rep
+    end
+
+    def map_array_to_models(arr, object_class, rep)
+      return [] if arr.nil?
+
+      arr.map.with_index { |_, index| object_class.new(rep, index) }
+    end
+
+    def link_models(interpreter)
+      # models have to linked in reverse order because reasons
+      @penalties.each { |m| m.link_to_other_models(interpreter) }
+      @placings .each { |m| m.link_to_other_models(interpreter) }
+      @teams    .each { |m| m.link_to_other_models(interpreter) }
+      @events   .each { |m| m.link_to_other_models(interpreter) }
+      @tournament.link_to_other_models(interpreter)
+    end
+
+    def sort_events_naturally
+      @events.sort_by! { |e| [e.trial?.to_s, e.name] }
+    end
+
+    def sort_teams_by_rank
+      sorted =
+        @teams
+        .group_by { |t| [t.disqualified?.to_s, t.exhibition?.to_s] }
+        .map { |key, teams| [key, sort_teams_by_points(teams)] }
+        .sort_by(&:first)
+        .map(&:last)
+        .flatten
+      @teams.map!.with_index { |_, i| sorted[i] }
+    end
+
+    include Interpreter::Tiebreaks
+    include Interpreter::Subdivisions
+    include Interpreter::HTML
+  end
+end

data/lib/sciolyff/interpreter/bids.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SciolyFF
+  # Bid assignment logic, to be included in the Interpreter::Tournament class
+  module Interpreter::Bids
+    def top_teams_per_school
+      # explicitly relies on uniq traversing in order
+      @top_teams_per_school ||= @teams.uniq { |t| [t.school, t.city, t.state] }
+    end
+
+    def teams_eligible_for_bids
+      return top_teams_per_school if bids_per_school == 1
+
+      # doesn't rely on group_by preserving order
+      @teams_eligible_for_bids ||=
+        @teams
+        .group_by { |t| [t.school, t.city, t.state] }
+        .each_value { |teams| teams.sort_by!(&:rank) }
+        .map { |_, teams| teams.take(bids_per_school) }
+        .flatten
+        .sort_by(&:rank)
+    end
+  end
+end

data/lib/sciolyff/interpreter/event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'sciolyff/interpreter/model'
+
+module SciolyFF
+  # Models an instance of a Science Olympiad event at a specific tournament
+  class Interpreter::Event < Interpreter::Model
+    def link_to_other_models(interpreter)
+      super
+      @placings = interpreter.placings.select { |p| p.event == self }
+      @placings_by_team =
+        @placings.group_by(&:team).transform_values!(&:first)
+      @raws = @placings.select(&:raw?).map(&:raw).sort
+    end
+
+    attr_reader :placings, :raws
+
+    def name
+      @rep[:name]
+    end
+
+    def trial?
+      @rep[:trial] || false
+    end
+
+    def trialed?
+      @rep[:trialed] || false
+    end
+
+    def high_score_wins?
+      !low_score_wins?
+    end
+
+    def low_score_wins?
+      @rep[:scoring] == 'low'
+    end
+
+    def placing_for(team)
+      @placings_by_team[team]
+    end
+
+    def maximum_place
+      @maximum_place ||=
+        if trial?
+          placings.size
+        elsif tournament.per_event_n?
+          [per_event_maximum_place, tournament.maximum_place].min
+        else
+          tournament.maximum_place
+        end
+    end
+
+    private
+
+    def per_event_maximum_place
+      return competing_teams_count if tournament.per_event_n == 'participation'
+
+      placings.map(&:place).compact.max + 1
+    end
+
+    def competing_teams_count
+      return placings.count(&:participated?) if trial?
+
+      placings.count do |p|
+        p.participated? && !(p.team.exhibition? || p.exempt?)
+      end
+    end
+  end
+end

data/lib/sciolyff/interpreter/html.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SciolyFF
+  # Grants ability to convert a SciolyFF file into stand-alone HTML and other
+  # formats (YAML, JSON)
+  module Interpreter::HTML
+    require 'erubi'
+    require 'sciolyff/interpreter/html/helpers'
+    require 'json'
+
+    def to_html(hide_raw: false, color: '#000000')
+      helpers = Interpreter::HTML::Helpers.new
+      src = Erubi::Engine.new(helpers.template).src
+      helpers.eval_with_binding(src, self, hide_raw, color)
+             .gsub(/^\s*$/, '')   # remove empty lines
+             .gsub(/\s+$/, '')    # remove trailing whitespace
+    end
+
+    def to_yaml(hide_raw: false)
+      rep = hide_raw ? hidden_raw_rep : @rep
+      stringify_keys(rep).to_yaml
+    end
+
+    def to_json(hide_raw: false, pretty: false)
+      rep = hide_raw ? hidden_raw_rep : @rep
+      return JSON.pretty_generate(rep) if pretty
+
+      rep.to_json
+    end
+
+    private
+
+    def hidden_raw_rep
+      @hidden_raw_rep || begin
+        @hidden_raw_rep = Marshal.load(Marshal.dump(@rep))
+        @hidden_raw_rep[:Placings].each { |p| hide_and_replace_raw(p) }
+        @hidden_raw_rep
+      end
+    end
+
+    def hide_and_replace_raw(placing_rep)
+      placing = placings.find do |p|
+        p.event.name == placing_rep[:event] &&
+          p.team.number == placing_rep[:team]
+      end
+      placing_rep.delete :raw
+      placing_rep[:tie] = true if placing.tie?
+      placing_rep[:place] = placing.place if placing.place
+    end
+
+    def stringify_keys(hash)
+      return hash unless hash.instance_of? Hash
+
+      hash.map do |k, v|
+        new_k = k.to_s
+        new_v = case v
+                when Array then v.map { |e| stringify_keys(e) }
+                when Hash then stringify_keys(v)
+                else v
+                end
+        [new_k, new_v]
+      end.to_h
+    end
+  end
+end

data/lib/sciolyff/interpreter/html/helpers.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SciolyFF
+  # Holds helper methods used in template.html.erb
+  class Interpreter::HTML::Helpers
+    def template
+      File.read(File.join(__dir__, 'template.html.erb'))
+    end
+
+    def eval_with_binding(src, interpreter, hide_raw, color)
+      i = interpreter
+      css_file_content = File.read(File.join(__dir__, 'main.css'))
+      js_file_content = File.read(File.join(__dir__, 'main.js'))
+      eval(src)
+    end
+
+    private
+
+    STATES_BY_POSTAL_CODE = {
+      AK: 'Alaska',
+      AZ: 'Arizona',
+      AR: 'Arkansas',
+      CA: 'California',
+      nCA: 'Northern California',
+      sCA: 'Southern California',
+      CO: 'Colorado',
+      CT: 'Connecticut',
+      DE: 'Delaware',
+      DC: 'District of Columbia',
+      FL: 'Florida',
+      GA: 'Georgia',
+      HI: 'Hawaii',
+      ID: 'Idaho',
+      IL: 'Illinois',
+      IN: 'Indiana',
+      IA: 'Iowa',
+      KS: 'Kansas',
+      KY: 'Kentucky',
+      LA: 'Louisiana',
+      ME: 'Maine',
+      MD: 'Maryland',
+      MA: 'Massachusetts',
+      MI: 'Michigan',
+      MN: 'Minnesota',
+      MS: 'Mississippi',
+      MO: 'Missouri',
+      MT: 'Montana',
+      NE: 'Nebraska',
+      NV: 'Nevada',
+      NH: 'New Hampshire',
+      NJ: 'New Jersey',
+      NM: 'New Mexico',
+      NY: 'New York',
+      NC: 'North Carolina',
+      ND: 'North Dakota',
+      OH: 'Ohio',
+      OK: 'Oklahoma',
+      OR: 'Oregon',
+      PA: 'Pennsylvania',
+      RI: 'Rhode Island',
+      SC: 'South Carolina',
+      SD: 'South Dakota',
+      TN: 'Tennessee',
+      TX: 'Texas',
+      UT: 'Utah',
+      VT: 'Vermont',
+      VA: 'Virginia',
+      WA: 'Washington',
+      WV: 'West Virginia',
+      WI: 'Wisconsin',
+      WY: 'Wyoming'
+    }.freeze
+
+    def trophy_and_medal_colors
+      %w[
+        #ffee58
+        #cfd8dc
+        #d8bf99
+        #ffefc0
+        #dcedc8
+        #f8bbd0
+        #eeccff
+        #fdd5b4
+        #ebedd8
+        #d4f0f1
+      ]
+    end
+
+    def trophy_and_medal_css(trophies, medals)
+      trophy_and_medal_colors.map.with_index do |color, i|
+        [
+          ("td.event-points[data-points='#{i+1}'] div" if i < medals),
+          ("td.event-points-focus[data-points='#{i+1}'] div" if i < medals),
+          ("div#team-detail tr[data-points='#{i+1}']" if i < medals),
+          ("td.rank[data-points='#{i+1}'] div" if i < trophies)
+        ].compact.join(',') + "{background-color: #{color};border-radius: 1em;}"
+      end.join +
+      trophy_and_medal_colors.map.with_index do |color, i|
+        "div#team-detail tr[data-points='#{i+1}'] td:first-child" if i < medals
+      end.compact.join(',') + "{padding-left: 0.5em;}"
+    end
+
+    def tournament_title(t_info)
+      return t_info.name if t_info.name
+
+      case t_info.level
+      when 'Nationals'
+        'Science Olympiad National Tournament'
+      when 'States'
+        "#{expand_state_name(t_info.state)} Science Olympiad State Tournament"
+      when 'Regionals'
+        "#{t_info.location} Regional Tournament"
+      when 'Invitational'
+        "#{t_info.location} Invitational"
+      end
+    end
+
+    def tournament_title_short(t_info)
+      case t_info.level
+      when 'Nationals'
+        'National Tournament'
+      when 'States'
+        "#{t_info.state} State Tournament"
+      when 'Regionals', 'Invitational'
+        t_info.short_name
+      end
+    end
+
+    def expand_state_name(postal_code)
+      STATES_BY_POSTAL_CODE[postal_code.to_sym]
+    end
+
+    def format_school(team)
+      if team.school_abbreviation
+        abbr_school(team.school_abbreviation)
+      else
+        abbr_school(team.school)
+      end
+    end
+
+    def abbr_school(school)
+      school.sub('Elementary School', 'Elementary')
+            .sub('Elementary/Middle School', 'E.M.S.')
+            .sub('Middle School', 'M.S.')
+            .sub('Junior High School', 'J.H.S.')
+            .sub(%r{Middle[ /-]High School}, 'M.H.S')
+            .sub('Junior/Senior High School', 'Jr./Sr. H.S.')
+            .sub('High School', 'H.S.')
+            .sub('Secondary School', 'Secondary')
+    end
+
+    def full_school_name(team)
+      location = if team.city then "(#{team.city}, #{team.state})"
+                 else              "(#{team.state})"
+                 end
+      [team.school, location].join(' ')
+    end
+
+    def full_team_name(team)
+      location = if team.city then "(#{team.city}, #{team.state})"
+                 else              "(#{team.state})"
+                 end
+      [team.school, team.suffix, location].join(' ')
+    end
+
+    def team_attended?(team)
+      team
+        .placings
+        .map(&:participated?)
+        .any?
+    end
+
+    def summary_titles
+      %w[
+        Champion
+        Runner-up
+        Third-place
+        Fourth-place
+        Fifth-place
+        Sixth-place
+      ]
+    end
+
+    def sup_tag(placing)
+      exempt = placing.exempt? || placing.dropped_as_part_of_worst_placings?
+      tie = placing.tie? && !placing.points_limited_by_maximum_place?
+      return '' unless tie || exempt
+
+      "<sup>#{'◊' if exempt}#{'*' if tie}</sup>"
+    end
+
+    def bids_sup_tag(team)
+      return '' unless team.earned_bid?
+
+      "<sup>✧</sup>"
+    end
+
+    def bids_sup_tag_note(tournament)
+      next_tournament = if tournament.level == 'Regionals'
+                          "#{tournament.state} State Tournament"
+                        else
+                          "National Tournament"
+                        end
+      qualifiee = tournament.bids_per_school > 1 ? 'team' : 'school'
+      "Qualified #{qualifiee} for the #{tournament.year} #{next_tournament}"
+    end
+
+    def placing_notes(placing)
+      place = placing.place
+      points = placing.isolated_points
+      [
+        ('trial event' if placing.event.trial?),
+        ('trialed event' if placing.event.trialed?),
+        ('disqualified' if placing.disqualified?),
+        ('did not participate' if placing.did_not_participate?),
+        ('participation points only' if placing.participation_only?),
+        ('tie' if placing.tie?),
+        ('exempt' if placing.exempt?),
+        ('points limited' if placing.points_limited_by_maximum_place?),
+        ('unknown place' if placing.unknown?),
+        ('placed behind exhibition team'\
+         if placing.points_affected_by_exhibition? && place - points == 1),
+        ('placed behind exhibition teams'\
+         if placing.points_affected_by_exhibition? && place - points > 1),
+        ('dropped'\
+         if placing.dropped_as_part_of_worst_placings?)
+      ].compact.join(', ').capitalize
+    end
+  end
+end