Python Client Example

Initialize our Compute Studio API client with the Tax-Brain webapp. Before doing this, make sure to set up your authentication credentials.

You can learn more about the specific methods used in this notebook in the Python API documentation.

Save your token at ~/.cs_api_token OR pass it directly to the C/S client:

cs = cs_kit.ComputeStudio("hdoupe", "Matchups", api_token="your token")
import cs_kit
matchups = cs_kit.ComputeStudio("hdoupe", "Matchups")

Checkout the inputs documentation for Matchups using the inputs method:

inputs = matchups.inputs()
inputs
{'model_parameters': {'matchup': {'schema': {'labels': {'use_full_sample': {'number_dims': 0,
      'validators': {'choice': {'choices': [True, False]}},
      'type': 'bool'}},
    'additional_members': {'section_1': {'number_dims': 0, 'type': 'str'},
     'section_2': {'number_dims': 0, 'type': 'str'}},
    'operators': {'array_first': False,
     'label_to_extend': None,
     'uses_extend_func': False}},
   'start_date': {'title': 'Start Date',
    'description': 'Date to start pulling statcast information',
    'notes': 'If using the 2020 dataset, only use dates in 2020.',
    'type': 'date',
    'number_dims': 0,
    'value': [{'use_full_sample': True, 'value': '2009-01-01'}],
    'validators': {'date_range': {'max': 'end_date', 'min': '2009-01-01'}},
    'section_1': 'Date',
    'section_2': ''},
   'end_date': {'title': 'End Date',
    'description': 'Date to quit pulling statcast information',
    'notes': 'If using the 2020 dataset, only use dates in 2020.',
    'type': 'date',
    'number_dims': 0,
    'value': [{'use_full_sample': True, 'value': '2020-11-10'}],
    'validators': {'date_range': {'max': '2020-11-10', 'min': '2009-01-01'}},
    'section_1': 'Date',
    'section_2': ''},
   'pitcher': {'title': 'Pitcher Name',
    'description': 'Name of pitcher to pull data on',
    'notes': 'Make sure the name of the pitcher is correct. A good place to reference this is baseball-reference.com',
    'type': 'str',
    'number_dims': 0,
    'value': [{'use_full_sample': True, 'value': 'Max Scherzer'}],
    'validators': {},
    'section_1': 'Parameters',
    'section_2': 'Pitcher'},
   'batter': {'title': 'Batter Name',
    'description': 'Name of batter for pitching matchup analysis',
    'notes': 'Make sure the name of the batter is correct. A good place to reference this is baseball-reference.com',
    'type': 'str',
    'number_dims': 1,
    'value': [{'use_full_sample': True, 'value': ['Freddie Freeman']}],
    'validators': {},
    'section_1': 'Parameters',
    'section_2': 'Batter'}}},
 'meta_parameters': {'schema': {'labels': {},
   'additional_members': {},
   'operators': {'uses_extend_func': False,
    'array_first': True,
    'label_to_extend': None}},
  'use_full_sample': {'title': 'Use Full Data',
   'description': 'Flag that determines whether Matchups uses the 10 year data set or the 2020 data set.',
   'type': 'bool',
   'number_dims': 0,
   'value': [{'value': True}],
   'validators': {'choice': {'choices': [True, False]}}}}}

Create a new “simulation” to look at what pitches Walker Buehler, a pitcher for the Los Angeles Dodgers, threw to Freddie Freeman and Ronald Acuna, my favorite players on the Atlanta Braves, in the 2020 NLCS.

response = matchups.create(
    adjustment={
        "matchup": {
            "pitcher": [{"value": "Walker Buehler"}],
            "batter": [{"value": ["Freddie Freeman", "Ronald Acuna"]}],
            "start_date": [{"value": "2020-10-12"}],
            "end_date": [{"value": "2020-10-18"}]
        }
    }
)
response
{'api_url': '/hdoupe/Matchups/api/v1/94/',
 'authors': ['hdoupe'],
 'creation_date': '2021-02-08T15:01:37.569658Z',
 'eta': 24.951767,
 'exp_comp_datetime': '2021-02-08T15:02:02.569658Z',
 'gui_url': '/hdoupe/Matchups/94/',
 'is_public': True,
 'model_pk': 94,
 'model_version': None,
 'notify_on_completion': False,
 'original_eta': 25.0,
 'outputs': None,
 'owner': 'hdoupe',
 'outputs_version': None,
 'project': {'app_location': None,
  'title': 'Matchups',
  'oneliner': 'Analyze pitcher-batter matchups over the last 10 years',
  'description': "[Matchups](https://github.com/hdoupe/Matchups) provides pitch data on pitcher and batter matchups.. Select a date range using the format YYYY-MM-DD. Keep in mind that Matchups only provides data on matchups going back to 2008. Two datasets are offered to run this model: one that only has the most recent season, 2018, and one that contains data on every single pitch going back to 2008. Next, select your favorite pitcher and some batters who he's faced in the past. Click submit to start analyzing the selected matchups!",
  'repo_url': 'https://github.com/hdoupe/Matchups',
  'repo_tag': 'master',
  'latest_tag': 'f0af41930298fa9950cef51b736b704b40bd31e8',
  'exp_task_time': 25,
  'server_cost': 0.06116,
  'cpu': '2.0',
  'memory': '6.0',
  'listed': True,
  'owner': 'hdoupe',
  'cluster_type': 'single-core',
  'sim_count': 94,
  'status': 'running',
  'user_count': 11,
  'callable_name': None,
  'tech': 'python-paramtools',
  'is_public': True,
  'has_write_access': True},
 'readme': None,
 'run_time': 0,
 'status': 'PENDING',
 'title': 'Untitled Simulation',
 'traceback': None,
 'parent_sims': [],
 'role': 'admin',
 'pending_permissions': [],
 'access': [{'is_owner': True, 'role': 'admin', 'username': 'hdoupe'}]}

The new simulation is now available at the following URL:

f"https://compute.studio{response['gui_url']}"
'https://compute.studio/hdoupe/Matchups/94/'

Use the API to update the simulation title and get a notification once the simulation is complete:

matchups.update(
    model_pk=response["model_pk"],
    title="Walker Beuhler vs My Favorite Braves Players in 2020 NLCS",
    notify_on_completion=True,
    is_public=True,
)
{'api_url': '/hdoupe/Matchups/api/v1/94/',
 'authors': ['hdoupe'],
 'creation_date': '2021-02-08T15:01:37.569658Z',
 'gui_url': '/hdoupe/Matchups/94/',
 'is_public': True,
 'model_pk': 94,
 'model_version': None,
 'notify_on_completion': True,
 'owner': 'hdoupe',
 'project': 'hdoupe/Matchups',
 'readme': None,
 'status': 'PENDING',
 'title': 'Walker Beuhler vs My Favorite Braves Players in 2020 NLCS',
 'role': 'admin'}

Download the results as a pandas dataframe and analyze them locally:

results = matchups.results(response["model_pk"], timeout=60)
results["Walker Buehler v. Freddie Freeman"].describe()
Unnamed: 0 release_speed launch_speed woba_value balls strikes outs_when_up at_bat_number plate_x plate_z
count 22.000000 22.00000 5.000000 6.000000 22.000000 22.000000 22.000000 22.000000 22.000000 22.000000
mean 4134.954545 93.95000 94.740000 0.600000 0.772727 0.954545 1.045455 16.818182 0.274545 2.088636
std 1735.733288 4.81137 18.349469 0.792465 0.922307 0.785419 0.213201 12.674069 1.060803 1.349029
min 2191.000000 82.10000 63.500000 0.000000 0.000000 0.000000 1.000000 2.000000 -2.500000 -1.330000
25% 2275.000000 91.77500 96.800000 0.000000 0.000000 0.000000 1.000000 2.000000 -0.187500 1.622500
50% 5595.500000 95.80000 99.100000 0.350000 0.500000 1.000000 1.000000 21.000000 0.340000 2.025000
75% 5665.750000 97.30000 102.700000 0.850000 1.000000 1.750000 1.000000 23.000000 0.727500 2.655000
max 5754.000000 99.00000 111.600000 2.000000 3.000000 2.000000 2.000000 41.000000 2.100000 5.880000
results["Walker Buehler v. Ronald Acuna"].describe()
Unnamed: 0 release_speed launch_speed woba_value balls strikes outs_when_up at_bat_number plate_x plate_z
count 19.000000 19.000000 5.000000 6.0 19.000000 19.000000 19.000000 19.000000 19.000000 19.000000
mean 4396.210526 93.405263 90.660000 0.0 0.578947 0.947368 0.105263 24.157895 0.017895 2.390526
std 1676.366062 4.815654 7.960088 0.0 0.837708 0.848115 0.315302 12.729071 0.712753 0.896763
min 2192.000000 80.900000 80.100000 0.0 0.000000 0.000000 0.000000 1.000000 -0.710000 0.960000
25% 2295.500000 89.050000 86.900000 0.0 0.000000 0.000000 0.000000 20.000000 -0.495000 1.800000
50% 5599.000000 95.700000 89.900000 0.0 0.000000 1.000000 0.000000 22.000000 -0.370000 2.340000
75% 5668.500000 96.450000 95.600000 0.0 1.000000 2.000000 0.000000 35.000000 0.470000 2.665000
max 5755.000000 98.000000 100.800000 0.0 3.000000 2.000000 1.000000 40.000000 1.460000 5.020000

Get simulation details:

matchups.detail(response["model_pk"])
{'api_url': '/hdoupe/Matchups/api/v1/94/',
 'authors': ['hdoupe'],
 'creation_date': '2021-02-08T15:01:37.569658Z',
 'eta': 0.0,
 'exp_comp_datetime': '2021-02-08T15:02:02.569658Z',
 'gui_url': '/hdoupe/Matchups/94/',
 'is_public': True,
 'model_pk': 94,
 'model_version': '2021',
 'notify_on_completion': True,
 'original_eta': 25.0,
 'outputs': {'outputs': {'renderable': {'outputs': [{'id': 'fe088e7c-3ca1-481e-b962-0175010fb3bf',
      'title': 'Walker Buehler v. All batters',
      'filename': 'Walker Buehler v. All batters.json',
      'media_type': 'bokeh',
      'screenshot': 'https://compute.studio/storage/screenshots/fe088e7c-3ca1-481e-b962-0175010fb3bf.png'},
     {'id': '3a3f47b6-18ac-40e9-80a3-8dd5027b2a7a',
      'title': 'Walker Buehler v. Freddie Freeman',
      'filename': 'Walker Buehler v. Freddie Freeman.json',
      'media_type': 'bokeh',
      'screenshot': 'https://compute.studio/storage/screenshots/3a3f47b6-18ac-40e9-80a3-8dd5027b2a7a.png'},
     {'id': '5cf9599b-30a6-4685-a0c4-6f51e182eee3',
      'title': 'Walker Buehler v. Ronald Acuna',
      'filename': 'Walker Buehler v. Ronald Acuna.json',
      'media_type': 'bokeh',
      'screenshot': 'https://compute.studio/storage/screenshots/5cf9599b-30a6-4685-a0c4-6f51e182eee3.png'}],
    'ziplocation': '0a10c8de-2b55-456c-80bf-bc42e86f1ef4_renderable.zip'},
   'downloadable': {'outputs': [{'id': '87b40820-4e08-4392-89e3-61693044733c',
      'title': 'Walker Buehler v. All batters',
      'filename': 'Walker Buehler v. All batters.csv',
      'media_type': 'CSV'},
     {'id': '65d56ff8-c33c-4730-97b1-b63fa8b38949',
      'title': 'Walker Buehler v. Freddie Freeman',
      'filename': 'Walker Buehler v. Freddie Freeman.csv',
      'media_type': 'CSV'},
     {'id': '5a7c118d-6174-4df3-8690-b0697399a327',
      'title': 'Walker Buehler v. Ronald Acuna',
      'filename': 'Walker Buehler v. Ronald Acuna.csv',
      'media_type': 'CSV'}],
    'ziplocation': '0a10c8de-2b55-456c-80bf-bc42e86f1ef4_downloadable.zip'}},
  'version': 'v1'},
 'owner': 'hdoupe',
 'outputs_version': 'v1',
 'project': {'app_location': None,
  'title': 'Matchups',
  'oneliner': 'Analyze pitcher-batter matchups over the last 10 years',
  'description': "[Matchups](https://github.com/hdoupe/Matchups) provides pitch data on pitcher and batter matchups.. Select a date range using the format YYYY-MM-DD. Keep in mind that Matchups only provides data on matchups going back to 2008. Two datasets are offered to run this model: one that only has the most recent season, 2018, and one that contains data on every single pitch going back to 2008. Next, select your favorite pitcher and some batters who he's faced in the past. Click submit to start analyzing the selected matchups!",
  'repo_url': 'https://github.com/hdoupe/Matchups',
  'repo_tag': 'master',
  'latest_tag': 'f0af41930298fa9950cef51b736b704b40bd31e8',
  'exp_task_time': 25,
  'server_cost': 0.06116,
  'cpu': '2.0',
  'memory': '6.0',
  'listed': True,
  'owner': 'hdoupe',
  'cluster_type': 'single-core',
  'sim_count': 94,
  'status': 'running',
  'user_count': 11,
  'callable_name': None,
  'tech': 'python-paramtools',
  'is_public': True,
  'has_write_access': True},
 'readme': None,
 'run_time': 29,
 'status': 'SUCCESS',
 'title': 'Walker Beuhler vs My Favorite Braves Players in 2020 NLCS',
 'traceback': None,
 'parent_sims': [],
 'role': 'admin',
 'pending_permissions': [],
 'access': [{'is_owner': True, 'role': 'admin', 'username': 'hdoupe'}]}