Skip to content
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

Add doctests / inline examples in API reference #90

Open
Luthaf opened this issue Mar 30, 2021 · 3 comments
Open

Add doctests / inline examples in API reference #90

Luthaf opened this issue Mar 30, 2021 · 3 comments
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@Luthaf
Copy link
Collaborator

Luthaf commented Mar 30, 2021

We already have some end-to-end examples/tutorials. These show how to accomplish a high level goal with this library ("how do I create a projection of my dataset using KPCovR").

It would be nice to also have "inline" examples inside the reference documentation, showing how to use each function separately ("how do I call FPS.fit with warm_start=True"). For a good example of how this would look like, see https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html#sklearn.decomposition.PCA.transform.

The standard tool to add such example in Python is called doctests: one write input code as if there was a python prompt (>>>); and the corresponding output. Then, there are tools to run the input code and check that output match. Check out the corresponding module in python standard library: https://docs.python.org/3/library/doctest.html

The first task for this issue would be to make sure doctests are part of the test suite checked on CI

We already have some classes with such examples (https://scikit-cosmo.readthedocs.io/en/latest/preprocessing.html#skcosmo.preprocessing.flexible_scaler.KernelNormalizer), but I think all classes should come with such a small example.

The second task for this issue would be to add doctests/examples to all classes in skcosmo.

@rosecers rosecers added documentation Improvements or additions to documentation good first issue Good for newcomers labels Jun 15, 2022
@Luthaf
Copy link
Collaborator Author

Luthaf commented Apr 24, 2023

Looks like we have examples for most of the functions!

@Luthaf Luthaf closed this as completed Apr 24, 2023
@Luthaf
Copy link
Collaborator Author

Luthaf commented Apr 24, 2023

Actually, I closed this a bit too fast: we have examples for most functions, but not all of them have doctests.

Here is an example of a doctest, actually checking the output of the code: https://github.com/lab-cosmo/scikit-matter/blob/45cff6a81c9136126518bb621101c53ec6e7565a/src/skmatter/decomposition/_pcovr.py#L174-L193

Here is a list of functions/classes without doctests:

  • SparseKernelCenterer
  • CUR
  • FPS
  • PCovCUR
  • PCovFPS
  • VoronoiFPS
  • DirectionalConvexHull
  • RidgeRegression2FoldCV
  • OrthogonalRegression
  • pointwise_global_reconstruction_error
  • global_reconstruction_error
  • pointwise_global_reconstruction_distortion
  • global_reconstruction_distortion
  • pointwise_local_reconstruction_error
  • local_reconstruction_error
  • skmatter.utils._pcovr_utils.pcovr_kernel
  • skmatter.utils._pcovr_utils.pcovr_covariance
  • skmatter.utils._orthogonalizers.Y_feature_orthogonalizer
  • skmatter.utils._orthogonalizers.Y_sample_orthogonalizer

@Luthaf Luthaf reopened this Apr 24, 2023
@agoscinski
Copy link
Collaborator

PR #201 moved examples to doctest for several of them, I ticket the boxes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

3 participants