Add the XGBoost ML library

[riley-harper]

This is a new IPUMS-motivated feature. We would like to integrate the XGBoost library into hlink so that you can use it like any of the other ML algorithms already available. Since XGBoost-Spark integration is currently experimental and since XGBoost has some other dependencies (libomp and pyarrow), we would like to make this an opt-in feature so that you don't need to have the XGBoost dependencies unless you want to use xgboost.

We intend to do this by adding a new optional-dependencies section to pyproject.toml.

[optional-dependencies]
dev = ...
xgboost = ["xgboost", "pyarrow>=4"]

Then in hlink/linking/core/classifier.py, we can try to import xgboost, but not error out if it's not available.

try:
    import xgboost
except ModuleNotFoundError:
    xgboost_available = False
else:
    xgboost_available = True

And if a user sets their model_type = "xgboost", we can confirm that the package is present and error out if it's not.

...
elif model_type == "xgboost":
    if not xgboost_available:
         raise ModuleNotFoundError("could not find xgboost, please install it")
    ...

My biggest question with this setup is how we test the feature. Do we just always install xgboost when running tests? Should we have two test environments, one with xgboost and one without?

To Do List

• Create an hlink extra which installs xgboost and its dependencies
• Integrate xgboost into core/classifier.py
• Make sure xgboost works with model_exploration
• Make sure xgboost works with training (especially step 3, save model metadata)
• Make sure xgboost works with matching
• Document the new hlink pip extra and additional requirements for xgboost (libomp). Note that xgboost-PySpark integration is still experimental, so it may not be as stable as other hlink features.
• Document the new model type in the Sphinx docs
• Make a nice, informative error message for when xgboost isn't available
• Update the tests to run once without xgboost installed and once with it installed
• Reduce the verbosity of xgboost logs so it doesn't output to stdout/stderr (can we redirect these to the Python logging system somehow?)

[riley-harper]

For the tests, maybe a good place to start is to write tests which skip themselves when xgboost isn't present. We can use pytest.mark.skip for this. Then we can make sure to install xgboost in the CI/CD tests, but the tests should still pass even if xgboost isn't available.

This doesn't really help us test the condition where xgboost is not available. This test would just make sure that we raise an exception that makes sense. I don't really want to add tests which are skipped if xgboost is available. That seems confusing and encourages fiddling with the environment back and forth as you run tests. Maybe we just won't write tests for this error case to start with.

[riley-harper]

I suppose even if we skip the tests when xgboost isn't available, we probably want to run the tests with and without xgboost to make sure that hlink runs as expected when xgboost isn't installed. Looking around on the internet, I've seen "tox" and "pytest-xdist" mentioned as tools that can help with this.

[riley-harper]

Another option is to make use of GitHub Actions matrix builds.

matrix:
        python_version: ["3.10", "3.11", "3.12"]
        include_extras: ["no", "yes"]

Edit: This might be a bit easier and more flexible:

matrix:
    python_version: ["3.10", "3.11", "3.12"]
    hlink_extras: ["dev", "dev,xgboost"]