-
Notifications
You must be signed in to change notification settings - Fork 61
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Repo readme #682
Merged
Merged
Repo readme #682
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
bee95fc
Repo README overhaul
thcrock 6bc24a8
remove README.rst, replace with README.md
thcrock f2449c3
Add subheaders and improve copy in run section
thcrock 074e62c
Fix postmodeling link
thcrock a41a50c
Changes from review
thcrock 625ac1b
More changes
thcrock 511ad6c
Disambiguate development headers
thcrock f69d99c
Phase header changes
thcrock 1501732
Merge remote-tracking branch 'origin/master' into repo_readme
thcrock 60207bb
Update setup.py
thcrock fa6c530
Merge branch 'master' into repo_readme
shaycrk File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -15,5 +15,5 @@ docs/site/ | |
venv/ | ||
my_db_config.yaml | ||
database.yaml | ||
|
||
docs/sources/index.md | ||
dirtyduck/triage/** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,150 @@ | ||
Triage | ||
====== | ||
|
||
Risk modeling and prediction for public policy | ||
|
||
[![image](https://travis-ci.com/dssg/triage.svg?branch=master)](https://travis-ci.org/dssg/triage) | ||
[![image](https://codecov.io/gh/dssg/triage/branch/master/graph/badge.svg)](https://codecov.io/gh/dssg/triage) | ||
[![image](https://codeclimate.com/github/dssg/triage.png)](https://codeclimate.com/github/dssg/triage) | ||
|
||
Building systems that use predictive models requires answering many design decisions, turning them into modeling choices, and technical tasks. Questions such as cohort selection, unit of analysis determination, outcome determination, feature (explanantory variables) generation, model/classifier training, evaluation, selection, and list generation are often complicated and hard to choose apriori. In addition, once these choices are made, they have to be combined in different ways throughout the course of a project. | ||
|
||
Triage aims to make these decisions for binary classification problems with a strong time component by: | ||
|
||
- Guiding users (data scientists, analysts, researchers) through these design choices by highlighting operational use questions that are important. | ||
- Providing interfaces to these different phases of a project, such as an Experiment. Each phase is defined by a configuration (corresponding to a design choice) specific to the needs of the project, and an arrangement of core data science components that work together to produce the output of that phase. | ||
|
||
|
||
`Experiment` (create features and models) -> `Audition` (pick the best models) -> `Postmodeling` (dive into best models) | ||
|
||
## Quick Links | ||
|
||
- [Dirty Duck Tutorial](https://dssg.github.io/triage/dirtyduck/docs/) - Are you completely new to Triage? Go through the tutorial here. | ||
- [Triage Documentation Site](https://dssg.github.io/triage/) - Used Triage before and want more reference documentation? | ||
- [Experiment](#experiment) - Want a refresher about the Experiment and how to use it? | ||
- [Audition](#audition) - Narrow your massive modeling grid down to a few good models. | ||
- [Postmodeling](#postmodeling) - Explore your best models more comprehensively. | ||
- [Development](#development) - Contribute to Triage development. | ||
|
||
## Prerequisites | ||
|
||
To use Triage, you first need: | ||
|
||
- Python 3.6 | ||
- A PostgreSQL 9.4+ database with your source data (events, geographical data, etc) loaded. | ||
- Ample space on an available disk, (or for example in Amazon Web Services's S3), to store the needed matrices and models for your experiments | ||
- A question you want to answer. To work with Triage, you need to be able to express this question as a binary classification problem with a strong temporal component. | ||
|
||
## Install | ||
|
||
Triage is a Python package distributable via `setuptools`. It may be | ||
installed directly using `easy_install` or `pip` (`pip install triage`), or named as a | ||
dependency of another package as `triage`. | ||
|
||
|
||
## 1. Experiment: Create Features and Models | ||
|
||
> I have a bunch of data and a question I want to answer. How do I answer the question? | ||
|
||
An experiment represents the initial research work of creating design matrices from source data, and training/testing/evaluating a model grid on those matrices. At the end of the experiment, a relational database with results metadata is populated, allowing for evaluation by the researcher. The later phases (Audition and Postmodeling) rely on the output of one or many Experiments. | ||
|
||
|
||
### Design an Experiment | ||
|
||
Triage experiments require a lot of configuration. You can see some [sample configuration with explanations](https://github.com/dssg/triage/blob/master/example/config/experiment.yaml) to see what configuration looks like. But if you're new to Triage, you will be much better off [reading the Dirty Duck tutorial](https://dssg.github.io/triage/dirtyduck/docs/) as opposed to jumping into the config file. It's a guided tour through Triage functionality using a real-world problem. | ||
|
||
### Run an Experiment | ||
|
||
Once you've defined your experiment, you can run it from the command-line or from within a Python program. | ||
|
||
The Triage CLI defaults database connection information to a file stored in 'database.yaml' (example in [example_database.yaml](example_database.yaml)), so with this you can omit any mention of the database. | ||
|
||
CLI: | ||
```bash | ||
|
||
triage experiment example/config/experiment.yaml | ||
``` | ||
|
||
Python: | ||
```python | ||
from triage.experiments import SingleThreadedExperiment | ||
|
||
experiment = SingleThreadedExperiment( | ||
config=experiment_config, # a dictionary | ||
db_engine=create_engine(...), # http://docs.sqlalchemy.org/en/latest/core/engines.html | ||
project_path='/path/to/directory/to/save/data' # could be an S3 path too: 's3://mybucket/myprefix/' | ||
) | ||
experiment.run() | ||
``` | ||
|
||
There are a plethora of options available for experiment running, affecting things like parallelization, storage, and more. These options are detailed in the [Running an Experiment](https://dssg.github.io/triage/experiments/running/) page. | ||
|
||
|
||
If you're familiar with creating an Experiment but want to see more reference documentation and some deep dives, the [Triage Documentation Site](https://dssg.github.io/triage) has more content. | ||
|
||
## 2. Audition: Pick the Best Models | ||
|
||
> I just trained a bunch of models. How do I pick the best ones? | ||
|
||
Audition is a tool for picking the best trained classifiers from a predictive analytics experiment. Often, production-scale experiments will come up with thousands of trained models, and sifting through all of those results can be time-consuming even after calculating the usual basic metrics like precision and recall. Which metrics matter most? Should you prioritize the best metric value over time or treat recent data as most important? Is low metric variance important? The answers to questions like these may not be obvious up front. Audition introduces a structured, semi-automated way of filtering models based on what you consider important, with an interface that is easy to interact with from a Jupyter notebook (with plots), but is driven by configuration that can easily be scripted. | ||
|
||
To get started with Audition, check out its [README](https://github.com/dssg/triage/tree/master/src/triage/component/audition) | ||
|
||
## 3. Postmodeling: Dive Deeper into Selected Models | ||
|
||
> What is the distribution of my scores? What is generating a higher FPR in model x compared to model y? What is the single most important feature in my models?` | ||
|
||
This questions, and other ones, are the kind of inquiries that the triage user may have in mind when scrolling trough the models selected by the Audition component. Choosing the right model for deployment and exploring its predictions and behavior in time is a pivotal task. postmodeling will help to answer some of this questions by exploring the outcomes of the model, and exploring "deeply" into the model behavior across time and features. | ||
|
||
[Get started with Postmodeling](https://github.com/dssg/triage/tree/master/src/triage/component/postmodeling/contrast) | ||
|
||
|
||
## Development | ||
|
||
Triage's primary developer is [University of Chicago's Center For Data Science and Public Policy](http://dsapp.uchicago.edu). | ||
|
||
To build this package (without installation), its dependencies may | ||
alternatively be installed from the terminal using `pip`: | ||
|
||
pip install -r requirement/main.txt | ||
|
||
### Testing | ||
|
||
To add test (and development) dependencies, use **test.txt**: | ||
|
||
pip install -r requirement/test.txt [-r requirement/dev.txt] | ||
|
||
Then, to run tests: | ||
|
||
pytest | ||
|
||
### Development Environment | ||
|
||
To quickly bootstrap a development environment, having cloned the | ||
repository, invoke the executable `develop` script from your system | ||
shell: | ||
|
||
./develop | ||
|
||
A "wizard" will suggest set-up steps and optionally execute these, for | ||
example: | ||
|
||
(install) begin | ||
|
||
(pyenv) installed | ||
|
||
(python-3.6.2) installed | ||
|
||
(virtualenv) installed | ||
|
||
(activation) installed | ||
|
||
(libs) install? | ||
1) yes, install {pip install -r requirement/main.txt -r requirement/test.txt -r requirement/dev.txt} | ||
2) no, ignore | ||
#? 1 | ||
|
||
### Contributing | ||
|
||
If you'd like to contribute to Triage development, see the [CONTRIBUTING.md](CONTRIBUTING.md) document. | ||
|
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe briefly describe what an experiment is in terms of triage (and maybe why we call it that) since it's not necessarily familiar/standard terminology.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we kind of do this later, perhaps it makes sense to move 'Triage Phase Details' up before this part? Or even just stick this section into the 'Experiment' part of the aforementioned 'Triage Phase Details'?