robusta-hmf 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,169 @@
1
+ # vscode
2
+ .vscode/
3
+
4
+ # MacOS
5
+ *.DS_Store
6
+
7
+ # Byte-compiled / optimized / DLL files
8
+ __pycache__/
9
+ *.py[cod]
10
+ *$py.class
11
+
12
+ # C extensions
13
+ *.so
14
+
15
+ # Distribution / packaging
16
+ .Python
17
+ build/
18
+ develop-eggs/
19
+ dist/
20
+ downloads/
21
+ eggs/
22
+ .eggs/
23
+ lib/
24
+ lib64/
25
+ parts/
26
+ sdist/
27
+ var/
28
+ wheels/
29
+ share/python-wheels/
30
+ *.egg-info/
31
+ .installed.cfg
32
+ *.egg
33
+ src/robusta_hmf/_version.py
34
+ # MANIFEST
35
+
36
+ # PyInstaller
37
+ # Usually these files are written by a python script from a template
38
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
39
+ *.manifest
40
+ *.spec
41
+
42
+ # Installer logs
43
+ pip-log.txt
44
+ pip-delete-this-directory.txt
45
+
46
+ # Unit test / coverage reports
47
+ htmlcov/
48
+ .tox/
49
+ .nox/
50
+ .coverage
51
+ .coverage.*
52
+ .cache
53
+ nosetests.xml
54
+ coverage.xml
55
+ *.cover
56
+ *.py,cover
57
+ .hypothesis/
58
+ .pytest_cache/
59
+ cover/
60
+
61
+ # Translations
62
+ *.mo
63
+ *.pot
64
+
65
+ # Django stuff:
66
+ *.log
67
+ local_settings.py
68
+ db.sqlite3
69
+ db.sqlite3-journal
70
+
71
+ # Flask stuff:
72
+ instance/
73
+ .webassets-cache
74
+
75
+ # Scrapy stuff:
76
+ .scrapy
77
+
78
+ # Sphinx documentation
79
+ docs/_build/
80
+
81
+ # PyBuilder
82
+ .pybuilder/
83
+ target/
84
+
85
+ # Jupyter Notebook
86
+ .ipynb_checkpoints
87
+
88
+ # IPython
89
+ profile_default/
90
+ ipython_config.py
91
+
92
+ # pyenv
93
+ # For a library or package, you might want to ignore these files since the code is
94
+ # intended to run in multiple environments; otherwise, check them in:
95
+ # .python-version
96
+
97
+ # pipenv
98
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
99
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
100
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
101
+ # install all needed dependencies.
102
+ #Pipfile.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ #poetry.lock
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ #pdm.lock
114
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
115
+ # in version control.
116
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
117
+ .pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
122
+ __pypackages__/
123
+
124
+ # Celery stuff
125
+ celerybeat-schedule
126
+ celerybeat.pid
127
+
128
+ # SageMath parsed files
129
+ *.sage.py
130
+
131
+ # Environments
132
+ .env
133
+ .venv
134
+ env/
135
+ venv/
136
+ ENV/
137
+ env.bak/
138
+ venv.bak/
139
+
140
+ # Spyder project settings
141
+ .spyderproject
142
+ .spyproject
143
+
144
+ # Rope project settings
145
+ .ropeproject
146
+
147
+ # mkdocs documentation
148
+ /site
149
+
150
+ # mypy
151
+ .mypy_cache/
152
+ .dmypy.json
153
+ dmypy.json
154
+
155
+ # Pyre type checker
156
+ .pyre/
157
+
158
+ # pytype static type analyzer
159
+ .pytype/
160
+
161
+ # Cython debug symbols
162
+ cython_debug/
163
+
164
+ # PyCharm
165
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
166
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
167
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
168
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
169
+ #.idea/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Thomas Hilder
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,68 @@
1
+ Metadata-Version: 2.4
2
+ Name: robusta-hmf
3
+ Version: 0.0.1
4
+ Summary: Robust heteroskedastic matrix factorisation in JAX.
5
+ Author-email: Tom Hilder <tom.hilder.dlhp@gmail.com>, "David W. Hogg" <TODO@TODO.com>
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.13
8
+ Requires-Dist: equinox>=0.13.0
9
+ Requires-Dist: jax>=0.7.1
10
+ Requires-Dist: optax>=0.2.5
11
+ Description-Content-Type: text/markdown
12
+
13
+ # Robusta-HMF
14
+
15
+ `jax` implementation of robust heteroskedastic matrix factorisation. Robusta like the coffee bean, get it?
16
+
17
+ ## Installation
18
+
19
+ Easiest is from PyPI either with `pip` (CURRENTLY NOT ON PYPI YET)
20
+
21
+ ```sh
22
+ pip install robusta-hmf
23
+ ```
24
+
25
+ or `uv` (recommended)
26
+
27
+ ```sh
28
+ uv add robusta-hmf
29
+ ```
30
+
31
+ Or, you can clone and build from source
32
+
33
+ ```sh
34
+ git clone git@github.com:TomHilder/robusta-hmf.git
35
+ cd robusta-hmf
36
+ pip install -e .
37
+ ```
38
+
39
+ ## Usage
40
+
41
+ TODO
42
+
43
+ ## Citation
44
+
45
+ TODO
46
+
47
+ ## Help
48
+
49
+ TODO
50
+
51
+ ## TODOs
52
+
53
+ - [x] Port Hogg's existing code and make sure it builds/installs*
54
+ - [x] Port to `equinox`*
55
+ - [ ] Type checking with `mypy`*
56
+ - [x] Add dependency injection for the following:*
57
+ - [x] Optimisation method, IRLS, SGD (directly optimising objective, see robust_hmf_notes.pdf)
58
+ - [ ] Potentially `dask` and batching support for SGD
59
+ - [x] w-steps. Each w-step corresponds to a different likelihood. Hogg's is Cauchy. We should let this flexible*
60
+ - [x] Initialisation.
61
+ - [x] Re-orientation. Can easily imagine wanting something cheaper for really big data.
62
+ - [ ] Add a save and restore method. Probably avoid pickle/dill and instead encapsulate info in serialisable way and then rebuild model upon loading
63
+ - [ ] Eh maybe, maybe not
64
+ - [x] Tests!*
65
+ - [ ] CI, automated tests, automated relases, and PyPI*
66
+ - [ ] Relax version requirements since uv by default is newest everything
67
+
68
+ (*) = Priority
@@ -0,0 +1,56 @@
1
+ # Robusta-HMF
2
+
3
+ `jax` implementation of robust heteroskedastic matrix factorisation. Robusta like the coffee bean, get it?
4
+
5
+ ## Installation
6
+
7
+ Easiest is from PyPI either with `pip` (CURRENTLY NOT ON PYPI YET)
8
+
9
+ ```sh
10
+ pip install robusta-hmf
11
+ ```
12
+
13
+ or `uv` (recommended)
14
+
15
+ ```sh
16
+ uv add robusta-hmf
17
+ ```
18
+
19
+ Or, you can clone and build from source
20
+
21
+ ```sh
22
+ git clone git@github.com:TomHilder/robusta-hmf.git
23
+ cd robusta-hmf
24
+ pip install -e .
25
+ ```
26
+
27
+ ## Usage
28
+
29
+ TODO
30
+
31
+ ## Citation
32
+
33
+ TODO
34
+
35
+ ## Help
36
+
37
+ TODO
38
+
39
+ ## TODOs
40
+
41
+ - [x] Port Hogg's existing code and make sure it builds/installs*
42
+ - [x] Port to `equinox`*
43
+ - [ ] Type checking with `mypy`*
44
+ - [x] Add dependency injection for the following:*
45
+ - [x] Optimisation method, IRLS, SGD (directly optimising objective, see robust_hmf_notes.pdf)
46
+ - [ ] Potentially `dask` and batching support for SGD
47
+ - [x] w-steps. Each w-step corresponds to a different likelihood. Hogg's is Cauchy. We should let this flexible*
48
+ - [x] Initialisation.
49
+ - [x] Re-orientation. Can easily imagine wanting something cheaper for really big data.
50
+ - [ ] Add a save and restore method. Probably avoid pickle/dill and instead encapsulate info in serialisable way and then rebuild model upon loading
51
+ - [ ] Eh maybe, maybe not
52
+ - [x] Tests!*
53
+ - [ ] CI, automated tests, automated relases, and PyPI*
54
+ - [ ] Relax version requirements since uv by default is newest everything
55
+
56
+ (*) = Priority
@@ -0,0 +1,37 @@
1
+ [project]
2
+ name = "robusta-hmf"
3
+ dynamic = ["version"]
4
+ description = "Robust heteroskedastic matrix factorisation in JAX."
5
+ readme = "README.md"
6
+ authors = [
7
+ { name = "Tom Hilder", email = "tom.hilder.dlhp@gmail.com" },
8
+ { name = "David W. Hogg", email = "TODO@TODO.com" },
9
+ ]
10
+ requires-python = ">=3.13"
11
+ dependencies = ["equinox>=0.13.0", "jax>=0.7.1", "optax>=0.2.5"]
12
+
13
+ [build-system]
14
+ requires = ["hatchling", "hatch-vcs"]
15
+ build-backend = "hatchling.build"
16
+
17
+ [tool.hatch.build]
18
+ include = ["src/robusta_hmf/py.typed"]
19
+ exclude = ["**/__pycache__/**"]
20
+
21
+ [tool.hatch.build.targets.sdist]
22
+ include = ["src/**", "README.md", "LICENSE"]
23
+
24
+ [tool.hatch.build.targets.wheel]
25
+ packages = ["src/robusta_hmf"]
26
+
27
+ [tool.hatch.build.hooks.vcs]
28
+ version-file = "src/robusta_hmf/_version.py"
29
+
30
+ [tool.hatch.version]
31
+ source = "vcs"
32
+
33
+ [tool.ruff]
34
+ line-length = 99 # Sorry PEP8 I'm a rebel
35
+
36
+ [dependency-groups]
37
+ dev = ["mypy>=1.18.2", "pytest>=8.4.2", "pytest-cov>=7.0.0"]
@@ -0,0 +1,11 @@
1
+ # __init__.py
2
+
3
+ from .convergence import ConvergenceTester
4
+ from .initialisation import Initialiser
5
+ from .main import Robusta
6
+
7
+ __all__ = [
8
+ "ConvergenceTester",
9
+ "Initialiser",
10
+ "Robusta",
11
+ ]
@@ -0,0 +1,34 @@
1
+ # file generated by setuptools-scm
2
+ # don't change, don't track in version control
3
+
4
+ __all__ = [
5
+ "__version__",
6
+ "__version_tuple__",
7
+ "version",
8
+ "version_tuple",
9
+ "__commit_id__",
10
+ "commit_id",
11
+ ]
12
+
13
+ TYPE_CHECKING = False
14
+ if TYPE_CHECKING:
15
+ from typing import Tuple
16
+ from typing import Union
17
+
18
+ VERSION_TUPLE = Tuple[Union[int, str], ...]
19
+ COMMIT_ID = Union[str, None]
20
+ else:
21
+ VERSION_TUPLE = object
22
+ COMMIT_ID = object
23
+
24
+ version: str
25
+ __version__: str
26
+ __version_tuple__: VERSION_TUPLE
27
+ version_tuple: VERSION_TUPLE
28
+ commit_id: COMMIT_ID
29
+ __commit_id__: COMMIT_ID
30
+
31
+ __version__ = version = '0.0.1'
32
+ __version_tuple__ = version_tuple = (0, 0, 1)
33
+
34
+ __commit_id__ = commit_id = None
@@ -0,0 +1,45 @@
1
+ # als.py
2
+
3
+ import equinox as eqx
4
+ import jax
5
+ import jax.numpy as jnp
6
+
7
+ from .state import RHMFState, update_state
8
+
9
+
10
+ class WeightedAStep(eqx.Module):
11
+ ridge: float | None = eqx.field(static=True, default=None)
12
+
13
+ def __call__(self, Y, W, state: RHMFState):
14
+ G = state.G
15
+
16
+ def solve_row(y_i, w_i):
17
+ s = jnp.sqrt(w_i)
18
+ Gw = G * s[:, None]
19
+ M = Gw.T @ Gw
20
+ if self.ridge is not None:
21
+ M = M + self.ridge * jnp.eye(G.shape[1], dtype=G.dtype)
22
+ b = Gw.T @ (s * y_i)
23
+ return jnp.linalg.solve(M, b)
24
+
25
+ A_new = jax.vmap(solve_row)(Y, W) # [N, K]
26
+ return update_state(state, A=A_new)
27
+
28
+
29
+ class WeightedGStep(eqx.Module):
30
+ ridge: float | None = eqx.field(static=True, default=None)
31
+
32
+ def __call__(self, Y, W, state: RHMFState):
33
+ A = state.A
34
+
35
+ def solve_col(y_j, w_j):
36
+ s = jnp.sqrt(w_j)
37
+ Aw = A * s[:, None]
38
+ M = Aw.T @ Aw
39
+ if self.ridge is not None:
40
+ M = M + self.ridge * jnp.eye(A.shape[1], dtype=A.dtype)
41
+ b = Aw.T @ (s * y_j)
42
+ return jnp.linalg.solve(M, b)
43
+
44
+ G_new = jax.vmap(solve_col)(Y.T, W.T) # [D, K]
45
+ return update_state(state, G=G_new)
@@ -0,0 +1,64 @@
1
+ # convergence.py
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Literal, get_args
5
+
6
+ import jax
7
+ import jax.numpy as jnp
8
+ from jaxtyping import Array
9
+
10
+ from .state import RHMFState
11
+
12
+ jax.config.update("jax_enable_x64", True)
13
+
14
+ ConvStrategy = Literal["max_frac_G", "max_frac_A", "rel_frac_loss", "none"]
15
+
16
+ DEFAULT_STRATEGY = "max_frac_G"
17
+ DEFAULT_TOL = 1e-6
18
+
19
+
20
+ def max_frac_mat(old_mat: Array, new_mat: Array, tol: float) -> bool:
21
+ d_mat = old_mat - new_mat
22
+ if jnp.max(d_mat * d_mat) / jnp.mean(new_mat * new_mat) < tol:
23
+ return True
24
+ else:
25
+ return False
26
+
27
+
28
+ def rel_frac_loss(old_loss: float, new_loss: float, tol: float) -> bool:
29
+ if jnp.abs(old_loss - new_loss) / jnp.abs(new_loss) < tol:
30
+ return True
31
+ else:
32
+ return False
33
+
34
+
35
+ def never_converged(*args, **kwargs) -> bool:
36
+ return False
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class ConvergenceTester:
41
+ strategy: ConvStrategy = field(default=DEFAULT_STRATEGY)
42
+ tol: float = field(default=DEFAULT_TOL)
43
+
44
+ def __post_init__(self):
45
+ if self.strategy not in get_args(ConvStrategy):
46
+ raise ValueError(
47
+ f"Invalid strategy: {self.strategy}. Must be one of {get_args(ConvStrategy)}."
48
+ )
49
+
50
+ def is_converged(
51
+ self,
52
+ old_state: RHMFState,
53
+ new_state: RHMFState,
54
+ old_loss: float,
55
+ new_loss: float,
56
+ ) -> bool:
57
+ if self.strategy == "max_frac_G":
58
+ return max_frac_mat(old_state.G, new_state.G, tol=self.tol)
59
+ elif self.strategy == "max_frac_A":
60
+ return max_frac_mat(old_state.A, new_state.A, tol=self.tol)
61
+ elif self.strategy == "rel_frac_loss":
62
+ return rel_frac_loss(old_loss, new_loss, tol=self.tol)
63
+ elif self.strategy == "none":
64
+ return never_converged()
@@ -0,0 +1,59 @@
1
+ # frame.py
2
+
3
+ from copy import deepcopy
4
+ from dataclasses import dataclass
5
+
6
+ import jax.numpy as jnp
7
+ from jaxtyping import Array
8
+
9
+ from .convergence import ConvergenceTester
10
+ from .hmf import HMF
11
+ from .state import RHMFState
12
+
13
+
14
+ @dataclass
15
+ class OptFrame:
16
+ method: HMF
17
+ conv_tester: ConvergenceTester
18
+
19
+ def run(
20
+ self,
21
+ Y: Array,
22
+ W: Array,
23
+ init_state: RHMFState,
24
+ rotation_cadence: int,
25
+ conv_check_cadence: int,
26
+ max_iter: int,
27
+ ):
28
+ # Get the step function from the method
29
+ step_fn = self.method.get_stepper()
30
+
31
+ # Always rotate for als
32
+ if self.method.opt_method == "als":
33
+ rotation_cadence = 1
34
+
35
+ # To store the loss history
36
+ loss_history = []
37
+
38
+ # Initialise states and loss
39
+ state = init_state
40
+ prev_state = deepcopy(init_state)
41
+ prev_loss = jnp.inf
42
+
43
+ # Training loop
44
+ for i in range(max_iter):
45
+ # Do we rotate this iteration?
46
+ rot = True if (i % rotation_cadence == 0 and i != 0) else False
47
+ # Take an optimization step and record the loss
48
+ state, loss = step_fn(Y=Y, W_data=W, state=state, rotate=rot)
49
+ loss_history.append(loss)
50
+ # Check convergence and print loss every conv_check_cadence iterations
51
+ if i % conv_check_cadence == 0 and i != 0:
52
+ if self.conv_tester.is_converged(prev_state, state, prev_loss, loss):
53
+ print(f"Converged at iteration {i}")
54
+ break
55
+ prev_state = deepcopy(state)
56
+ prev_loss = loss
57
+ print(f"iter {state.it:03d} | loss {loss:.4f}", flush=True)
58
+
59
+ return state, jnp.array(loss_history)