diff --git a/docs/source/_static/mdaviz_gui.png b/docs/source/_static/mdaviz_gui.png new file mode 100644 index 00000000..d2cb28ac Binary files /dev/null and b/docs/source/_static/mdaviz_gui.png differ diff --git a/docs/source/api/select_fields_table_view.rst b/docs/source/api/mda_file_table_model.rst similarity index 60% rename from docs/source/api/select_fields_table_view.rst rename to docs/source/api/mda_file_table_model.rst index 059b46f6..cdfeac37 100644 --- a/docs/source/api/select_fields_table_view.rst +++ b/docs/source/api/mda_file_table_model.rst @@ -1,7 +1,7 @@ ==================================== -select_fields_table_view +mda_file_table_model ==================================== -.. automodule:: mdaviz.select_fields_table_view +.. automodule:: mdaviz.mda_file_table_model :members: :private-members: diff --git a/docs/source/api/mda_file_table_view.rst b/docs/source/api/mda_file_table_view.rst new file mode 100644 index 00000000..3d781139 --- /dev/null +++ b/docs/source/api/mda_file_table_view.rst @@ -0,0 +1,7 @@ +==================================== +mda_file_table_view +==================================== + +.. automodule:: mdaviz.mda_file_table_view + :members: + :private-members: diff --git a/docs/source/api/select_fields_table_model.rst b/docs/source/api/select_fields_table_model.rst deleted file mode 100644 index f967d216..00000000 --- a/docs/source/api/select_fields_table_model.rst +++ /dev/null @@ -1,8 +0,0 @@ -==================================== -select_fields_table_model -==================================== - -.. FIXME: problems with this module - ... automodule:: mdaviz.select_fields_table_model - :members: - :private-members: diff --git a/docs/source/changes.rst b/docs/source/changes.rst new file mode 100644 index 00000000..6fa805e2 --- /dev/null +++ b/docs/source/changes.rst @@ -0,0 +1,6 @@ +.. _changes: + +Changes +======= + +TODO \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 7ff40acf..a19bab61 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,26 +1,18 @@ -====== -mdaviz -====== +======================= +mdaviz: MDA Data Viewer +======================= -Python Qt5 application to visualize mda data. -.. from gemviz - .. list-table:: - :widths: 1 2 - * - .. figure:: _static/gemviz_gui.png - :alt: fig.gemviz_gui - - * Browse catalogs of Bluesky data - * Search for data by keywords or date - * Visualize (1-D plots now) +Key Features +============ -.. toctree:: - :maxdepth: 1 - :hidden: +* Visualize MDA data (currently supports 1-D plots) +* Basic mathematical information and cursor utilities +* Fitting functionality coming soon - user_guide - install - api +Documentation +============= .. icons: https://fonts.google.com/icons .. grid:: 3 @@ -38,9 +30,43 @@ Python Qt5 application to visualize mda data. :link-type: doc -Indices and tables -================== +.. figure:: _static/mdaviz_gui.png + :alt: fig.mdaviz_gui + :width: 100% + :align: center + :figclass: align-center + :figwidth: 100% + + Screenshot of the mdaviz GUI displaying sample data. + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: Contents: + :hidden: + + user_guide + install + api + changes + license + +About +===== + +:home: https://bcda-aps.github.io/mdaviz/ +:bug tracker: https://github.com/BCDA-APS/mdaviz/issues +:source: https://github.com/BCDA-APS/mdaviz +:license: :ref:`license` +:full version: |release| +:published: |today| +:revisions: :ref:`History of code changes ` +:index: :ref:`genindex` +:module: :ref:`modindex` +:search: :ref:`search` + +Acknowledgements +================ -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +"This product includes software produced by UChicago Argonne, LLC +under Contract No. DE-AC02-06CH11357 with the Department of Energy." diff --git a/docs/source/install.rst b/docs/source/install.rst index 9953ade8..8bbc6045 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -2,24 +2,54 @@ Installation Guide ==================================== -First said, this software application is pre-release and may contain significant -unhandled bugs. Please report any issues you encounter -(https://github.com/BCDA-APS/mdaviz/issues/new) or feature requests, too. - -Suggested installation for developers is to use -``pip`` with its *editable* mode: - -This project is still in development. We have plans for production release -(https://github.com/orgs/BCDA-APS/projects/6). Until the production release, you -should run ``mdaviz`` as would a developer by following these (Linux) instructions: - -1. Navigate to a directory where you have similar software projects -2. ``git clone https://github.com/BCDA-APS/mdaviz`` - - only need to do this once, assumes you have ``git`` command -3. ``cd mdaviz`` -4. ``conda env create --force -n mdaviz -f ./env.yml`` - - only need to do this once, assumes you have ``conda`` command -5. ``conda activate mdaviz`` -6. ``pip install -e .`` -7. ``mdaviz &`` +The ``mdaviz`` package is available for installation by ``pip`` or from source. +Please [report](https://github.com/BCDA-APS/mdaviz/issues/new) any issues you encounter or feature requests, too. +pip +--- + +Released versions of ``mdaviz`` are available on `PyPI +`_. + +If you have ``pip`` installed, then you can install:: + + $ pip install mdaviz + +source +------ + +The latest development versions of apstools can be downloaded from the +GitHub repository listed above:: + + $ git clone https://github.com/BCDA-APS/mdaviz + +To install from the source directory using ``pip`` in editable mode:: + + $ cd mdaviz + $ python -m pip install -e . + +Required Libraries +------------------ + +The repository's ``env.yml`` file lists the additional packages +required by ``mdaviz``. Most packages are available as conda packages +from https://anaconda.org. The others are available on +https://PyPI.python.org. + +To Run This Program +=================== + +For ``pip`` installation, activate the conda environment and start the application:: + + $ conda activate mdaviz + $ mdaviz + +For source installation, navigate to the mdaviz directory then use the same commands:: + + $ cd mdaviz + $ conda activate mdaviz + $ mdaviz + +You can also create an alias for convenience; e.g., in bash:: + + $ alias start_mdaviz="conda activate mdaviz; mdaviz" diff --git a/docs/source/license.rst b/docs/source/license.rst new file mode 100644 index 00000000..36252c4e --- /dev/null +++ b/docs/source/license.rst @@ -0,0 +1,7 @@ +.. _license: + +License +======= + +.. literalinclude:: ../../mdaviz/LICENSE + :language: text \ No newline at end of file diff --git a/mdaviz/data_table_model.py b/mdaviz/data_table_model.py index 054a8ef1..66d6514d 100644 --- a/mdaviz/data_table_model.py +++ b/mdaviz/data_table_model.py @@ -1,25 +1,32 @@ +""" +.. autosummary:: + + ~DataTableModel + +""" + from PyQt5 import QtCore from PyQt5.QtCore import QAbstractTableModel, QVariant, Qt class DataTableModel(QAbstractTableModel): - """ - This model is designed to handle data represented as a dictionary where keys correspond to column labels and values are lists of data points for each column. + """This model is designed to handle data represented as a dictionary where keys correspond to column labels and values are lists of data points for each column. + - Parameters: - - scanDict (dict): A dictionary where keys are pos/det indexes and values are dictionaries: - {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}. - - parent (QObject, optional): The parent object for this table model, default is None. + Args: + - scanDict (dict): A dictionary where keys are pos/det indexes and values are dictionaries: + {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}. + - parent (QObject, optional): The parent object for this table model, default is None. Methods: - - rowCount: Returns the number of rows in the table model. - - columnCount: Returns the number of columns in the table model. - - data: Returns the data to be displayed for a given index and role. - - headerData: Provides the header labels for the table model. - - columnLabels: Returns a list of column labels. - - setColumnLabels: Sets the column labels based on keys from the input dictionary. - - allData: Returns the current data stored in the model. - - setAllData: Sets the model's data using the input dictionary. + - rowCount: Returns the number of rows in the table model. + - columnCount: Returns the number of columns in the table model. + - data: Returns the data to be displayed for a given index and role. + - headerData: Provides the header labels for the table model. + - columnLabels: Returns a list of column labels. + - setColumnLabels: Sets the column labels based on keys from the input dictionary. + - allData: Returns the current data stored in the model. + - setAllData: Sets the model's data using the input dictionary. The model dynamically adjusts to changes in the input data, updating both the data displayed and the column headers as necessary. """ diff --git a/mdaviz/mda_file_table_model.py b/mdaviz/mda_file_table_model.py index db0f2b33..8a1befc4 100644 --- a/mdaviz/mda_file_table_model.py +++ b/mdaviz/mda_file_table_model.py @@ -23,9 +23,9 @@ .. autosummary:: - ~SelectFieldsTableModel + ~MDAFileTableModel ~ColumnDataType - ~FieldSelectionRuleType + ~FieldRuleType ~TableColumn ~TableField """ diff --git a/mdaviz/mda_file_table_view.py b/mdaviz/mda_file_table_view.py index 02f6560a..4632dbc7 100644 --- a/mdaviz/mda_file_table_view.py +++ b/mdaviz/mda_file_table_view.py @@ -128,29 +128,26 @@ def data2Plot(self, selections): Extracts selected datasets for plotting from scanDict based on user selections. Parameters: - - selections: A dictionary with keys "X" and "Y", where "X" is the index for the x-axis data - and "Y" is a list of indices for the y-axis data. + - selections: A dictionary with keys "X" and "Y", where "X" is the index for the x-axis data + and "Y" is a list of indices for the y-axis data. Returns: - - A tuple of (datasets, plot_options), where datasets is a list of tuples containing the - data and options (label) for each dataset, and plot_options contains overall plotting configurations. + - A tuple of (datasets, plot_options), where datasets is a list of tuples containing the + data and options (label) for each dataset, and plot_options contains overall plotting configurations. - ..note:: - scanDict = {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...', - 'type':...}}. """ datasets, plot_options = [], {} if self.data() is not None: - # extract scan info: + # ------ extract scan info: fileName = self.data()["fileInfo"]["fileName"] filePath = self.data()["fileInfo"]["filePath"] scanDict = self.data()["fileInfo"]["scanDict"] - # extract x data: + # ------ extract x data: x_index = selections.get("X") - x_data = scanDict[x_index].get("data") if x_index in scanDict else None - # extract y(s) data: + x_data = scanDict[x_index].get("data") if x_index in scanDict else None + # ------ extract y(s) data: y_index = selections.get("Y", []) y_first_unit = y_first_name = "" for i, y in enumerate(y_index): @@ -169,7 +166,7 @@ def data2Plot(self, selections): ds_options["label"] = y_label ds = [x_data, y_data] if x_data is not None else [y_data] datasets.append((ds, ds_options)) - + # scanDict = {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}} plot_options = { "x": scanDict[x_index].get("name", "") if x_index in scanDict else "", "x_unit": ( diff --git a/mdaviz/utils.py b/mdaviz/utils.py index 37c6a4c3..c42d75aa 100644 --- a/mdaviz/utils.py +++ b/mdaviz/utils.py @@ -55,14 +55,13 @@ def num2fstr(x): def byte2str(byte_literal): """ - Converts a byte literal to a UTF-8 encoded string. - If the input is not a byte literal, it is returned as is without any conversion. + Converts a byte literal to a UTF-8 encoded string. If the input is not a byte literal, it is returned as is without any conversion. Parameters: - - byte_literal (bytes | Any): The byte literal to be decoded or any input to be returned as is if not bytes. + - byte_literal (bytes | Any): The byte literal to be decoded or any input to be returned as is if not bytes. Returns: - - str | Any: The decoded string if the input is a byte literal, otherwise the original input. + - str | Any: The decoded string if the input is a byte literal, otherwise the original input. """ return ( byte_literal.decode("utf-8") @@ -76,24 +75,24 @@ def get_det(mda_file_data): Extracts scan positioners and detectors from an MDA file data object. This function processes an mda.scanDim object to extract its scanPositioner and scanDetector instances. - It organizes these instances into a dictionary, with their indexes as keys in the order of p0, P1,... Px, D01, D02,... DX. - p0 is a default scanPositioner object representing the point index. If additional positioners exist, they follow p0 in sequence. - The first detector is labeled D01 and subsequent detectors follow in numerical order. + It organizes these instances into a dictionary, with their indexes as keys in the order of ``p0, P1,... Px, D01, D02,... DX``. + ``p0`` is a default scanPositioner object representing the point index. If additional positioners exist, they follow ``p0`` in sequence. + The first detector is labeled ``D01`` and subsequent detectors follow in numerical order. Parameters: - - mda_file_data: An instance of an mda.scanDim object, which contains the MDA file data to be processed. + - mda_file_data: An instance of an mda.scanDim object, which contains the MDA file data to be processed. Returns: - - A tuple containing: - - A dictionary (d) where keys are indexes, mapping to either scanPositioner or scanDetector objects. - The dictionary is structured as {0: p0, 1: P1, ..., np: D01, np+1: D02, ..., np+nd: DX}. - - The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner - other than the default index positioner exists, otherwise 0. - - The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner. - - Note: - - p0 is created by default and corresponds to the point index, described as an 'Index' scanPositioner object with predefined properties. - - np is the total number of positioners, nd the number of detectors, and npts the number of data points actually acquired. + A tuple containing: + - A dictionary (d) where keys are indexes, mapping to either scanPositioner or scanDetector objects. + The dictionary is structured as ``{0: p0, 1: P1, ..., np: D01, np+1: D02, ..., np+nd: DX}``. + - The index (first_pos) of the first positioner in the returned dictionary. This is 1 if a positioner + other than the default index positioner exists, otherwise 0. + - The index (first_det) of the first detector in the returned dictionary, which directly follows the last positioner. + + Notes: + - p0 is created by default and corresponds to the point index, described as an 'Index' scanPositioner object with predefined properties. + - np is the total number of positioners, nd the number of detectors, and npts the number of data points actually acquired. """ d = {} @@ -141,19 +140,18 @@ def get_scan(mda_file_data): follow in numerical order: p0, p1,... px, d01, d02,... dX. Parameters: - - mda_file_data: An instance of an mda.scanDim object to be processed. + - mda_file_data: An instance of an mda.scanDim object to be processed. Returns: - - A tuple containing: - - A dictionary keyed by index, each mapping to a sub-dictionary containing - the scan object ('object') along with its 'data', 'unit', 'name' and 'type'. - Structure: - {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...', - 'type':...}}. - - The index (first_pos) of the first positioner in the returned dictionary. This - is 1 if a positioner other than the default index positioner exists, otherwise 0. - - The index (first_det) of the first detector in the returned dictionary, which - directly follows the last positioner. + - A tuple containing: + - A dictionary keyed by index, each mapping to a sub-dictionary containing + the scan object ('object') along with its 'data', 'unit', 'name' and 'type'. + Structure: + {index: {'object': scanObject, 'data': [...], 'unit': '...', 'name': '...','type':...}}. + - The index (first_pos) of the first positioner in the returned dictionary. This + is 1 if a positioner other than the default index positioner exists, otherwise 0. + - The index (first_det) of the first detector in the returned dictionary, which + directly follows the last positioner. """ d = {} @@ -228,10 +226,10 @@ def mda2ftm(selection): This is used to sync selection states between SelectFieldsTableModel and MDA_MVC. Parameters: - - selection (dict): The selection in MVC format to be converted. + - selection (dict): The selection in MVC format to be converted. Returns: - - dict: The selection converted to TM format. + - dict: The selection converted to TM format. """ if selection is not None: ftm_selection = { @@ -252,10 +250,10 @@ def ftm2mda(selection): Used to update MDA_MVC selection state (self.selectionField()) based on changes in SelectFieldsTableModel. Parameters: - - selection (dict): The selection in TM format to be converted. + - selection (dict): The selection in TM format to be converted. Returns: - - dict: The selection converted to MVC format. + - dict: The selection converted to MVC format. """ mda_selection = {} if selection is not None: @@ -336,10 +334,11 @@ def reconnect(signal, new_slot): Disconnects any slots connected to the given signal and then connects the signal to the new_slot. Parameters: - - signal: The signal to disconnect and then reconnect. - - new_slot: The new slot to connect to the signal. + - signal: The signal to disconnect and then reconnect. + - new_slot: The new slot to connect to the signal. - Note: This function catches TypeError which occurs if the signal was not connected to any slots. + Note: + - this function catches TypeError which occurs if the signal was not connected to any slots. """ try: signal.disconnect()