From 71ec1f048484b1f46961784bf82572c528fc1f9a Mon Sep 17 00:00:00 2001 From: Simon Perkins Date: Tue, 10 Sep 2024 17:53:20 +0200 Subject: [PATCH 1/4] Remove warning sections that aren't rendered correctly on github --- README.rst | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index d6ad515..a376afc 100644 --- a/README.rst +++ b/README.rst @@ -86,14 +86,9 @@ Why xarray-ms? Work in Progress ---------------- -.. warning:: - - xarray-ms is currently under active development and does not yet - have feature parity with xradio_. - -.. warning:: - - The Measurement Set v4 specification is currently under active development. +The Measurement Set v4 specification is currently under active development. +xarray-ms is currently under active development and does not yet +have feature parity with xradio_. Most measures information and many secondary sub-tables are currently missing. However, the most important parts of the ``MAIN`` tables, From dc9527f8fd4736acff993439c5ea22680c913a2f Mon Sep 17 00:00:00 2001 From: Simon Perkins Date: Tue, 10 Sep 2024 17:55:03 +0200 Subject: [PATCH 2/4] Remove stray boilerplate --- doc/source/index.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 2045570..84d6ebd 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,11 +6,6 @@ xarray-ms documentation ======================= -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - .. toctree:: :maxdepth: 2 :caption: Contents: From 4681e033ac13b1820b1a92362a50149fc970facb Mon Sep 17 00:00:00 2001 From: Simon Perkins Date: Tue, 10 Sep 2024 17:59:56 +0200 Subject: [PATCH 3/4] open_{dataset/datatree} docstring formatting --- xarray_ms/backend/msv2/entrypoint.py | 64 ++++++++++++++++++++++------ xarray_ms/utils.py | 8 ++++ 2 files changed, 60 insertions(+), 12 deletions(-) diff --git a/xarray_ms/backend/msv2/entrypoint.py b/xarray_ms/backend/msv2/entrypoint.py index 786a217..75107e2 100644 --- a/xarray_ms/backend/msv2/entrypoint.py +++ b/xarray_ms/backend/msv2/entrypoint.py @@ -11,6 +11,7 @@ from xarray.backends import BackendEntrypoint from xarray.backends.common import AbstractWritableDataStore, _normalize_path from xarray.backends.store import StoreBackendEntrypoint +from xarray.core.dataset import Dataset from xarray.core.datatree import DataTree from xarray.core.utils import try_read_magic_number_from_file_or_path @@ -22,13 +23,12 @@ ) from xarray_ms.backend.msv2.table_factory import TableFactory from xarray_ms.errors import InvalidPartitionKey +from xarray_ms.utils import format_docstring if TYPE_CHECKING: from io import BufferedIOBase from xarray.backends.common import AbstractDataStore - from xarray.core.dataset import Dataset - from xarray.core.datatree import DataTree from xarray_ms.backend.msv2.structure import PartitionKeyT @@ -248,18 +248,41 @@ def guess_can_open( return False + @format_docstring(DEFAULT_PARTITION_COLUMNS=DEFAULT_PARTITION_COLUMNS) def open_dataset( self, filename_or_obj: str | os.PathLike[Any] | BufferedIOBase | AbstractDataStore, *, drop_variables: str | Iterable[str] | None = None, - partition_columns=None, - partition_key=None, - auto_corrs=True, - ninstances=8, - epoch=None, - structure_factory=None, + partition_columns: List[str] | None = None, + partition_key: PartitionKeyT | None = None, + auto_corrs: bool = True, + ninstances: int = 8, + epoch: str | None = None, + structure_factory: MSv2StructureFactory | None = None, ) -> Dataset: + """Create a :class:`~xarray.Dataset` presenting an MSv4 view + over a partition of a MSv2 CASA Measurement Set + + Args: + filename_or_obj: The path to the MSv2 CASA Measurement Set file. + drop_variables: Variables to drop from the dataset. + partition_columns: The columns to use for partitioning the Measurement set. + Defaults to :code:`{DEFAULT_PARTITION_COLUMNS}`. + partition_key: A key corresponding to an individual partition. + For example :code:`(('DATA_DESC_ID', 0), ('FIELD_ID', 0))`. + If :code:`None`, the first partition will be opened. + auto_corrs: Include/Exclude auto-correlations. + ninstances: The number of Measurement Set instances to open for parallel I/O. + epoch: A unique string identifying the creation of this Dataset. + This should not normally need to be set by the user + structure_factory: A factory for creating MSv2Structure objects. + This should not normally need to be set by the user + + Returns: + A :class:`~xarray.Dataset` referring to the unique + partition specified by :code:`partition_columns` and :code:`partition_key`. + """ filename_or_obj = _normalize_path(filename_or_obj) store = MSv2Store.open( filename_or_obj, @@ -274,17 +297,34 @@ def open_dataset( store_entrypoint = StoreBackendEntrypoint() return store_entrypoint.open_dataset(store) + @format_docstring(DEFAULT_PARTITION_COLUMNS=DEFAULT_PARTITION_COLUMNS) def open_datatree( self, filename_or_obj: str | os.PathLike[Any] | BufferedIOBase | AbstractDataStore, *, drop_variables: str | Iterable[str] | None = None, - partition_columns=None, - auto_corrs=True, - ninstances=8, - epoch=None, + partition_columns: List[str] | None = None, + auto_corrs: bool = True, + ninstances: int = 8, + epoch: str | None = None, **kwargs, ) -> DataTree: + """Create a :class:`~xarray.core.datatree.DataTree` presenting an MSv4 view + over multiple partitions of a MSv2 CASA Measurement Set. + + Args: + filename_or_obj: The path to the MSv2 CASA Measurement Set file. + drop_variables: Variables to drop from the dataset. + partition_columns: The columns to use for partitioning the Measurement set. + Defaults to :code:`{DEFAULT_PARTITION_COLUMNS}`. + auto_corrs: Include/Exclude auto-correlations. + ninstances: The number of Measurement Set instances to open for parallel I/O. + epoch: A unique string identifying the creation of this Dataset. + This should not normally need to be set by the user + + Returns: + An xarray :class:`~xarray.core.datatree.DataTree` + """ if isinstance(filename_or_obj, os.PathLike): ms = str(filename_or_obj) elif isinstance(filename_or_obj, str): diff --git a/xarray_ms/utils.py b/xarray_ms/utils.py index 7622255..741afa9 100644 --- a/xarray_ms/utils.py +++ b/xarray_ms/utils.py @@ -76,3 +76,11 @@ def normalise_args( args.append(default) return tuple(args), kw + + +def format_docstring(**subs): + def decorator(o): + o.__doc__ = o.__doc__.format(**subs) + return o + + return decorator From 3e7944a845a003caddd8b81bb2cc70273775a2af Mon Sep 17 00:00:00 2001 From: Simon Perkins Date: Tue, 10 Sep 2024 18:43:45 +0200 Subject: [PATCH 4/4] Update history --- doc/source/history.rst | 7 +++++++ doc/source/index.rst | 1 + 2 files changed, 8 insertions(+) create mode 100644 doc/source/history.rst diff --git a/doc/source/history.rst b/doc/source/history.rst new file mode 100644 index 0000000..2d0b074 --- /dev/null +++ b/doc/source/history.rst @@ -0,0 +1,7 @@ +HISTORY +======= + +0.2.0 (DD-MM-YYYY) +------------------ + +* Initial release diff --git a/doc/source/index.rst b/doc/source/index.rst index 84d6ebd..a68485c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,3 +13,4 @@ xarray-ms documentation readme install api + history