mgnipy.V2.mgnifier.metadata module

mgnipy.V2.mgnifier.metadata module#

class MGnifyMetadata(data=None, id_label=None)[source]#

Bases: ResultsHandler

Parameters:
append_result(page_num, value)[source]#

Append a single metadata record to the results. This method adds a new record to the existing results, typically used when processing paginated responses.

Parameters:

  • page_num (int ) – The page number (or request number) to which the record should be appended.

  • value (dict ) – A single metadata record to append to the results.

property data#

Get the data associated with the current instance.

property downloads: list [dict ] | None #

Get the downloads information from the current results, if available. This property extracts the ‘downloads’ key from each record in the results.

Returns:

A list of download information dictionaries, or None if no results are available.

Return type:

list [dict ] or None

get_ids(label=None)#

Get a list of IDs/accessions from the current metadata.

Parameters:

label (str , optional) – The key to extract IDs from. If None, uses the default key based on the resource type.

Returns:

A list of IDs extracted from the metadata.

Return type:

list of str

Raises:

ValueError – If no data is available to extract IDs from.

property ids: list [str ] | None #

Get the list of identifiers from the current results.

Returns:

List of identifiers (accessions, etc.), or None if no results.

Return type:

list [str ] or None

Examples

>>> from mgnipy.V2.mgnifier import MGnifier
>>> query = MGnifier("studies")
>>> query.get()
>>> ids = query.search_results.ids
property pages: int | None #

The pages available in the results, if any. This is determined by the keys of the results dictionary, which represent page numbers.

Returns:

A list of page numbers available in the results.

Return type:

list [int ]

property records: chain | None #

Get an iterator of individual metadata records from the retrieved results, if available. This property provides a convenient way to access the metadata records without needing to handle pagination.

Used by ResultsHandler mixin.

Returns:

An iterator that yields individual metadata records if results are available, otherwise None.

Return type:

chain or None

property results: dict [int , list [dict ]]#

Get the retrieved metadata results, if available. Results are stored in a dictionary with request number (e.g. page number) as keys.

to_json(data=None, orient='records', lines=True, **json_kwargs)#

Convert the current metadata to a JSON string or save it to a file.

Parameters:

  • data (dict of int to list of dict , optional) – The paginated data to convert. If None, uses self.qs._results.

  • **json_kwargs – Additional keyword arguments passed to the JSON serialization function.

  • orient (str )

  • lines (bool )

Returns:

The JSON string representation of the metadata, or None if no data is available.

Return type:

str or None

Raises:

RuntimeError – If no data is available to convert.

to_list(*, data=None, drop_duplicates=False)#

Convert the current or provided metadata to a list of dictionaries.

Parameters:

  • data (optional) – The paginated data to convert. If None, uses :pyattr:`data`.

  • drop_duplicates (bool , default True) – Whether to drop duplicate records from the list.

Returns:

A list of metadata records as dictionaries, or None if no data is available.

Return type:

list

Examples

>>> handler = ResultsHandler(data=[{"x": 10}])
>>> handler.to_list()
[{'x': 10}]
to_pandas(data=None, expand_nested_dicts=False, rename_columns=None, drop_duplicates=False, **kwargs)#

Convert the current or provided metadata to a pandas DataFrame.

Parameters:

  • data (list of dict , optional) – List of records to convert. If None, uses :pyattr:`data`.

  • expand_nested_dicts (list of str or bool , optional) – List of keys to expand into separate columns, or True to expand defaults.

  • rename_columns (dict of str to str, optional) – A dictionary mapping old column names to new column names.

  • **kwargs – Additional keyword arguments passed to pd.DataFrame.

  • drop_duplicates (bool )

Returns:

DataFrame containing the metadata or None when no data is available.

Return type:

pd.DataFrame or None

Examples

>>> handler = ResultsHandler(data=[{"a": 1, "b": 2}])
>>> df = handler.to_pandas()
>>> list(df.columns)
['a', 'b']
>>> df.iloc[0]['a']
np.int64(1)
to_polars(data=None, expand_nested_dicts=False, rename_columns=None, drop_duplicates=False, **polars_kwargs)#

Convert the current metadata to a Polars DataFrame.

Parameters:

  • data (dict of int to list of dict , optional) – The paginated data to convert. If None, uses self.qs._results.

  • **polars_kwargs – Additional keyword arguments passed to pl.DataFrame.

  • expand_nested_dicts (list [str ] | bool | None)

  • rename_columns (dict [str , str ] | None)

  • drop_duplicates (bool )

Returns:

A Polars DataFrame containing the metadata.

Return type:

pl.DataFrame

Raises:

RuntimeError – If no data is available to convert.

class ResultsHandler(data=None)[source]#

Bases: object

Mixin providing methods to handle and convert paginated results. This mixin provides methods to convert paginated results into various formats such as pandas DataFrames, lists of dictionaries, JSON strings, and Polars DataFrames.

The mixin assumes the host class provides the following dependencies:

  • data: A property that returns an iterable of metadata records, typically a chain of dictionaries. This can be overridden by providing data directly to the conversion methods.

Parameters:

data (Optional[list [dict [str , Any]]])

property data: list [dict [str , Any ]]#

Get the data associated with the current instance.

get_ids(label=None)[source]#

Get a list of IDs/accessions from the current metadata.

Parameters:

label (str , optional) – The key to extract IDs from. If None, uses the default key based on the resource type.

Returns:

A list of IDs extracted from the metadata.

Return type:

list of str

Raises:

ValueError – If no data is available to extract IDs from.

to_json(data=None, orient='records', lines=True, **json_kwargs)[source]#

Convert the current metadata to a JSON string or save it to a file.

Parameters:

  • data (dict of int to list of dict , optional) – The paginated data to convert. If None, uses self.qs._results.

  • **json_kwargs – Additional keyword arguments passed to the JSON serialization function.

  • orient (str )

  • lines (bool )

Returns:

The JSON string representation of the metadata, or None if no data is available.

Return type:

str or None

Raises:

RuntimeError – If no data is available to convert.

to_list(*, data=None, drop_duplicates=False)[source]#

Convert the current or provided metadata to a list of dictionaries.

Parameters:

  • data (optional) – The paginated data to convert. If None, uses :pyattr:`data`.

  • drop_duplicates (bool , default True) – Whether to drop duplicate records from the list.

Returns:

A list of metadata records as dictionaries, or None if no data is available.

Return type:

list

Examples

>>> handler = ResultsHandler(data=[{"x": 10}])
>>> handler.to_list()
[{'x': 10}]
to_pandas(data=None, expand_nested_dicts=False, rename_columns=None, drop_duplicates=False, **kwargs)[source]#

Convert the current or provided metadata to a pandas DataFrame.

Parameters:

  • data (list of dict , optional) – List of records to convert. If None, uses :pyattr:`data`.

  • expand_nested_dicts (list of str or bool , optional) – List of keys to expand into separate columns, or True to expand defaults.

  • rename_columns (dict of str to str, optional) – A dictionary mapping old column names to new column names.

  • **kwargs – Additional keyword arguments passed to pd.DataFrame.

  • drop_duplicates (bool )

Returns:

DataFrame containing the metadata or None when no data is available.

Return type:

pd.DataFrame or None

Examples

>>> handler = ResultsHandler(data=[{"a": 1, "b": 2}])
>>> df = handler.to_pandas()
>>> list(df.columns)
['a', 'b']
>>> df.iloc[0]['a']
np.int64(1)
to_polars(data=None, expand_nested_dicts=False, rename_columns=None, drop_duplicates=False, **polars_kwargs)[source]#

Convert the current metadata to a Polars DataFrame.

Parameters:

  • data (dict of int to list of dict , optional) – The paginated data to convert. If None, uses self.qs._results.

  • **polars_kwargs – Additional keyword arguments passed to pl.DataFrame.

  • expand_nested_dicts (list [str ] | bool | None)

  • rename_columns (dict [str , str ] | None)

  • drop_duplicates (bool )

Returns:

A Polars DataFrame containing the metadata.

Return type:

pl.DataFrame

Raises:

RuntimeError – If no data is available to convert.

add_id_param_field(given_id, id_label, records)[source]#
Parameters:
add_pipeline_version_field(records)[source]#
Parameters:

records (list [dict [str , Any ]])

Contents