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.

Sign up for GitHub

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

Document requesting no noise with a sentinel value #186

Merged
merged 2 commits into from
Jun 8, 2023
Merged

Document requesting no noise with a sentinel value #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3d8406b
Document requesting no noise with a sentinel value
zmbc May 23, 2023
49e9962
Merge branch 'develop' into docs/no-noise-sentinel
zmbc Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/api_reference/noising/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ All of the dataset generation functions have the same (optional) parameters.
Notable parameters include:

- a `source` path to the root directory of pseudopeople input data (defaults to using the sample dataset included with pseudopeople).
- a `config` path to a YAML file or a Python dictionary to :ref:`override the default configuration <configuration_main>`.
- a `config` path to a YAML file, a Python dictionary, or the special value :code:`pseudopeople.NO_NOISE`, to :ref:`override the default configuration <configuration_main>`.
- a `year` (defaults to 2020).

For applied examples of using these functions, see the :ref:`Quickstart <quickstart>` and :ref:`tutorials <tutorial_main>`.
Expand Down
6 changes: 5 additions & 1 deletion docs/source/configuration/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ Due to this fine-grained control, there are a very large number of settings.
**It is not necessary to configure everything.**
pseudopeople includes reasonable default noise settings
and your configuration can override as few or as many of the default values as you like.
You can also pass the special value :code:`pseudopeople.NO_NOISE`, which prevents all configurable noise types
from occurring at all.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious what alternatives were considered for the interface, e.g., an option boolean skip_noising or something like that.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we directly considered that; it's not a bad idea but it does add an extra "degree of freedom" i.e. someone could set the boolean to False but pass a configuration that specifies no noise, or vice versa.

The other reason I like this API is that in the future, pseudopeople.NO_NOISE could change from being a sentinel value to actually being the full configuration for no noise, and it would be backwards-compatible.

To learn more about the default settings, see :ref:`Noise Type Details <noise_type_details>`.
You can access the defaults from your Python code by calling the :func:`pseudopeople.get_config` function.

Expand Down Expand Up @@ -87,7 +90,8 @@ How to pass configuration to pseudopeople

Each of pseudopeople's :ref:`dataset generation functions <dataset_generation_functions>` takes a :code:`config`
argument.
This argument can be passed either a Python dictionary or the path to a YAML file.
This argument can be passed either a Python dictionary, the path to a YAML file, or the special value
:code:`pseudopeople.NO_NOISE`, which prevents all configurable noise types from occurring at all.

Configurable parameters
-----------------------
Expand Down