Convert `matching` to a reusable action

[iaindillingham]

To be a reusable action, matching must:

• [ ] have README.md in the root directory
• [ ] have action.yaml in the root directory
• [ ] have an entrypoint script that's referenced by action.yaml*
• [ ] have a main branch
• [ ] have one or more tags that signify releases
• [ ] not have dependencies that are not in python-docker, r-docker, or stata-docker
• [ ] not have Dockerfile or other Docker-related sidecars
• [ ] be a member of the opensafely-actions organization
• [ ] be hosted on https://actions.opensafely.org/ (actions-registry)

For more information, see https://docs.opensafely.org/actions-reusable/.

*For Python reusable actions, the package isn't installed into the virtualenv, meaning that it should either use relative imports or have an entrypoint module rather than an entrypoint script. For example, replace this entrypoint script:

run: python:latest python action/__main__.py

With this entrypoint module:

run: python:latest python -m action.__main__

Entrypoint script/module

Essentially, the entrypoint will pass arguments to osmatching.match through project.yaml. However, we could rename several arguments to improve understanding. We could also decouple the matching reusable action's API from the current implementation of osmatching.match by, for example, not mentioning that the files containing the cases and the potential controls should be CSVs; this would allow us to more easily accept other file types in the future.

An entry in project.yaml that calls the matching reusable action would look something like this:

matching:
  run: matching:v1.0 --cases output/input_cases.csv --potential-controls output/input_potential_controls.csv --controls-per-case 1 --match-on '{"age": 1, "sex": "category", "stp_code": "category"}' --case-index-date case_index_date --config '{"replace_match_index_date_with_case": "no_offset"}'
  needs: [generate_cases, generate_potential_controls]
  outputs:
    moderately_sensitive: 
      matching_report: output/matching_report.txt  
    highly_sensitive: 
      matched_matches: output/matched_matches.csv

For a discussion of how the matching reusable action can be used in a case-control study, see: https://github.com/opensafely-core/cohort-extractor/issues/585#issuecomment-941103805.

[iaindillingham]

~What makes an action an action? Current thinking is here: https://github.com/opensafely-core/action-packager/issues/1#issuecomment-874200067. ⚠️ Don't pick up this issue until current thinking has settled down.~

[iaindillingham]

~This is what makes an action an action: opensafely-core/actions-registry#7~