Skip to content

Commit 397d429

Browse files
robinschmidrobinschmid
authored
Merge pull request #258 from robinschmid/tech-stack
Index, getting started, install, dev docs
2 parents 282bad4 + 56a23ee commit 397d429

20 files changed

+276
-221
lines changed

‎docs/additional_resources.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Additional figures
2+
3+
## Performance {#performance}
4+
![mzmine_performance_both.png](img/performance/mzmine_performance_both.png)
5+
6+
![mzmine_performance_memory.png](img/performance/mzmine_performance_memory.png)
7+
8+
![mzmine_performance_speed.png](img/performance/mzmine_performance_speed.png)
9+
10+
## Feature table
11+
12+
![example_featuretable_light.png](img/example_featuretable_light.png)

‎docs/coding/general_structure.md‎

Lines changed: 130 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,175 @@
1-
## **General structure of MZmine3 code**
1+
# mzmine architecture & development process
22

3-
# **MZmine architecture**
3+
## Technology
44

5-
MZmine 3 is developed using Java technology, therefore it is completely platform independent, requiring only Java runtime for running.
6-
One of the main design goals is to keep a strict separation between the application core and modules for data processing and visualization. The general architecture of the modules is presented at the following scheme.
5+
mzmine is developed in modern Java, and the distributed installers and portable versions ship with a
6+
matching Java Runtime. This makes mzmine standalone platform independent. There is no need to
7+
install Java on the target machine. Updates can be installed over older releases and follow semantic
8+
versioning, i.e., major.minor.patch like 4.8.0. In rare cases, the mzmine installer may ask for
9+
manual removal of a previous installation. Run mzmine through its graphical user interface (GUI),
10+
built with JavaFX, or via [command line interface](../commandline_tool.md) (CLI) to run batch
11+
processing.
712

8-
![Architecture](mzmine3-architecture-01.png)
13+
Contributions to the mzmine [source code](https://github.com/mzmine/mzmine)
14+
and [documentation](https://github.com/mzmine/mzmine_documentation) are possible through pull
15+
requests (code) or issues to the respective repositories. Feel free to create a fork of each
16+
repository to work on feature branches. We recommend that you reach out to our team early in your
17+
idea or development phase to boost your productivity. We can provide help to new developers to get
18+
started with mzmine development and provide pointers to already existing resources.
919

10-
[//]: # (TODO Describe application core)
11-
[//]: # (Describe data processing modules)
12-
[//]: # (Describe visualization specifics)
20+
- How to contribute to the [documentation](../contribute.md)?
21+
- How to contribute to the [mzmine code base](../contribute_intellij.md)?
1322

14-
[//]: # ( System)
23+
!!! tip
24+
The practical instructions for mzmine coding can be found [here](module_development.md).
1525

16-
[//]: # ( Service)
26+
## GitHub issues as a pool of ideas and feedback:
1727

18-
[//]: # ( Layers)
28+
- Providing **feedback** on specific modules or functions
29+
- Outlining **feature requests**: This can be small improvements or full module ideas. Useful
30+
information includes: Links to articles, reference implementations, and descriptions of user
31+
inputs, expected results, and example use cases.
32+
- Reporting **bugs**: Provide all details on how to reproduce bugs, the log file, batch
33+
configuration, example data
1934

20-
[//]: # ( Components)
35+
One of the main design goals is to keep a strict separation between the application core and modules
36+
for data processing and visualization. The general architecture of the modules is presented at the
37+
following scheme.
2138

22-
[//]: # ( Classes)
39+
## Roadmap
2340

24-
[//]: # ( Methods)
41+
The development process of mzmine is agile and driven by multiple factors:
2542

26-
[//]: # (List of classes - modules correspondence)
43+
- **User Feature Requests**: Community needs and feedback shape our development priorities
44+
- **Strategic Partnerships**: Collaborations with academic and industry partners guide development
45+
directions
46+
- **Contracted Development**: Specific features can be developed through funded projects
47+
- **Community Contributors**: Open-source contributions from developers worldwide
48+
- **Internal Planning**: Strategic development guided by the mzio team's expertise and vision
2749

28-
!!! tip
29-
The practical instructions for MZmine coding can be found [here](module_development.md).
50+
Our roadmap remains flexible to accommodate emerging needs while maintaining focus on core
51+
functionality improvements.
3052

31-
## **Module structure**
53+
# Development
3254

33-
Each module in MZmine necessarily contains three classes:
55+
## Core architecture
3456

35-
- [Name]Module.java
36-
- [Name]Parameters.java
37-
- [Name]Task.java
57+
mzmine's core architecture is built on several key components that enable efficient and modular data
58+
processing:
3859

39-
Optionally module can contain dialog class:
60+
### Task controller
4061

41-
- [Name]Dialog.java
62+
The TaskController manages the execution of processing tasks, allowing multiple operations to run in
63+
parallel. It handles task scheduling, priority management, and resource allocation to optimize
64+
performance on multi-core systems. Tasks can be monitored through progress tracking and canceled if
65+
needed.
4266

43-
!!! tip
44-
You can fnd examples for all these classes in the `java/io/github/mzmine/modules/example` folder.
67+
### Module system
4568

46-
### **Module class**
69+
mzmine uses a modular architecture where each processing step is implemented as an independent
70+
module. This design:
4771

48-
Each Module class implements one of three interfaces:
72+
- Ensures loose coupling between different processing steps
73+
- Makes modules reusable across different workflows
74+
- Simplifies maintenance and testing
75+
- Allows easy addition of new functionality without modifying existing code
4976

50-
- **MZMineModule** interface - the most basic interface, aimed at any module that has to store some kind of parameters,
51-
- **MZMineRunnableModule** interface - an interface that extends MZmine module and presents a `runModule()` method, which provides an opportunity to run task (for example, from the dialog),
52-
- **MZMineProcessingModule** interface - an interface that extends MZMineRunnableModule and gives an opportunity to execute a module in a batch.
77+
### GUI framework
5378

79+
The graphical user interface is built with JavaFX following the Model-View-Controller (MVC) pattern:
5480

55-
### **Parameters class**
81+
- Interactive data visualization dashboards
82+
- Real-time updates of processing results
83+
- Flexible window management for multiple views
84+
- Custom controls for mass spectrometry data visualization
85+
- Interactive linking between dashboards through reactive programming (binding of JavaFx properties)
5686

57-
The Parameters class is defined by the **ParameterSet interface**, which declares functions necessary to get, load, and save module parameters. Also, in this class additional information must be defined, such as compatibility of module with the IMS data and URL of online documentation. Typically, a module would use **SimpleParameterSet class**.
87+
### Parameter system
5888

59-
[//]: # (TODO Add parameter types)
89+
User parameters are easy to design and extend in their functionality and offer:
6090

61-
### Task
91+
- Consistent, auto generated user interfaces across all modules
92+
- Type-safe parameter handling
93+
- Automatic validation of user inputs
94+
- Persistent storage of parameter values
95+
- Versioning of parameters, offering handling of simple changes in parameter behavior or to notify
96+
about impactful changes
6297

63-
This is the part where the functionality of a module is implemented. The main specifications are defined by the **Task interface**, with methods that control and monitor the flow of a task execution (such as `cancel()`, `getTaskPriority()`, `getFinishedPercentage()`). Task interface is implemented by **AbstractTask class**, which defines some of the most common used methods.
98+
## Module development
6499

65-
[//]: # (AbstractTask)
66-
[//]: # (Here you can focus on algorithm implementation and performance.)
100+
Each module in mzmine is built from three classes:
67101

68-
[//]: # (constructor)
102+
- [Name]Module.java
103+
- [Name]Parameters.java
104+
- [Name]Task.java
105+
106+
!!! tip
107+
You can fnd examples for all these classes in the
108+
`java/io/github/mzmine/modules/example` [folder](https://github.com/mzmine/mzmine/tree/master/mzmine-community/src/main/java/io/github/mzmine/modules/example)
109+
110+
### Module class
69111

70-
[//]: # (initialize())
112+
The module holds metadata like the name, description, and ParameterSet class.
71113

72-
[//]: # (run())
114+
Each Module class implements one of three interfaces or its subclasses:
73115

74-
[//]: # (### Dialog)
116+
- **MZMineModule** interface - the most basic interface, aimed at any module that has to store some
117+
kind of parameters,
118+
- **MZMineRunnableModule** interface - an interface that extends mzmine module and presents a
119+
`runModule()` method, which provides an opportunity to run task (for example, from the dialog),
120+
- **MZMineProcessingModule** interface - an interface that extends MZMineRunnableModule and gives an
121+
opportunity to execute a module in a batch.
75122

123+
!!! tip
124+
125+
There are special implementations of Module to make the definition and scheduling easier, like
126+
[TaskPerFeatureListModule](https://github.com/mzmine/mzmine/blob/master/mzmine-community/src/main/java/io/github/mzmine/modules/impl/TaskPerFeatureListModule.java)
127+
that splits the work in one task per feature list, and
128+
[SingleTaskFeatureListsModule](https://github.com/mzmine/mzmine/blob/master/mzmine-community/src/main/java/io/github/mzmine/modules/impl/SingleTaskFeatureListsModule.java)
129+
that processes all feature lists in a single task.
76130

77-
[//]: # (### Module)
131+
### ParameterSet class
78132

79-
[//]: # (TODO Create following subpages?)
133+
The Parameters class is defined by the **ParameterSet interface**, which declares functions
134+
necessary to get, load, and save module parameters. This class provides versioning with mapping
135+
functions to load parameters that were saved by a previous version of mzmine. This includes simple
136+
mapping of parameter values, e.g., if a parameter changed its data type, or more complex handling of
137+
version changes to ensure compatibility with newer versions. The parameters are displayed in a
138+
**ParameterSetupDialog** and interfaces are auto-generated to allow user optimization. Custom *
139+
*ParameterSetupDialog**s may provide charts and other visual feedback to facilitate parameter
140+
tuning.
141+
The ParameterSet class also points to this documentation by providing a URL. If you develop a
142+
module, please provide a documentation and link as well.
143+
information must
80144

81-
[//]: # (## **Developing a new MZmine module**))
145+
**ParameterSets** are made up of **Parameters** that are accessed through static instances of these
146+
parameters. Each **Parameter** defines the GUI controls, saving and loading, and value validation.
82147

83-
[//]: # ()
84-
[//]: # ()
85-
[//]: # (## **Adding a new feature**)
148+
!!! typ
86149

87-
[//]: # ()
88-
[//]: # ()
89-
[//]: # (## **Fixing a bug**)
150+
Typically, new Parameters classes can extend the [**SimpleParameterSet class**.](https://github.com/mzmine/mzmine/blob/master/mzmine-community/src/main/java/io/github/mzmine/parameters/impl/SimpleParameterSet.java)
90151

91-
[//]: # (TODO Add more info on the following)
152+
#### Latest module parameters
92153

93-
[//]: # (### Creating parameters))
154+
MZmineCore contains a map of the latest module parameters. This ParameterSet is often copied as the
155+
starting point for creating the parameter setup dialog. Once the user runs a module with different
156+
parameters, those latest parameters are updated.
157+
158+
### Task
94159

95-
[//]: # ()
96-
[//]: # (constructor)
160+
This class implements the logic of a module. The main specifications are
161+
defined by the **Task interface** and its abstract child classes. It defines methods that control
162+
and monitor the flow of a task execution (such as `cancel()`, `getTaskPriority()`,
163+
`getFinishedPercentage()`, `getStatus()`).
97164

98-
[//]: # (showSetupDialog)
165+
A new task is usually created by its module, added to the TaskController with a specified
166+
TaskPriority (HIGH, NORMAL), and the task controller will call its **run** method. If successful,
167+
the task should add an applied method to the processed RawDataFiles and FeatureLists. These applied
168+
methods hold a trace of all operations applied to data files and feature lists and will enable later
169+
generation of batch configurations from the processing history.
99170

100-
[//]: # (#### i/o)
171+
The best starting points are newer abstract classes like **AbstractSimpleTask**,
172+
**AbstractFeatureListTask**, or **AbstractRawDataFileTask** that already define much of the control
173+
flow logic and facilitate the creation of applied methods.
101174

102175
{{ git_page_authors }}

‎docs/coding/macos_signing.md‎

Lines changed: 0 additions & 90 deletions
This file was deleted.

‎docs/css/extra.css‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,3 @@
1010
.md-header {
1111
background-color: #0072b2;
1212
}
13-

0 commit comments

Comments
 (0)