search

bracketclub / bracket-data

Get some helpful data for a tournament bracket.
MIT License
5 stars 1 forks source link
bracketclub

readme

bracket-data

Note: This package is now located in the bracketclub/bracketclub monorepo.

Get some helpful data for a tournament bracket.

NPM

What is a bracket?

From wikipedia:

A bracket is a tree diagram that represents the series of games played during a tournament, named as such because it appears to be a large number of interconnected (punctuational) brackets.

But if you're going to use this, you probably already know that :).

What does this module do?

Let's say you like writing code, and you like brackets, and then one day you want to write some code about brackets. Well, you'll probably need some data first. bracket-data aims to have this data for you separated by sport and year, as well as some helpers to make it easier to interact with that data.

API

This module can be used in Node or the browser. All of the following examples are extracting the same data.

In Node, you can require the module as normally would:

// Node usage
var ncaam2013 = require("bracket-data")({
  year: "2013",
  sport: "ncaam"
});

In a browser, the files are provided prebuilt so that you don't include the whole bundle.

// For usage in a browser without bundling data for any other sport/year
var ncaam2013 = require("bracket-data/browser/ncaam-2013");

If you don't care about including all the data for every sport/year, then you can still require it normally:

// Browser usage, although this bundles data for every sport/year
var ncaam2013 = require("bracket-data")({
  year: "2013",
  sport: "ncaam"
});

Other Scripts

This module has a few helper scripts which are used to make certain things easier.

npm run bracketology

This will take the current year's teams from the ESPN Bracketology website and write them to the current year's JSON files. These usually wont be 100% accurate but will allow you to get some of the current year's data to test and is useful when the teams wont be selected for a few weeks.

npm run names -- ncaam 2018 [URLS]

This will check the URLs for a full list of team names and reference them against the list of teams in the provided sport/year combination to make sure no teams are missing.

What data does this module give me?

Hopefully enough to display an interactive bracket. There are many other modules for doing things like explicity validating, scoring and updating a bracket.

Here are the specific properties with examples from the ncaam-2013 bracket. Keep in mind, that the data will change based on the number of teams in the bracket, the number of regions and which teams.

{
  "regions": {
    "MW": {
      "name": "Midwest",
      "fullname": "Midwest Region",
      "sameSideAs": "W",
      "teams": [
        "Louisville",
        "Duke",
        "Michigan State",
        "Saint Louis",
        "Oklahoma State",
        "Memphis",
        "Creighton",
        "Colorado State",
        "Missouri",
        "Cincinnati",
        "Saint Mary's",
        "Oregon",
        "New Mexico State",
        "Valparaiso",
        "Albany",
        "North Carolina A&T"
      ],
      "id": "MW"
    },
    /* other regions... */
    "FF": {
      "id": "FF",
      "name": "Final Four"
    }
}
MW18124637211232121W19121361410291362929S185411371514315434E1912463721432434FFMWSMW
{
  "REGION_COUNT": 4,
  "REGION_IDS": [
    "MW",
    "W",
    "S",
    "E"
  ],
  "FINAL_ID": "FF",
  "ALL_IDS": [
    "MW",
    "W",
    "S",
    "E",
    "FF"
  ],
  "EMPTY": "MWXXXXXXXXXXXXXXXWXXXXXXXXXXXXXXXSXXXXXXXXXXXXXXXEXXXXXXXXXXXXXXXFFXXX",
  "FINAL_NAME": "Final Four",
  "UNPICKED_MATCH": "X",
  "TEAMS_PER_REGION": 16
}
[1, 16, 8, 9, 5, 12, 4, 13, 6, 11, 3, 14, 7, 10, 2, 15];
{
  "scoring": {
    // Each correct pick is worth one point
    "simple": 1
  }
}

or a pretty standard scoring system like:

{
  "scoring": {
    // Each correct pick is worth as many points as the value at the index of its round
    "standard": [10, 20, 40, 80, 160, 320]
  }
}

or even as complex as the gooley scoring method which I have modeled here.

Does this have X sport for Y year?

Probably not, but it's only a pull request away! All the data lives in JSON files under the ./data dir. To add a sport/year combination:

  1. Add a directory with the name of the sport (if it doesn't already exist)
  2. Add/edit a defaults.json file inside that sport's directory (if it doesn't already exist)
  3. Add a file YYYY.json inside that sport's directory

Right now the required properties are:

And the following properties are optional:

These properties are merged recursively (using lodash's merge) with the properties from defaults.json being overwritten by the properties from YYYY.json. This allows for things that don't change often (such as the order) to only be written in one place, whereas things such as teams (which change every year) to be located in the appropriate file.

Also see the above section for further explanation about these properites or go look at a complete example: defaults.json, YYYY.json.

Which sports does it have?

Currently it only has a few, but the next priority will be adding the 2014 data very quickly after it is available.

Anything else?

If this is interesting to you, I think you should follow @tweetthebracket on Twitter. There are also a lot of other bracket related modules on our GitHub organization page.

LICENSE

MIT