How to display .jmd (Julia markdown) documentation from REPL?

General Usage
1

I’m interested in using Julia markdown to document the data in a .csv file used in a health care application. After writing a simple .jmd file, I tried to display it using the REPL’s help?> mode, which replied that it couldn’t find the file (even though it is in the current directory).

What is the command to get Julia to display my .jmd documentation?

2

Hey @g2g , a little confused by what I think you are trying to achieve here. Could you give me exactly what you are imagining as an example? Is it something like:

help?> MYDATA
Fields Descriptions
- Field 1: Identifier
- Field 2: Date
...

Or what are you envisioning exactly? If you want to document datasets or variables from within a Julia package, you’ll want to document it from within your package like:

module MyPackage

    """
    This is my dataset. There are many like it
    but this is mine.
    """
    MYDATA = # Whatever this is

    export MYDATA

end

Then you could do this:

julia> using MyPackage

help?> MYDATA
    This is my dataset. There are many like it
    but this is mine.
3

I’m trying to document the data in the .csv file with the header of that .csv file. Specifically, I’m trying to define the lookup tables that are used in the .csv data. For example, a row of the .csv file might be

2024-10-20T17:21:00,0,0

where the first column is the timestamp of the measurement, the second column is the measurement type (0 for administered medication), and the third column is medication type (0 for 5 mg midodrine). I’d like the documentation in the header to define the list of possible measurement types and medication types and other types of measurement data, which may change for different .csv files.

4

Ok, let me see if I understand: you want to attach data to what each column is doing in your CSV file such that if you want to look up what a column represents within your Julia session (i.e. help?> MYDATA) you can see what that column represents as well as what potential values exist for that column. Is that right?

If so, we do something similar to this within IPUMS.jl where we have a custom loader that loads two files at once to produce one DataFrame.jl DataFrame with metadata annotations. The syntax is something like loader(data, header_data)and that gives me a DataFrame with my data and the ability to look up what each column represents and what values they can take from within my REPL.

Here’s an example of what I mean using IPUMS.jl:

julia> ddi = parse_ddi("poland_data/ipumsi_00001.xml");

julia> df = load_ipums_extract(ddi, "poland_data/ipumsi_00001.dat");

julia> for colname in names(df)
           println("$(colname):\n----------------\n\n 
           $(colmetadata(df, colname, 
           "description"))\n\n")
       end

COUNTRY:
----------------

 COUNTRY gives the country from which the sample was drawn.  The codes assigned to each country are those used by the UN Statistics Division and the ISO (International Organization for Standardization).


YEAR:
----------------

 YEAR gives the year in which the census or survey was taken. For samples that span years, the midpoint or first year of the interval is reported.


SAMPLE:
----------------

 SAMPLE identifies the IPUMS sample from which the case is drawn. Each sample receives a unique 9-digit code. The code is structured as follows:

The first 3 digits are the ISO/UN codes used in COUNTRY

The next 4 digits are the year of the census/survey

The final 2 digits identify the sample within the year.  For the last two digits, censuses or large census-like surveys have a value "0" (e.g, 01) in the second-to-last digit, household surveys have a value of "2" (e.g., 21), and employment surveys have a value of "4" (e.g., 41).

# Other information

If you want to do something like that, I would strongly suggest the DataFrames.jl MetaData API here: Metadata · DataFrames.jl Hopefully that helps – let me know your thoughts. Also, if there are specific health informatics nuances to this question, feel free to ask on the Julia Slack in the #health-and-medicine channel as that is where members of JuliaHealth hangs out – others may be able to help better depending on your need.

5

Thanks. if I need to use a second file, I’ll look closely at your suggestion of using DataFrames.jl. Currently, I’m trying to understand the capabilities of .jmd and I’m hoping to have the lookup table definitions and the .csv data in a single file.

Although it would be a convenience to be able to display the .jmd file from the REPL, perhaps that is not yet implemented.

6

Hmm… Yea, a .jmd file doesn’t do what you want here.

Out of curiosity, could you give a full example of what you would want your REPL to display? It doesn’t have to be real info or anything, just an example of what you would want to see in an ideal world.

Could you also provide an example of the single file you have that has the information you want to encode?

I can try tinkering with an example of what you are imagining.

7

With my novice-level understanding of .jmd, I think (perhaps incorrectly) that .jmd is a superset of .md, which can format lists. And I think lists are enough to document the .csv file’s lookup tables.

My question may have been overly specific. If I were to ask it again, I would ask something more general: “How to display .md (markdown) documentation from REPL?”

I’m designing the .csv file to handle about 50 different measurement types. Currently the work is more “nuts and bolts” and not needing much tinkering. However, once this foundational work is done, there will be plenty of tinkering (e.g., can causal relationships be found between the measurement types?).