Update v2 docs with new changes #132

klwetstone · 2021-10-14T20:21:14Z

closes https://github.com/drivendataorg/zamba-algorithms/issues/500
closes https://github.com/drivendataorg/zamba-algorithms/issues/8

Updates docs with new changes.

Bonus updates

Incoporates changes in PR Clarify caching #131

zamba/models/model_manager.py

Fixes bug in predict_model, previously had ModelConfig(train_config=predict_config, ...)

zamba/models/config.py

Updates the docstring for num_workers since the default is now 3 instead of one less than the number of CPUs in the system

github-actions · 2021-10-14T20:24:30Z

🚀 Deployed on https://deploy-preview-132--silly-keller-664934.netlify.app

klwetstone · 2021-10-14T20:50:59Z

@ejm714 doc updates ready for review!

ejm714 · 2021-10-14T22:35:26Z

@klwetstone can you fix the failing tests?

also just a heads up that there are more changes in https://github.com/drivendataorg/zamba/pull/131/files that need to be incorporated. check out the PR description and the issues for a description of what changed

codecov · 2021-10-15T13:03:42Z

Codecov Report

❗ No coverage uploaded for pull request base (v2@97ba34e). Click here to learn what that means.
The diff coverage is n/a.

❗ Current head 52b1cf2 differs from pull request most recent head a81fa39. Consider uploading reports for the commit a81fa39 to get more accurate results

@@         Coverage Diff          @@
##             v2    #132   +/-   ##
====================================
  Coverage      ?   87.3%           
====================================
  Files         ?      25           
  Lines         ?    1479           
  Branches      ?       0           
====================================
  Hits          ?    1292           
  Misses        ?     187           
  Partials      ?       0

klwetstone · 2021-10-15T13:38:29Z

@ejm714 updated! some of the pytests are failing, but I don't think it's from something in this PR. Let me know if you want me to dive deeper!

ejm714

Looking good -- can you rebase this on v2 instead of the final models dir? this is capturing all of those changes in this PR whereas we just want the docs pieces

docs/docs/configurations.md

docs/docs/extra-options.md

docs/docs/predict-tutorial.md

docs/docs/python-tutorial.ipynb

docs/docs/quickstart.md

docs/docs/train-tutorial.md

klwetstone · 2021-10-19T15:16:42Z

Almost ready - I rebased onto v2, but it didn't get rid of the commits from rebasing onto 492 (to get the updated docstrings) so I'm doing it manually

ejm714 · 2021-10-19T16:39:48Z

FYI I also changed the navigation TOC to be expanded instead of bold section headers.

Pretty sure the bold section headers was an intentional change by @jayqi. Details here: #129. I see rationale for both sides -- can you two strike a balance?

klwetstone · 2021-10-19T17:43:35Z

Pretty sure the bold section headers was an intentional change by @jayqi. Details here: #129. I see rationale for both sides -- can you two strike a balance?

Ah I see that change now. We could either find a way to make section headers bold when they have no sub-pages, or limit the depth of the TOC that's display automatically when navigation is expanded. I have no preference, I'll start looking into which might be easier

klwetstone · 2021-10-19T17:59:29Z

Two options that are easy to implement:

Move API reference to the end and keep sections expanded. This will still show the long menu, but won't be in the way
Use expand rather than bolded section headers, but don't have any expanded automatically - users will have to click the down arrow to see the subsections.

I find 2 makes it a little harder to navigate, so I'd lean towards 1. Unfortunately I'm not seeing a way yet we can get "Available Models" to be bolded as a section header, or a way to limit automatic TOC expansion depth. @ejm714 @jayqi

jayqi · 2021-10-19T18:01:30Z

@klwetstone I think maybe you can try turning "Available Models" into a pseudo-section and attaching a page to it with this setting: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages

klwetstone · 2021-10-19T18:14:13Z

@klwetstone I think maybe you can try turning "Available Models" into a pseudo-section and attaching a page to it with this setting: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages

I played around with that, but the navigation.sections has never actually worked for me. I get:

Where only the second "available models" is clickable. Did it work for you?

docs/docs/train-tutorial.md

rephrase train data size rec Co-authored-by: Emily Miller <ejm714@gmail.com>

jayqi · 2021-10-19T19:47:52Z

Something actually seems wrong with navigation.indexes. I can't get it to work with either sections or menus. I'll poke around this a little more.

Anyways, in theory, it seems like navigation.indexes + navigation.sections should be explicitly supported now. squidfunk/mkdocs-material#3070

klwetstone · 2021-10-19T20:11:41Z

Hmm I just upgraded to mkdocs-material 7.3.2, where the bug should theoretically be fixed, and I'm still getting the same issues.

What do you think of just moving the API reference section to the bottom and having all tabs expanded? Another option is to combine some of the API reference pages. For example, have zamba.data.metadata and zamba.data.video in one markdown file under zamba.data with two headers.

…ndex Enable nav index page for models

klwetstone · 2021-10-19T20:35:50Z

@ejm714 TOC navigation formatting is resolved, ready for review again!

docs/docs/models/index.md

* delete v1 * remove hidden files * Zamba v1 docs port (#108) * workflow tests * remove tests workflow from v2 * Great migration (#113) * copy everything * first round of deletion * more deletions * more deletions * put everything under zamba * remove old readme * replace zamba_algorithms with zamba * integrate makefile * changed files * updates from save dir overwrite * add gitignore * use gitignore from zamba algo * remove load metadata * remove old dirs * lint * remove load metadata * remove load_metadata test * fix datamodule tests * simplify time dist model since there is only one * flake8 * remove unused file * put back lost code * back to long name because that is was model is registered as * species is no longer on model * use models without species prefix and zamba backbone finetune params; * rename time dist head since there is only one * further remove species * use lstrip instead * passing tests * add missing underscore * update links to setup.cfg * specify branches in workflow * update setup.cfg * Update setup.cfg Co-authored-by: Peter Bull <pjbull@gmail.com> * Update setup.cfg Co-authored-by: Peter Bull <pjbull@gmail.com> Co-authored-by: Peter Bull <pjbull@gmail.com> * bug fix (#114) * Skip on failure, actually drop duplicates, clarify logging (#115) * skip on failure, actually drop duplicates, clarify logging * correct comment * only apply to root validators * First draft of zamba v2 docs (#112) * Update zamba predict in cli doc * Update zamba train in cli doc * Formatting * Start updating index * Update ungulate pic * update to chimp image * specify image sizes * update image sizes * add labels to images * Format * add labels to frames * note about top div * start updating inputs_outputs * tweaks to index * Use new vids in index * use full size images * remove some todo notes * comments to cli md * comments to cli md * comments to cli md * Add comments to index * Comments to inputs_outputs * Incorporate preliminary comments * Start working on install * Start working on algorithms * Start reorganizing * Redo quickstart to have a python section * Add basics of slowfast * Use better compressed images * Try and view with new TOC * Add more model info * Start configuration documentation * Add all configurations * Update TOC with configurations doc page * Add where output is saved * Add placeholders for user tutorials * v2 updates * Add info about yolox * Send us labeled videos * Make available models top level * TODO about model details * Better explanation of YAML v CLI args * Copy edits and formatting * Update install page * Add basic use to available models * Update mkdocs.yml * Start working on python package page * Make TOC work correctly * Add explanation of more of the parameter options * Start user tutorials * Update based on new default help text * Copy editing * Add where to reference for python package * Remove repetitive parameter explanation from cli.md * Update TOC names * Update tutorial names * Add python package and training to quickstart * copy edits * Status before big reorganization * Restructure * Write predict tutorial * Other updates for restructuring * YAML configs page * Update homepage index * Save path for CSV * Update tutorials * Update default video loading configs * Record of extra code, then will delete * Remove extra md files * Save path updates * delete more extra files * copy edits * Update args * TODO updates * New default save path * Update megadetector explanation * Better ffmpeg installation instructions * Fix checkpoint saving behavior * Typos * Add troubleshooting sections and format python code blocks better * Add video loading requirements to yaml-config.md * Improve default model descriptions * Begin incorporating feedback * consistent FFmpeg capitalization * index testing * index testing * More feedback * Add debugging page * yaml feedback * Seprate common advanced options page * beautiful magic tabs and more copy editing * Tabs on model page * Support training models with just two classes (#117) * two class metric updates * Update tests/conftest.py Co-authored-by: Emily Miller <ejm714@gmail.com> Co-authored-by: Emily Miller <ejm714@gmail.com> * 32 not 31 species (#118) * Add erdantic diagram (#121) * add erdantic diagram * add missing docs reqs * unpin * Write out splits + fix for videos that cannot be loaded (#119) * write out splits * write out zeros for videos that cannot be loaded * create missing save dir * typo * Add OSes and codecov to github actions (#124) * add oses and codecov * try w/o windows * msvc config * test with env var * Give up on Windows for now * [V2] Clean up dev dependencies (#125) * Remove unneeded dev dependencies * Split out docs and lint deps for faster installation Co-authored-by: Jay Qi <jayqi@users.noreply.github.com> * [V2] Release and docs CI (#126) * Add make command to build distributions * Add --version command * Add README * Test built distributions; add failed build notify * Reorder config to keep build metadata together at the top * Rename docs-publish to docs-master * Rename docs-master to docs-latest * Add maintainers docs * Add release workflow * Add mike for versioned docs * Run docs-latest on push to v2 * Remove code tags in nav * Add __main__ for python -m entrypoint Co-authored-by: Jay Qi <jayqi@users.noreply.github.com> * Get default video loader config for models (#127) * get default video loader for model * get default vlc if not specified * set save dir to tmp path so splits.csv is written to temp dir * keep vlc in so we can use for training * add evenly sample * use loguru * set num workers to 3 * remove cpu count * revert change * show ffmpeg error in debug mode * add link to wiki * Rename README.md to MAINTAINING.md (#128) * API Reference with mkdocstrings (#129) * Remove upload_models.py script * Add API Reference with mkdocstrings * Minor documentation tweaks to fix rendering * Use sections instead of auto-expand * Need to install zamba to use mkdocstrings * Put back upload_models.py * Wrap upload_models in if __name__ = '__main__' Co-authored-by: Jay Qi <jayqi@users.noreply.github.com> * Resized test assets (#130) * add resized test assets * resampled to fps=1 * update labels per new videos * update with new video * fix failed test * start python tutorial * Update v2 docs with new changes (#132) * clarify labels filepath columns * start updating video loader config list * update configs * Update video organization reqs * video_width/height and num_workers * filepaths * default num_workers * update num_workers in CLI * writing out train_config and predict_config yamls * splits.csv * updates based on netlify preview * add screencast video demo * fix linting fail * updates for caching PR 131 * typo * use best terminal video from asciinema * specific explanation of frame_selection_height * correct default batch size * add frame_selection_width v model_input_width * talk about num_workers more * flake8 fix * PR feedback * update home page language * fix typo and change from sections to expand * reduce toc depth to 2 to allow expand * use megadetectorlite consistently * move api reference to end * add train data size recs * Update docs/docs/train-tutorial.md rephrase train data size rec Co-authored-by: Emily Miller <ejm714@gmail.com> * Enable nav index page for models * make contribute section header * Edit MDLite language * put yolox back in Co-authored-by: Emily Miller <ejm714@gmail.com> Co-authored-by: Jay Qi <jayqi@users.noreply.github.com> * Expose final three models (#133) * add official models dir * remove tf events * move to outside template folder * simplify model mapping; set batch size default to 2 * move official models into zamba * add vlc for slowfast * update manifest for official models * update filename * update filepath * must import models for them to be in available_models * remove config details used for training so these can be the baseline * update config * add backbone finetune config that was used in case defaults change * update labels for time dist; remove slowfast until it is retrained * update per new model * formatting * helper command * already path * Clarify caching (#131) * set ability to turn off caching for prediction * reomve cache dir from cli * test cache dir is set but not used * rename to MODEL_CACHE_DIR for consistency * rename cache_dir to model_cache_dir * move video cache dir into configs * remove unneeded code as caching is off by default * rename to video_cache_dir for clarity * remove * do not support setting in configs * put back in settings * lint and such * rebase fix * put cache_dir and cleanup option on video laoder config * add tests for caching * get empty vlc if none is passed * put within func to avoid writing to real path * add logging * bug fix * reomve old change * loguru uses warning not warn * load dotenv in init * setup logger in init and rename to log_level for simplicity * cleanup does not change hash * fix test * lint * add regression test * do not use load_dotenv * Fix transform look up bug (#135) * separate out weight lookup from class based dict * fix lookup * set split propotions to none if using split in labels * tense * shorten * fix failing test * add updated slowfast model * add test for specifying checkpoint * address deprectation warnings * update templates to reflect final models * fix imports * lint * fix make docs-serve * Update link to models and contribute pages * update erdantic schema * Update references to other pages * Add links to final github source code to docs (#141) * add working links with v2 branch * use master branch instead of v2 * refer to api docs instead of github * Automated workflow for publishing models (#140) * WIP * update weight lookup and hash config to get model name * use auto workflow * auto workflow * add logging * rename to publish models * auto workflow * add code for handling finetuned models * add docs for adding a new model * checklist * update model name * put models in official models dir on s3 * add lookup function * auto workflow * use model dir which is clearer than ckpt * update docs * new slowfast model * rglob needs list * update euro config * only hash once and have function do a lookup * make this not model specific * clarify comments * remove checkpoint from train_config * docs * function to get only model params * use function to subset train config * update yamls based on exclude rather than include * only set checkpoint if not from_scratch, otherwise look up hparams * missing import * lint * checkpoint will now be none for training fromm scratch * remove space * docs-latest needs zamba (#143) * Add densepose model (#142) * Add densepose model * Update densepose install and testing * format * remove errant test yml * more generic codec * append coverage * Update README for v2 (#134) * screencast video demo * video not showing * video show method * autoplay vid * vid * updated terminal video * test video embedding * terminal video * Embed video in README * start updating text * full draft of text * delete vid and update text * editing based on page rendering * rephrase * make same as index.md * update monkey video * edit README * improve formatting * add make docs-setup * delete index.md raw page * hybrid README * update * updates * correct contribute link * add changelog from HISTORY.md * create changelog folder placeholder * delete old changelog md * Simplify caching (#145) * simplify caching * nest function * simplify * move * alphabetize * lint * rename to cache path * fix dataset * Change default backbone finetuning, auto_lr_find, and fix persistent workers bug (#148) * Default patience from 3 to 5 * Default for auto_lr_find to False * Change default unfreeze_backbone_at_epoch to 5 * Fix persistent_workers bug * Revert changes to templates * 496 docs review (#150) * add denspose and update save dir * commit two autogenerated files * changelog edits * contribute edits * WIP edits for models * finish edits for models and separate out densepose * full list of parks * config options * vscode format * move config guide into tutorials * extra options * windows not tested * tutorial edits * remove extra nb * put save path back * quickstart edits * vscode formatting * finish quickstart edits * train tutorial * add template section * logging * ffpmeg install in readme * finetuning * capitalization * remove ffmpmeg * date * add densepose * tweak * simplify * fix densepose video link * caps and tensorboard * add help * remove pythong piece since this is focused on yaml files * more tweaks * edit history not change log * copy edits * fix changelog * table * table * typo * alphabetize * table bug * table edits * Simplify save_dir and some directory -> dir renames (#151) * wip renames * renames in docs * readme * data dir renamme in docs * rename in code from data_directory to data_dir * maintaining update * fix capitalization * further updates * tweak * do not overwrite * add overwrite save dir * add overwrite save dir to config * update configs with all info * use full train configuration * only upload if does not exist * tests for save * overwrite param * better set up and test for overwrite * docs * update docs with overwrite * from overwrite_save_dir to overwrite * missed rename * remove machine specific from vlc * unindent so test actually runs * check for local and cached checkpoints * should be and * write out predict config before preds start like we do for train config * update all configs and use only first 10 digits of hash * dry run check after save is configured; more robust test * reorder * show save directory * copy edits * update template * fix test * lower case for consistency * fix test * Fix docs links (#155) * update readme links * update makefile Co-authored-by: Emily Miller <ejm714@gmail.com> Co-authored-by: ejm714 <emily@drivendata.org> Co-authored-by: Katie Wetstone <46792169+klwetstone@users.noreply.github.com> Co-authored-by: Jay Qi <2721979+jayqi@users.noreply.github.com> Co-authored-by: Jay Qi <jayqi@users.noreply.github.com> Co-authored-by: Katie Wetstone <klwetstone@gmail.com> Co-authored-by: Robert Gibboni <robert@drivendata.org>

klwetstone marked this pull request as draft October 14, 2021 20:40

klwetstone marked this pull request as ready for review October 14, 2021 20:50

klwetstone requested a review from ejm714 October 14, 2021 20:50

klwetstone force-pushed the 500-doc-updates branch 2 times, most recently from 47f8c26 to 55741b7 Compare October 18, 2021 20:50

ejm714 requested changes Oct 18, 2021

View reviewed changes

klwetstone force-pushed the 500-doc-updates branch from 7f568f7 to 8cbcc7e Compare October 19, 2021 14:14

klwetstone added 17 commits October 19, 2021 11:19

clarify labels filepath columns

57472e0

start updating video loader config list

b9ab825

update configs

5141f47

Update video organization reqs

860f4d6

video_width/height and num_workers

a3dc816

filepaths

2400fbf

default num_workers

14f99b9

update num_workers in CLI

c2b49a1

writing out train_config and predict_config yamls

4ad727c

splits.csv

cfe7d8a

updates based on netlify preview

16d38c4

add screencast video demo

502f642

fix linting fail

f5da007

updates for caching PR 131

581ee25

typo

7aa9ee4

use best terminal video from asciinema

ffd6243

specific explanation of frame_selection_height

8d45102

klwetstone added 3 commits October 19, 2021 11:30

update home page language

5dc1fa4

fix typo and change from sections to expand

3c95d89

reduce toc depth to 2 to allow expand

50779df

use megadetectorlite consistently

c3900c2

move api reference to end

ded14b2

add train data size recs

666c8ad

ejm714 reviewed Oct 19, 2021

View reviewed changes

docs/docs/train-tutorial.md Outdated Show resolved Hide resolved

Update docs/docs/train-tutorial.md

d0b518c

rephrase train data size rec Co-authored-by: Emily Miller <ejm714@gmail.com>

Enable nav index page for models

c115932

jayqi mentioned this pull request Oct 19, 2021

Enable nav index page for models #136

Merged

klwetstone and others added 2 commits October 19, 2021 16:27

Merge pull request #136 from drivendataorg/500-docs-updates-section-i…

e0cf326

…ndex Enable nav index page for models

make contribute section header

4abaab4

ejm714 reviewed Oct 19, 2021

View reviewed changes

docs/docs/models/index.md Outdated Show resolved Hide resolved

Edit MDLite language

97b9729

ejm714 reviewed Oct 19, 2021

View reviewed changes

docs/docs/models/index.md Outdated Show resolved Hide resolved

put yolox back in

a81fa39

ejm714 self-requested a review October 19, 2021 20:47

ejm714 approved these changes Oct 19, 2021

View reviewed changes

ejm714 merged commit 97ba06a into v2 Oct 19, 2021

ejm714 deleted the 500-doc-updates branch October 19, 2021 20:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update v2 docs with new changes #132

Update v2 docs with new changes #132

klwetstone commented Oct 14, 2021 •

edited by ejm714

github-actions bot commented Oct 14, 2021 •

edited

klwetstone commented Oct 14, 2021

ejm714 commented Oct 14, 2021

codecov bot commented Oct 15, 2021 •

edited

klwetstone commented Oct 15, 2021

ejm714 left a comment

klwetstone commented Oct 19, 2021

ejm714 commented Oct 19, 2021

klwetstone commented Oct 19, 2021

klwetstone commented Oct 19, 2021

jayqi commented Oct 19, 2021

klwetstone commented Oct 19, 2021

jayqi commented Oct 19, 2021

klwetstone commented Oct 19, 2021

klwetstone commented Oct 19, 2021

Update v2 docs with new changes #132

Update v2 docs with new changes #132

Conversation

klwetstone commented Oct 14, 2021 • edited by ejm714

github-actions bot commented Oct 14, 2021 • edited

klwetstone commented Oct 14, 2021

ejm714 commented Oct 14, 2021

codecov bot commented Oct 15, 2021 • edited

Codecov Report

klwetstone commented Oct 15, 2021

ejm714 left a comment

Choose a reason for hiding this comment

klwetstone commented Oct 19, 2021

ejm714 commented Oct 19, 2021

klwetstone commented Oct 19, 2021

klwetstone commented Oct 19, 2021

jayqi commented Oct 19, 2021

klwetstone commented Oct 19, 2021

jayqi commented Oct 19, 2021

klwetstone commented Oct 19, 2021

klwetstone commented Oct 19, 2021

klwetstone commented Oct 14, 2021 •

edited by ejm714

github-actions bot commented Oct 14, 2021 •

edited

codecov bot commented Oct 15, 2021 •

edited